Cache (#4447)

Co-authored-by: Cahid Arda Öz <cahidardaooz@gmail.com>

Author: AndriiSherman

.github/workflows/release-feature-branch.yaml

@@ -237,7 +237,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.18'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - uses: pnpm/action-setup@v3
@@ -334,7 +334,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.18'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - uses: pnpm/action-setup@v3
@@ -415,4 +415,4 @@ jobs:
         working-directory: ${{ matrix.package }}
         shell: bash
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}

.github/workflows/release-latest.yaml

@@ -360,7 +360,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.18'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - uses: pnpm/action-setup@v3

.github/workflows/unpublish-release-feature-branch.yaml

@@ -21,7 +21,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.18'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Unpublish

.nvmrc

@@ -1 +1 @@
-18.18
+22

changelogs/drizzle-orm/0.44.0.md

@@ -0,0 +1,91 @@
+## Error handling
+
+Starting from this version, we’ve introduced a new `DrizzleQueryError` that wraps all errors from database drivers and provides a set of useful information:
+
+1. A proper stack trace to identify which exact `Drizzle` query failed
+2. The generated SQL string and its parameters
+3. The original stack trace from the driver that caused the DrizzleQueryError
+
+## Drizzle `cache` module
+
+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.
+
+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.
+
+Out first native integration was built together with Upstash team and let you natively use `upstash` as a cache for your drizzle queries
+
+```ts
+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 }
+  })
+});
+```
+
+You can also implement your own cache, as Drizzle exposes all the necessary APIs, such as get, put, mutate, etc.
+You can find full implementation details on the [website](https://orm.drizzle.team/docs/cache#custom-cache)
+
+```ts
+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> {
+    ...
+  }
+  // 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> {
+    ...
+  }
+  // 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> {
+    ...
+  }
+}
+```
+
+For more usage example you can check our [docs](https://orm.drizzle.team/docs/cache#cache-usage-examples)

drizzle-orm/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "drizzle-orm",
-	"version": "0.43.1",
+	"version": "0.44.0",
 	"description": "Drizzle ORM package for SQL databases",
 	"type": "module",
 	"scripts": {
@@ -64,14 +64,15 @@
 		"better-sqlite3": ">=7",
 		"bun-types": "*",
 		"expo-sqlite": ">=14.0.0",
-		"gel": ">=2",
 		"knex": "*",
 		"kysely": "*",
 		"mysql2": ">=2",
 		"pg": ">=8",
 		"postgres": ">=3",
 		"sql.js": ">=1",
-		"sqlite3": ">=5"
+		"sqlite3": ">=5",
+		"gel": ">=2",
+		"@upstash/redis": ">=1.34.7"
 	},
 	"peerDependenciesMeta": {
 		"mysql2": {
@@ -157,6 +158,9 @@
 		},
 		"@prisma/client": {
 			"optional": true
+		},
+		"@upstash/redis": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
@@ -173,11 +177,12 @@
 		"@planetscale/database": "^1.16.0",
 		"@prisma/client": "5.14.0",
 		"@tidbcloud/serverless": "^0.1.1",
-		"@types/better-sqlite3": "^7.6.4",
+		"@types/better-sqlite3": "^7.6.12",
 		"@types/node": "^20.2.5",
 		"@types/pg": "^8.10.1",
 		"@types/react": "^18.2.45",
 		"@types/sql.js": "^1.4.4",
+		"@upstash/redis": "^1.34.3",
 		"@vercel/postgres": "^0.8.0",
 		"@xata.io/client": "^0.29.3",
 		"better-sqlite3": "^11.9.1",

drizzle-orm/src/aws-data-api/pg/driver.ts

@@ -21,6 +21,7 @@ import { AwsDataApiSession } from './session.ts';
 
 export interface PgDriverOptions {
 	logger?: Logger;
+	cache?: Cache;
 	database: string;
 	resourceArn: string;
 	secretArn: string;
@@ -118,9 +119,13 @@ function construct<TSchema extends Record<string, unknown> = Record<string, neve
 		};
 	}
 
-	const session = new AwsDataApiSession(client, dialect, schema, { ...config, logger }, undefined);
+	const session = new AwsDataApiSession(client, dialect, schema, { ...config, logger, cache: config.cache }, undefined);
 	const db = new AwsDataApiPgDatabase(dialect, session, schema as any);
 	(<any> db).$client = client;
+	(<any> db).$cache = config.cache;
+	if ((<any> db).$cache) {
+		(<any> db).$cache['invalidate'] = config.cache?.onMutate;
+	}
 
 	return db as any;
 }

drizzle-orm/src/aws-data-api/pg/session.ts

@@ -5,6 +5,9 @@ import {
 	ExecuteStatementCommand,
 	RollbackTransactionCommand,
 } from '@aws-sdk/client-rds-data';
+import type { Cache } from '~/cache/core/cache.ts';
+import { NoopCache } from '~/cache/core/cache.ts';
+import type { WithCacheConfig } from '~/cache/core/types.ts';
 import { entityKind } from '~/entity.ts';
 import type { Logger } from '~/logger.ts';
 import {
@@ -33,17 +36,23 @@ export class AwsDataApiPreparedQuery<
 
 	constructor(
 		private client: AwsDataApiClient,
-		queryString: string,
+		private queryString: string,
 		private params: unknown[],
 		private typings: QueryTypingsValue[],
 		private options: AwsDataApiSessionOptions,
+		cache: Cache,
+		queryMetadata: {
+			type: 'select' | 'update' | 'delete' | 'insert';
+			tables: string[];
+		} | undefined,
+		cacheConfig: WithCacheConfig | undefined,
 		private fields: SelectedFieldsOrdered | undefined,
 		/** @internal */
 		readonly transactionId: string | undefined,
 		private _isResponseInArrayMode: boolean,
 		private customResultMapper?: (rows: unknown[][]) => T['execute'],
 	) {
-		super({ sql: queryString, params });
+		super({ sql: queryString, params }, cache, queryMetadata, cacheConfig);
 		this.rawQuery = new ExecuteStatementCommand({
 			sql: queryString,
 			parameters: [],
@@ -108,7 +117,9 @@ export class AwsDataApiPreparedQuery<
 
 		this.options.logger?.logQuery(this.rawQuery.input.sql!, this.rawQuery.input.parameters);
 
-		const result = await this.client.send(this.rawQuery);
+		const result = await this.queryWithCache(this.queryString, params, async () => {
+			return await this.client.send(this.rawQuery);
+		});
 		const rows = result.records?.map((row) => {
 			return row.map((field) => getValueFromDataApi(field));
 		}) ?? [];
@@ -139,6 +150,7 @@ export class AwsDataApiPreparedQuery<
 
 export interface AwsDataApiSessionOptions {
 	logger?: Logger;
+	cache?: Cache;
 	database: string;
 	resourceArn: string;
 	secretArn: string;
@@ -158,6 +170,7 @@ export class AwsDataApiSession<
 
 	/** @internal */
 	readonly rawQuery: AwsDataApiQueryBase;
+	private cache: Cache;
 
 	constructor(
 		/** @internal */
@@ -174,6 +187,7 @@ export class AwsDataApiSession<
 			resourceArn: options.resourceArn,
 			database: options.database,
 		};
+		this.cache = options.cache ?? new NoopCache();
 	}
 
 	prepareQuery<
@@ -188,6 +202,8 @@ export class AwsDataApiSession<
 		name: string | undefined,
 		isResponseInArrayMode: boolean,
 		customResultMapper?: (rows: unknown[][]) => T['execute'],
+		queryMetadata?: { type: 'select' | 'update' | 'delete' | 'insert'; tables: string[] },
+		cacheConfig?: WithCacheConfig,
 		transactionId?: string,
 	): AwsDataApiPreparedQuery<T> {
 		return new AwsDataApiPreparedQuery(
@@ -196,6 +212,9 @@ export class AwsDataApiSession<
 			query.params,
 			query.typings ?? [],
 			this.options,
+			this.cache,
+			queryMetadata,
+			cacheConfig,
 			fields,
 			transactionId ?? this.transactionId,
 			isResponseInArrayMode,
@@ -210,6 +229,8 @@ export class AwsDataApiSession<
 			undefined,
 			false,
 			undefined,
+			undefined,
+			undefined,
 			this.transactionId,
 		).execute();
 	}

drizzle-orm/src/better-sqlite3/driver.ts

@@ -29,7 +29,7 @@ export class BetterSQLite3Database<TSchema extends Record<string, unknown> = Rec
 
 function construct<TSchema extends Record<string, unknown> = Record<string, never>>(
 	client: Database,
-	config: DrizzleConfig<TSchema> = {},
+	config: Omit<DrizzleConfig<TSchema>, 'cache'> = {},
 ): BetterSQLite3Database<TSchema> & {
 	$client: Database;
 } {
@@ -57,6 +57,10 @@ function construct<TSchema extends Record<string, unknown> = Record<string, neve
 	const session = new BetterSQLiteSession(client, dialect, schema, { logger });
 	const db = new BetterSQLite3Database('sync', dialect, session, schema);
 	(<any> db).$client = client;
+	// (<any> db).$cache = config.cache;
+	// if ((<any> db).$cache) {
+	// 	(<any> db).$cache['invalidate'] = config.cache?.onMutate;
+	// }
 
 	return db as any;
 }