|
| 1 | +## Error handling |
| 2 | + |
| 3 | +Starting from this version, we’ve introduced a new `DrizzleQueryError` that wraps all errors from database drivers and provides a set of useful information: |
| 4 | + |
| 5 | +1. A proper stack trace to identify which exact `Drizzle` query failed |
| 6 | +2. The generated SQL string and its parameters |
| 7 | +3. The original stack trace from the driver that caused the DrizzleQueryError |
| 8 | + |
| 9 | +## Drizzle `cache` module |
| 10 | + |
| 11 | +Drizzle sends every query straight to your database by default. There are no hidden actions, no automatic caching or invalidation - you’ll always see exactly what runs. If you want caching, you must opt in. |
| 12 | + |
| 13 | +By default, Drizzle uses a explicit caching strategy (i.e. `global: false`), so nothing is ever cached unless you ask. This prevents surprises or hidden performance traps in your application. Alternatively, you can flip on all caching (global: true) so that every select will look in cache first. |
| 14 | + |
| 15 | +Out first native integration was built together with Upstash team and let you natively use `upstash` as a cache for your drizzle queries |
| 16 | + |
| 17 | +```ts |
| 18 | +import { upstashCache } from "drizzle-orm/cache/upstash"; |
| 19 | +import { drizzle } from "drizzle-orm/..."; |
| 20 | + |
| 21 | +const db = drizzle(process.env.DB_URL!, { |
| 22 | + cache: upstashCache({ |
| 23 | + // 👇 Redis credentials (optional — can also be pulled from env vars) |
| 24 | + url: '<UPSTASH_URL>', |
| 25 | + token: '<UPSTASH_TOKEN>', |
| 26 | + // 👇 Enable caching for all queries by default (optional) |
| 27 | + global: true, |
| 28 | + // 👇 Default cache behavior (optional) |
| 29 | + config: { ex: 60 } |
| 30 | + }) |
| 31 | +}); |
| 32 | +``` |
| 33 | + |
| 34 | +You can also implement your own cache, as Drizzle exposes all the necessary APIs, such as get, put, mutate, etc. |
| 35 | +You can find full implementation details on the [website](https://orm.drizzle.team/docs/cache#custom-cache) |
| 36 | + |
| 37 | +```ts |
| 38 | +import Keyv from "keyv"; |
| 39 | +export class TestGlobalCache extends Cache { |
| 40 | + private globalTtl: number = 1000; |
| 41 | + // This object will be used to store which query keys were used |
| 42 | + // for a specific table, so we can later use it for invalidation. |
| 43 | + private usedTablesPerKey: Record<string, string[]> = {}; |
| 44 | + constructor(private kv: Keyv = new Keyv()) { |
| 45 | + super(); |
| 46 | + } |
| 47 | + // For the strategy, we have two options: |
| 48 | + // - 'explicit': The cache is used only when .$withCache() is added to a query. |
| 49 | + // - 'all': All queries are cached globally. |
| 50 | + // The default behavior is 'explicit'. |
| 51 | + override strategy(): "explicit" | "all" { |
| 52 | + return "all"; |
| 53 | + } |
| 54 | + // This function accepts query and parameters that cached into key param, |
| 55 | + // allowing you to retrieve response values for this query from the cache. |
| 56 | + override async get(key: string): Promise<any[] | undefined> { |
| 57 | + ... |
| 58 | + } |
| 59 | + // This function accepts several options to define how cached data will be stored: |
| 60 | + // - 'key': A hashed query and parameters. |
| 61 | + // - 'response': An array of values returned by Drizzle from the database. |
| 62 | + // - 'tables': An array of tables involved in the select queries. This information is needed for cache invalidation. |
| 63 | + // |
| 64 | + // For example, if a query uses the "users" and "posts" tables, you can store this information. Later, when the app executes |
| 65 | + // any mutation statements on these tables, you can remove the corresponding key from the cache. |
| 66 | + // If you're okay with eventual consistency for your queries, you can skip this option. |
| 67 | + override async put( |
| 68 | + key: string, |
| 69 | + response: any, |
| 70 | + tables: string[], |
| 71 | + config?: CacheConfig, |
| 72 | + ): Promise<void> { |
| 73 | + ... |
| 74 | + } |
| 75 | + // This function is called when insert, update, or delete statements are executed. |
| 76 | + // You can either skip this step or invalidate queries that used the affected tables. |
| 77 | + // |
| 78 | + // The function receives an object with two keys: |
| 79 | + // - 'tags': Used for queries labeled with a specific tag, allowing you to invalidate by that tag. |
| 80 | + // - 'tables': The actual tables affected by the insert, update, or delete statements, |
| 81 | + // helping you track which tables have changed since the last cache update. |
| 82 | + override async onMutate(params: { |
| 83 | + tags: string | string[]; |
| 84 | + tables: string | string[] | Table<any> | Table<any>[]; |
| 85 | + }): Promise<void> { |
| 86 | + ... |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +For more usage example you can check our [docs](https://orm.drizzle.team/docs/cache#cache-usage-examples) |
0 commit comments