Cache not yet supported for views
Caching does not currently work with database views. This is a temporary limitation.
Drizzle · PostgreSQL · 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 (global: false), meaning nothing is cached unless explicitly requested. This prevents hidden performance traps and surprises in applications. Drizzle sends every query straight to the database by default with no automatic caching or invalidation.
Cache global mode enables all queries to be cached
Setting global: true enables caching for all select queries by default, causing every select to look in cache first before querying the database.
upstashCache configuration
The upstashCache() helper accepts the following options: url (Upstash URL, optional if env var set), token (Upstash token, optional if env var set), global (boolean to enable caching for all queries, optional), and config (default cache behavior with options like ex for expiration in seconds, optional).
CacheConfig type for Upstash
CacheConfig for Upstash contains: ex (expiration in seconds, positive integer, optional) and hexOptions (options for HEXPIRE command supporting values 'NX', 'nx', 'XX', 'xx', 'GT', 'gt', 'LT', 'lt', optional).
$withCache() method for opt-in caching
In explicit caching mode (global: false), call .$withCache() on a select query to enable caching for that specific query. This method accepts options: config (to rewrite cache configuration), tag (custom cache key instead of hashing query+params), and autoInvalidate (boolean to enable/disable auto-invalidation, defaults to true).
$withCache(false) to disable cache for specific query
In global caching mode (global: true), call .$withCache(false) on a specific query to disable cache for that query only.
db.$cache.invalidate() method
The db.$cache.invalidate() method accepts an object with either 'tables' or 'tags' key. The tables parameter accepts a single table object/string or array of table objects/strings to invalidate all queries using those tables. The tags parameter accepts a single string or array of strings to invalidate queries with specific tags.
Custom cache implementation with Cache class
Custom cache implementations extend the Cache class and must implement four methods: strategy() returning 'explicit' or 'all', get(key: string) returning Promise<any[] | undefined>, put(key: string, response: any, tables: string[], isTag?: boolean, config?: CacheConfig) for storing cached data, and onMutate(params: {tags: string | string[], tables: string | string[] | Table<any> | Table<any>[]}) called during mutations for invalidation.
CacheConfig type for custom cache
CacheConfig for custom cache implementations contains: ex (expiration in seconds, optional), px (expiration in milliseconds, optional), exat (Unix time in seconds when key expires, optional), pxat (Unix time in milliseconds when key expires, optional), keepTtl (retain existing TTL when updating a key, optional), and hexOptions (options for HEXPIRE supporting 'NX', 'XX', 'GT', 'LT' in any case, optional).
autoInvalidate false leads to eventual consistency
When .$withCache({ autoInvalidate: false }) is used, the cache is not invalidated immediately when mutations occur on related tables. The cached data remains stale until the TTL expires naturally, allowing for eventual consistency. This is useful for data that doesn't change often and slight staleness is acceptable, or when manual cache invalidation is preferred.
Cache does not work with raw queries
Caching is not supported with raw SQL queries executed via db.execute(sql`...`).
Cache does not work in transactions
Caching is not supported when queries are executed inside db.transaction() blocks.
Cache not yet supported for Relational Queries
Caching does not currently work with Drizzle Relational Queries such as db.query.users.findMany(). This is a temporary limitation that will be handled in the future.
Cache not yet supported for AWS Data API drivers
Caching does not currently work with AWS Data API drivers. This is a temporary limitation.
upstashCache example with opt-in caching
Example of using upstashCache with opt-in caching (global: false): import { upstashCache } from 'drizzle-orm/cache/upstash'; import { drizzle } from 'drizzle-orm/...'; const db = drizzle(process.env.DB_URL!, { cache: upstashCache({ url: '', token: '' }), }); const res = await db.select().from(users).$withCache(); Queries without .$withCache() will not use cache.
upstashCache example with global caching enabled
Example of using upstashCache with global caching enabled: 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); All queries will check cache by default.
upstashCache example with custom configuration
Example of upstashCache with custom credentials and options: import { upstashCache } from 'drizzle-orm/cache/upstash'; import { drizzle } from 'drizzle-orm/...'; const db = drizzle(process.env.DB_URL!, { cache: upstashCache({ url: '<UPSTASH_URL>', token: '<UPSTASH_TOKEN>', global: true, config: { ex: 60 } }) });
Mutation operations trigger cache invalidation by default
Any mutate operation (insert, update, delete) will trigger the cache's onMutate handler and attempt to invalidate cached queries that involved the affected tables, unless autoInvalidate is explicitly disabled.