@drizzle-adapter/d1 1.1.1 → 2.0.0

package/README.md

@@ -60,33 +60,43 @@ await client.run(sql`SELECT * FROM users`);
 ```
 
 ### Transaction Compatibility
-**Important**: Cloudflare D1 does not support real SQL transactions. This adapter provides a compatibility layer that allows transaction-based code to run without modifications, but **without transaction guarantees**:
+**Breaking in 2.0.0**: Cloudflare D1 has no interactive transactions. `transaction()` now throws `D1TransactionUnsupportedError` instead of running the callback without atomicity. The callback is never invoked.
 
 ```typescript
-// This code will run without errors, but operations are NOT atomic
-await client.transaction(async (tx) => {
-  await tx.insert(users).values({ name: 'John' });
-  await tx.update(posts).set({ published: 1 });
-  // If an error occurs here, previous operations will NOT be rolled back
-});
+import { D1TransactionUnsupportedError } from '@drizzle-adapter/d1';
+
+try {
+  await client.transaction(async (tx) => { /* never runs */ });
+} catch (caughtError) {
+  if (caughtError instanceof D1TransactionUnsupportedError) {
+    // use db.batch() instead
+  }
+}
 ```
 
-**For atomic operations**, use D1's batch API directly:
+**For atomic operations**, use `db.batch()`. It runs as one implicit SQL transaction (all-or-nothing):
 
 ```typescript
-// This provides atomic execution - all succeed or all fail
+import { sql } from 'drizzle-orm';
+
 const results = await client.batch([
-  client.insert(users).values({ name: 'John' }).prepare(),
-  client.update(posts).set({ published: 1 }).prepare()
+  client.insert(users).values({ name: 'John' }),
+  client.run(sql`UPDATE posts SET published = 1 WHERE id = ${postId}`)
 ]);
 ```
 
 ### Migration Considerations
-- **Transaction Compatibility**: Existing code using `db.transaction()` will work without modification
+- **Transaction Compatibility**: Since 2.0.0, `db.transaction()` throws `D1TransactionUnsupportedError`; migrate to `db.batch()`
 - **No Rollback**: Failed operations cannot be automatically rolled back
 - **Batch Operations**: Use `db.batch()` for operations that require atomicity
 - **Error Handling**: Implement manual cleanup logic for critical operations
 
+### Releasing
+```bash
+pnpm check && pnpm lint && pnpm test
+pnpm --filter @drizzle-adapter/d1 publish --access public   # run from the repo root
+```
+
 ## Usage
 
 ### Cloudflare Workers Setup

package/dist/Adapter/D1DrizzleConnection.js

@@ -1,4 +1,5 @@
 import { drizzle } from 'drizzle-orm/d1';
+import { D1TransactionUnsupportedError } from '../Error/D1TransactionUnsupportedError.js';
 /**
  * D1 connection implementation for Drizzle ORM.
  * Manages database connections and provides client access for D1 databases.
@@ -15,14 +16,16 @@ export class D1DrizzleConnection {
         const database = drizzle(driver);
         database.execute =
             database.run;
-        // Override transaction method to provide transaction-like behavior
-        // Since D1 doesn't support real transactions, we pass the original client
-        // Users can implement their own batching if needed for atomicity
-        database.transaction = async (callback) => {
-            // For now, just pass the original client - no transaction isolation
-            // This allows code to work without modifications while being explicit about the limitation
-            return await callback(database);
-        };
+        /**
+         * Replaces drizzle's transaction. drizzle-orm d1/session.js transaction() issues raw `begin`, which D1 rejects (probe in 1TS-Monorepo#4023).
+         * The callback is never run; callers must use batch().
+         * @returns {Promise<never>} Always rejects with D1TransactionUnsupportedError.
+         */
+        database.transaction =
+            async () => {
+                // `return await` satisfies both require-await and the no-bare-throw lint rules
+                return await Promise.reject(new D1TransactionUnsupportedError());
+            };
         this.client = database;
     }
     /**

package/dist/Error/D1TransactionUnsupportedError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thrown by transaction() on a D1 client. D1 has no interactive transactions,
+ * so the callback could not run atomically.
+ */
+export declare class D1TransactionUnsupportedError extends Error {
+    /**
+     * Constructor.
+     */
+    constructor();
+}

package/dist/Error/D1TransactionUnsupportedError.js

@@ -0,0 +1,13 @@
+/**
+ * Thrown by transaction() on a D1 client. D1 has no interactive transactions,
+ * so the callback could not run atomically.
+ */
+export class D1TransactionUnsupportedError extends Error {
+    /**
+     * Constructor.
+     */
+    constructor() {
+        super('D1 has no interactive transactions, so transaction() would run your callback without atomicity. Use db.batch([...]) instead: it is atomic (one implicit SQL transaction, all-or-nothing). Wrap raw SQL as db.run(sql`...`) inside the batch.');
+        this.name = 'D1TransactionUnsupportedError';
+    }
+}

package/dist/Interface/D1DrizzleClientInterface.d.ts

@@ -13,5 +13,6 @@ export interface D1DrizzleClientInterface extends DrizzleClientInterface {
     selectDistinct(...args: any[]): ReturnType<AnyD1Database['selectDistinct']>;
     update(...args: any[]): ReturnType<AnyD1Database['update']>;
     insert(...args: any[]): ReturnType<AnyD1Database['insert']>;
-    transaction(...args: any[]): ReturnType<AnyD1Database['transaction']>;
+    /** Always rejects with D1TransactionUnsupportedError — use batch(). */
+    transaction(...args: unknown[]): Promise<never>;
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { D1DrizzleAdapterFactory } from './Factory/D1DrizzleAdapterFactory.js';
 export { D1DrizzleAdapter } from './Adapter/D1DrizzleAdapter.js';
 export { D1DrizzleConnection } from './Adapter/D1DrizzleConnection.js';
+export { D1TransactionUnsupportedError } from './Error/D1TransactionUnsupportedError.js';
 export { D1DrizzleAdapterFactory } from './Factory/D1DrizzleAdapterFactory.js';
 export { D1DrizzleDataTypesFactory } from './Factory/D1DrizzleDataTypesFactory.js';
 export * from './Interface/D1DrizzleClientInterface.js';

package/dist/index.js

@@ -4,6 +4,7 @@ import { D1DrizzleAdapterFactory } from './Factory/D1DrizzleAdapterFactory.js';
 import { D1DrizzleDataTypesFactory } from './Factory/D1DrizzleDataTypesFactory.js';
 export { D1DrizzleAdapter } from './Adapter/D1DrizzleAdapter.js';
 export { D1DrizzleConnection } from './Adapter/D1DrizzleConnection.js';
+export { D1TransactionUnsupportedError } from './Error/D1TransactionUnsupportedError.js';
 export { D1DrizzleAdapterFactory } from './Factory/D1DrizzleAdapterFactory.js';
 export { D1DrizzleDataTypesFactory } from './Factory/D1DrizzleDataTypesFactory.js';
 export * from './Interface/D1DrizzleClientInterface.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drizzle-adapter/d1",
   "type": "module",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -14,12 +14,23 @@
       "default": "./dist/migrator.js"
     }
   },
+  "scripts": {
+    "lint": "eslint src/",
+    "format": "eslint --fix src/",
+    "test": "vitest run",
+    "check": "tsc --noEmit",
+    "build": "shx rm -rf dist && tsc && tsc-esm-fix",
+    "package:tgz": "pnpm pack",
+    "package:publish": "pnpm publish --access public",
+    "prepublishOnly": "pnpm run build"
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260317.1",
     "@dmitryrechkin/eslint-standard": "^1.5.13",
     "dotenv": "^17.3.1",
     "eslint": "^10.1.0",
     "eslint-plugin-unused-imports": "^4.4.1",
+    "miniflare": "4.20260317.2",
     "shx": "^0.4.0",
     "tsc-esm-fix": "^3.1.2",
     "tsconfig-paths": "^4.2.0",
@@ -28,18 +39,9 @@
     "wrangler": "^4.77.0"
   },
   "dependencies": {
-    "drizzle-orm": "^0.45.1",
-    "@drizzle-adapter/core": "^1.1.1",
-    "@drizzle-adapter/sqlite-core": "^1.1.1"
+    "@drizzle-adapter/core": "workspace:^",
+    "@drizzle-adapter/sqlite-core": "workspace:^",
+    "drizzle-orm": "^0.45.1"
   },
-  "license": "MIT",
-  "scripts": {
-    "lint": "eslint src/",
-    "format": "eslint --fix src/",
-    "test": "vitest run",
-    "check": "tsc --noEmit",
-    "build": "shx rm -rf dist && tsc && tsc-esm-fix",
-    "package:tgz": "pnpm pack",
-    "package:publish": "pnpm publish --access public"
-  }
-}
+  "license": "MIT"
+}

package/src/Adapter/D1DrizzleConnection.ts

@@ -2,6 +2,7 @@ import type { D1Database } from '@cloudflare/workers-types';
 import type { DrizzleConnectionInterface } from '@drizzle-adapter/core';
 import { drizzle } from 'drizzle-orm/d1';
 
+import { D1TransactionUnsupportedError } from '../Error/D1TransactionUnsupportedError';
 import type { D1DrizzleClientInterface } from '../Interface/D1DrizzleClientInterface';
 
 /**
@@ -26,21 +27,19 @@ export class D1DrizzleConnection implements DrizzleConnectionInterface
 		(database as unknown as D1DrizzleClientInterface).execute =
 			database.run;
 
-		// Override transaction method to provide transaction-like behavior
-		// Since D1 doesn't support real transactions, we pass the original client
-		// Users can implement their own batching if needed for atomicity
-		(database as unknown as D1DrizzleClientInterface).transaction = async <
-			T
-		>(
-			callback: (tx: D1DrizzleClientInterface) => Promise<T>
-		): Promise<T> =>
-		{
-			// For now, just pass the original client - no transaction isolation
-			// This allows code to work without modifications while being explicit about the limitation
-			return await callback(
-				database as unknown as D1DrizzleClientInterface
-			);
-		};
+		/**
+		 * Replaces drizzle's transaction. drizzle-orm d1/session.js transaction() issues raw `begin`, which D1 rejects (probe in 1TS-Monorepo#4023).
+		 * The callback is never run; callers must use batch().
+		 * @returns {Promise<never>} Always rejects with D1TransactionUnsupportedError.
+		 */
+		(database as unknown as D1DrizzleClientInterface).transaction =
+			async (): Promise<never> =>
+			{
+				// `return await` satisfies both require-await and the no-bare-throw lint rules
+				return await Promise.reject(
+					new D1TransactionUnsupportedError()
+				);
+			};
 
 		this.client = database as unknown as D1DrizzleClientInterface;
 	}

package/src/Error/D1TransactionUnsupportedError.ts

@@ -0,0 +1,17 @@
+/**
+ * Thrown by transaction() on a D1 client. D1 has no interactive transactions,
+ * so the callback could not run atomically.
+ */
+export class D1TransactionUnsupportedError extends Error
+{
+	/**
+	 * Constructor.
+	 */
+	constructor()
+	{
+		super(
+			'D1 has no interactive transactions, so transaction() would run your callback without atomicity. Use db.batch([...]) instead: it is atomic (one implicit SQL transaction, all-or-nothing). Wrap raw SQL as db.run(sql`...`) inside the batch.'
+		);
+		this.name = 'D1TransactionUnsupportedError';
+	}
+}

package/src/Interface/D1DrizzleClientInterface.ts

@@ -15,5 +15,6 @@ export interface D1DrizzleClientInterface extends DrizzleClientInterface
 	selectDistinct(...args: any[]): ReturnType<AnyD1Database['selectDistinct']>;
 	update(...args: any[]): ReturnType<AnyD1Database['update']>;
 	insert(...args: any[]): ReturnType<AnyD1Database['insert']>;
-	transaction(...args: any[]): ReturnType<AnyD1Database['transaction']>;
+	/** Always rejects with D1TransactionUnsupportedError — use batch(). */
+	transaction(...args: unknown[]): Promise<never>;
 }

package/src/index.ts

@@ -9,6 +9,7 @@ import { D1DrizzleDataTypesFactory } from './Factory/D1DrizzleDataTypesFactory';
 
 export { D1DrizzleAdapter } from './Adapter/D1DrizzleAdapter';
 export { D1DrizzleConnection } from './Adapter/D1DrizzleConnection';
+export { D1TransactionUnsupportedError } from './Error/D1TransactionUnsupportedError';
 export { D1DrizzleAdapterFactory } from './Factory/D1DrizzleAdapterFactory';
 export { D1DrizzleDataTypesFactory } from './Factory/D1DrizzleDataTypesFactory';
 export * from './Interface/D1DrizzleClientInterface';

package/tests/Adapter/D1DrizzleConnection.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { D1DrizzleConnection } from '../../src/Adapter/D1DrizzleConnection';
 import { drizzle } from 'drizzle-orm/d1';
 import type { D1Database } from '@cloudflare/workers-types';
+import { D1TransactionUnsupportedError } from '../../src/Error/D1TransactionUnsupportedError';
 
 // Mock drizzle-orm/d1
 vi.mock('drizzle-orm/d1', () => ({
@@ -37,4 +38,13 @@ describe('D1DrizzleConnection', () => {
 		const client = connection.getClient();
 		expect(client).toMatchObject({ mockedClient: true });
 	});
+
+	it('transaction() rejects with D1TransactionUnsupportedError and never runs the callback', async () => {
+		const connection = new D1DrizzleConnection(mockD1Database);
+		const callback = vi.fn();
+		const transactionPromise = (connection.getClient() as unknown as { transaction: (cb: typeof callback) => Promise<unknown> }).transaction(callback);
+		await expect(transactionPromise).rejects.toBeInstanceOf(D1TransactionUnsupportedError);
+		await expect(transactionPromise).rejects.toThrow('db.batch');
+		expect(callback).not.toHaveBeenCalled();
+	});
 });

package/tests/Error/D1TransactionUnsupportedError.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import * as packageEntry from '../../src/index';
+
+describe('D1TransactionUnsupportedError', () => {
+	it('is exported from the package entry point', () => {
+		expect(packageEntry.D1TransactionUnsupportedError).toBeDefined();
+		const error = new packageEntry.D1TransactionUnsupportedError();
+		expect(error).toBeInstanceOf(Error);
+		expect(error.name).toBe('D1TransactionUnsupportedError');
+		expect(error.message).toContain('db.batch');
+	});
+});

package/tests/Integration/D1Atomicity.miniflare.test.ts

@@ -0,0 +1,77 @@
+import type { D1Database } from '@cloudflare/workers-types';
+import { sql } from 'drizzle-orm';
+import type { DrizzleD1Database } from 'drizzle-orm/d1';
+import { Miniflare } from 'miniflare';
+import type { D1Database as MiniflareD1Database } from 'miniflare';
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { D1DrizzleConnection } from '../../src/Adapter/D1DrizzleConnection';
+import { D1TransactionUnsupportedError } from '../../src/Error/D1TransactionUnsupportedError';
+
+describe('D1 atomicity (real Miniflare D1)', () => {
+	let miniflare: Miniflare;
+	let miniflareDatabase: MiniflareD1Database;
+
+	beforeAll(async () => {
+		miniflare = new Miniflare({
+			modules: true,
+			script: 'export default {fetch(){return new Response("")}}',
+			d1Databases: ['DB']
+		});
+		miniflareDatabase = await miniflare.getD1Database('DB');
+		await miniflareDatabase.exec('CREATE TABLE probe (id INTEGER PRIMARY KEY, name TEXT UNIQUE)');
+	});
+
+	afterAll(async () => {
+		await miniflare.dispose();
+	});
+
+	// Real adapter client. batch() and run() exist on the drizzle D1 client at runtime
+	// but are not on D1DrizzleClientInterface, so the client is cast to DrizzleD1Database.
+	const buildAdapterClient = (): DrizzleD1Database =>
+		new D1DrizzleConnection(miniflareDatabase as unknown as D1Database).getClient() as unknown as DrizzleD1Database;
+
+	const countProbeRows = async (): Promise<number> => {
+		const result = await miniflareDatabase
+			.prepare('SELECT count(*) AS total FROM probe')
+			.first<{ total: number }>();
+		return Number(result?.total);
+	};
+
+	const clearProbeRows = async (): Promise<void> => {
+		await miniflareDatabase.exec('DELETE FROM probe');
+	};
+
+	it('transaction() rejects with D1TransactionUnsupportedError and never runs the callback', async () => {
+		await clearProbeRows();
+		const client = buildAdapterClient();
+		const callback = vi.fn(async () => 'ran');
+		await expect(
+			(client as unknown as { transaction: (work: typeof callback) => Promise<unknown> }).transaction(callback)
+		).rejects.toBeInstanceOf(D1TransactionUnsupportedError);
+		expect(callback).not.toHaveBeenCalled();
+		expect(await countProbeRows()).toBe(0);
+	});
+
+	// drizzle-orm d1/session.js batch() forwards to native D1Database.batch, which is one implicit SQL transaction.
+	it('a batch with a UNIQUE violation is all-or-nothing', async () => {
+		await clearProbeRows();
+		const client = buildAdapterClient();
+		await expect(
+			client.batch([
+				client.run(sql`INSERT INTO probe (name) VALUES ('dup')`),
+				client.run(sql`INSERT INTO probe (name) VALUES ('dup')`)
+			])
+		).rejects.toThrow(/UNIQUE/);
+		expect(await countProbeRows()).toBe(0);
+	});
+
+	it('a batch of two distinct inserts commits both rows (control)', async () => {
+		await clearProbeRows();
+		const client = buildAdapterClient();
+		await client.batch([
+			client.run(sql`INSERT INTO probe (name) VALUES ('alpha')`),
+			client.run(sql`INSERT INTO probe (name) VALUES ('beta')`)
+		]);
+		expect(await countProbeRows()).toBe(2);
+	});
+});