Drizzle 默认会将每个查询直接发送到数据库。没有隐藏操作，没有自动缓存或失效——您将始终准确看到运行了什么。如果您需要缓存，则必须选择启用。
默认情况下，Drizzle 使用 `explicit` 缓存策略（即 `global: false`），因此除非您要求，否则绝不会缓存任何内容。这可以防止应用程序中出现意外或隐藏的性能陷阱。或者，您可以打开 `all` 缓存（`global: true`），这样每个 select 都会首先查找缓存。
Drizzle 提供了一个开箱即用的 `upstashCache()` 辅助函数。默认情况下，如果设置了环境变量，它将使用 Upstash Redis 进行自动配置。
import { upstashCache } from "drizzle-orm/cache/upstash";
import { drizzle } from "drizzle-orm/...";
const db = drizzle(process.env.DB_URL!, {
cache: upstashCache(),
});您还可以显式定义您的 Upstash 凭据，默认启用所有查询的全局缓存，或传递自定义缓存选项
import { upstashCache } from "drizzle-orm/cache/upstash";
import { drizzle } from "drizzle-orm/...";
const db = drizzle(process.env.DB_URL!, {
cache: upstashCache({
// 👇 Redis credentials (optional — can also be pulled from env vars)
url: '<UPSTASH_URL>',
token: '<UPSTASH_TOKEN>',
// 👇 Enable caching for all queries by default (optional)
global: true,
// 👇 Default cache behavior (optional)
config: { ex: 60 }
})
});Drizzle 支持 Upstash 的以下缓存配置选项
export type CacheConfig = {
/**
* Expiration in seconds (positive integer)
*/
ex?: number;
/**
* Set an expiration (TTL or time to live) on one or more fields of a given hash key.
* Used for HEXPIRE command
*/
hexOptions?: "NX" | "nx" | "XX" | "xx" | "GT" | "gt" | "LT" | "lt";
};配置缓存后，缓存的行为如下
情况 1：Drizzle 使用 `global: false`（默认，选择性缓存）
import { upstashCache } from "drizzle-orm/cache/upstash";
import { drizzle } from "drizzle-orm/...";
const db = drizzle(process.env.DB_URL!, {
// 👇 `global: true` is not passed, false by default
cache: upstashCache({ url: "", token: "" }),
});在这种情况下，以下查询不会从缓存中读取
const res = await db.select().from(users);
// Any mutate operation will still trigger the cache's onMutate handler
// and attempt to invalidate any cached queries that involved the affected tables
await db.insert(users).value({ email: "[email protected]" });要使此查询从缓存中读取，请调用 `.$withCache()`
const res = await db.select().from(users).$withCache();`.$withCache` 有一组选项，您可以用来管理和配置此特定查询策略
// rewrite the config for this specific query
.$withCache({ config: {} })
// give this query a custom cache key (instead of hashing query+params under the hood)
.$withCache({ tag: 'custom_key' })
// turn off auto-invalidation for this query
// note: this leads to eventual consistency (explained below)
.$withCache({ autoInvalidate: false })最终一致性示例
此示例仅在您手动设置 `autoInvalidate: false` 时才相关。默认情况下，`autoInvalidate` 是启用的。
您可能希望关闭 `autoInvalidate`，如果
在这些情况下，关闭它可以减少不必要的缓存失效。但是，在大多数情况下，我们建议保持默认启用。
示例：假设您将 `usersTable` 上的以下查询缓存，TTL 为 3 秒
const recent = await db
.select().from(usersTable)
.$withCache({ config: { ex: 3 }, autoInvalidate: false });如果有人运行 `db.insert(usersTable)...`，缓存不会立即失效。在长达 3 秒的时间内，您将继续看到旧数据，直到最终达到一致性。
情况 2：Drizzle 使用 `global: true` 选项
import { upstashCache } from "drizzle-orm/cache/upstash";
import { drizzle } from "drizzle-orm/...";
const db = drizzle(process.env.DB_URL!, {
cache: upstashCache({ url: "", token: "", global: true }),
});在这种情况下，以下查询将从缓存中读取
const res = await db.select().from(users);如果要为此特定查询禁用缓存，请调用 `.$withCache(false)`
// disable cache for this query
const res = await db.select().from(users).$withCache(false);您还可以使用来自 `db` 的缓存实例来使特定表或标签失效
// Invalidate all queries that use the `users` table. You can do this with the Drizzle instance.
await db.$cache.invalidate({ tables: users });
// or
await db.$cache.invalidate({ tables: [users, posts] });
// Invalidate all queries that use the `usersTable`. You can do this by using just the table name.
await db.$cache.invalidate({ tables: "usersTable" });
// or
await db.$cache.invalidate({ tables: ["usersTable", "postsTable"] });
// You can also invalidate custom tags defined in any previously executed select queries.
await db.$cache.invalidate({ tags: "custom_key" });
// or
await db.$cache.invalidate({ tags: ["custom_key", "custom_key1"] });此示例展示了如何在 Drizzle 中插入自定义 `cache`：您提供函数以从缓存中获取数据、将结果存储回缓存以及在运行变更操作时使条目失效。
缓存扩展提供以下配置选项
export type CacheConfig = {
/** expire time, in seconds */
ex?: number;
/** expire time, in milliseconds */
px?: number;
/** Unix time (sec) at which the key will expire */
exat?: number;
/** Unix time (ms) at which the key will expire */
pxat?: number;
/** retain existing TTL when updating a key */
keepTtl?: boolean;
/** options for HEXPIRE (hash-field TTL) */
hexOptions?: 'NX' | 'XX' | 'GT' | 'LT' | 'nx' | 'xx' | 'gt' | 'lt';
};const db = drizzle(process.env.DB_URL!, { cache: new TestGlobalCache() });import Keyv from "keyv";
export class TestGlobalCache extends Cache {
private globalTtl: number = 1000;
// This object will be used to store which query keys were used
// for a specific table, so we can later use it for invalidation.
private usedTablesPerKey: Record<string, string[]> = {};
constructor(private kv: Keyv = new Keyv()) {
super();
}
// For the strategy, we have two options:
// - 'explicit': The cache is used only when .$withCache() is added to a query.
// - 'all': All queries are cached globally.
// The default behavior is 'explicit'.
override strategy(): "explicit" | "all" {
return "all";
}
// This function accepts query and parameters that cached into key param,
// allowing you to retrieve response values for this query from the cache.
override async get(key: string): Promise<any[] | undefined> {
const res = (await this.kv.get(key)) ?? undefined;
return res;
}
// This function accepts several options to define how cached data will be stored:
// - 'key': A hashed query and parameters.
// - 'response': An array of values returned by Drizzle from the database.
// - 'tables': An array of tables involved in the select queries. This information is needed for cache invalidation.
//
// For example, if a query uses the "users" and "posts" tables, you can store this information. Later, when the app executes
// any mutation statements on these tables, you can remove the corresponding key from the cache.
// If you're okay with eventual consistency for your queries, you can skip this option.
override async put(
key: string,
response: any,
tables: string[],
config?: CacheConfig,
): Promise<void> {
await this.kv.set(key, response, config ? config.ex : this.globalTtl);
for (const table of tables) {
const keys = this.usedTablesPerKey[table];
if (keys === undefined) {
this.usedTablesPerKey[table] = [key];
} else {
keys.push(key);
}
}
}
// This function is called when insert, update, or delete statements are executed.
// You can either skip this step or invalidate queries that used the affected tables.
//
// The function receives an object with two keys:
// - 'tags': Used for queries labeled with a specific tag, allowing you to invalidate by that tag.
// - 'tables': The actual tables affected by the insert, update, or delete statements,
// helping you track which tables have changed since the last cache update.
override async onMutate(params: {
tags: string | string[];
tables: string | string[] | Table<any> | Table<any>[];
}): Promise<void> {
const tagsArray = params.tags
? Array.isArray(params.tags)
? params.tags
: [params.tags]
: [];
const tablesArray = params.tables
? Array.isArray(params.tables)
? params.tables
: [params.tables]
: [];
const keysToDelete = new Set<string>();
for (const table of tablesArray) {
const tableName = is(table, Table)
? getTableName(table)
: (table as string);
const keys = this.usedTablesPerKey[tableName] ?? [];
for (const key of keys) keysToDelete.add(key);
}
if (keysToDelete.size > 0 || tagsArray.length > 0) {
for (const tag of tagsArray) {
await this.kv.delete(tag);
}
for (const key of keysToDelete) {
await this.kv.delete(key);
for (const table of tablesArray) {
const tableName = is(table, Table)
? getTableName(table)
: (table as string);
this.usedTablesPerKey[tableName] = [];
}
}
}
}
}db.execute(sql`select 1`);db.batch([
db.insert(users).values(...),
db.update(users).set(...).where()
])await db.transaction(async (tx) => {
await tx.update(accounts).set(...).where(...);
await tx.update...
});await db.query.users.findMany();