Cache invalidation by tags
Use db.$cache.invalidate({ tags: 'custom_key' }) or db.$cache.invalidate({ tags: ['custom_key', 'custom_key1'] }) to invalidate all queries that were cached with specific custom tags.
Drizzle · SQLite · all subjects
cache
19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Drizzle cache default behavior
By default, Drizzle uses an explicit caching strategy where global is false. Nothing is cached unless explicitly requested via .$withCache(). This prevents hidden performance traps and surprises in applications.
Drizzle cache global strategy
Drizzle supports a global caching strategy where global is true. When enabled, every select query will look in the cache first before querying the database.
Upstash cache configuration example
To use Upstash Redis with Drizzle, import upstashCache from 'drizzle-orm/cache/upstash' and pass it to the drizzle function: const db = drizzle(process.env.DB_URL!, { cache: upstashCache({ token: process.env.UPSTASH_TOKEN, url: process.env.UPSTASH_URL }) });
Upstash cache config options
Upstash cache supports the following CacheConfig options: ex (number, optional) - expiration in seconds as a positive integer; hexOptions (string, optional) - set TTL on hash fields with values 'NX', 'nx', 'XX', 'xx', 'GT', 'gt', 'LT', or 'lt' for HEXPIRE command.
withCache method with explicit strategy
With global: false (default), use .$withCache() on a select query to enable caching for that specific query. The method accepts options: config to override cache config, tag for custom cache keys, and autoInvalidate (boolean) to control cache invalidation on mutations.
withCache method with global strategy
With global: true, all queries are cached by default. Use .$withCache(false) on a specific query to disable caching for just that query.
autoInvalidate cache option behavior
By default, autoInvalidate is enabled and cache entries are automatically invalidated when mutations occur on their tables. When autoInvalidate is false, cache entries remain valid until TTL expires, leading to eventual consistency. This is useful for data that changes infrequently like product listings or blog posts.
Cache invalidation by tables
Use db.$cache.invalidate({ tables: users }) or db.$cache.invalidate({ tables: [users, posts] }) to invalidate all queries using specific table objects. Alternatively, use string table names: db.$cache.invalidate({ tables: 'usersTable' }) or db.$cache.invalidate({ tables: ['usersTable', 'postsTable'] }).
Custom cache config options
Custom cache implementations support the following CacheConfig options: ex (number, optional) - expire time in seconds; px (number, optional) - expire time in milliseconds; exat (number, optional) - Unix time in seconds when key expires; pxat (number, optional) - Unix time in milliseconds when key expires; keepTtl (boolean, optional) - retain existing TTL when updating a key; hexOptions (string, optional) - options for HEXPIRE with values 'NX', 'XX', 'GT', 'LT', 'nx', 'xx', 'gt', or 'lt'.
Custom cache class implementation
To implement a custom cache, extend the Cache class and override: strategy() to return 'explicit' or 'all'; get(key) to retrieve cached data; put(key, response, tables, isTag, config) to store data; onMutate(params) to handle invalidation when mutations occur.
Cache strategy method return values
The strategy() method in a custom cache implementation must return either 'explicit' (cache used only with .$withCache()) or 'all' (all queries cached globally). The default behavior is 'explicit'.
Cache put method parameters
The put() method signature is: put(key: string, response: any, tables: string[], isTag: boolean = false, config?: CacheConfig). The key is a hashed query and parameters. Response is an array of values from the database. Tables are table names involved in the query for invalidation. isTag indicates if the entry uses tag-based invalidation. Config provides TTL and expiration options.
Cache onMutate parameters
The onMutate() method receives an object with two keys: tags (string or string array) for tag-based invalidation, and tables (string, string array, Table object, or Table array) representing tables affected by insert/update/delete statements.
Cache incompatibility with raw queries
The cache extension does not work with raw SQL queries such as db.all(sql`select 1`). Raw queries will not be cached or have their results managed by the cache system.
Cache incompatibility with batch queries
The cache extension does not work with the batch feature in d1 and libsql. Queries executed through db.batch() will bypass the cache.
Cache incompatibility with transactions
The cache extension does not work with transactions. Queries executed within db.transaction() blocks will bypass the cache system.
Cache temporary limitations
The following features do not yet support caching: Drizzle Relational Queries (db.query.users.findMany()), better-sqlite3 driver, Durable Objects, expo sqlite, and views. These limitations are temporary and will be addressed in future versions.
Cache mutation auto-invalidation behavior
By default, any insert, update, or delete statement triggers the cache's onMutate handler which automatically invalidates cached queries involving the affected tables. This ensures consistency but can be disabled per-query with autoInvalidate: false.