feat(unenv-preset): add support for native node:sqlite module (#11841)

vicb · petebacondarwin · devin-ai-integration[bot] · web-flow · commit beb96af470ae · 2026-01-12T18:05:27.000Z
* feat(unenv-preset): add support for native node:sqlite module (#11805) * feat(unenv-preset): add support for native node:sqlite module Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> * fix: improve testSqlite to test both unenv and native cases Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> * refactor: use assertTypeOfProperties for cleaner test code Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fixup! do not error when `node:sqlite` is not available on the active Node runtime * fixup! feedback --------- Co-authored-by: Pete Bacon Darwin <pete@bacondarwin.com> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
diff --git a/.changeset/native-sqlite-module.md b/.changeset/native-sqlite-module.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/unenv-preset": minor
+---
+
+Add support for native `node:sqlite` module when the `enable_nodejs_sqlite_module` compatibility flag is enabled. This feature is currently experimental and requires `nodejs_compat`, `experimental`, and `enable_nodejs_sqlite_module` compatibility flags to be set.
diff --git a/packages/unenv-preset/src/preset.ts b/packages/unenv-preset/src/preset.ts
@@ -80,6 +80,7 @@ export function getCloudflarePreset({
 	const consoleOverrides = getConsoleOverrides(compat);
 	const vmOverrides = getVmOverrides(compat);
 	const inspectorOverrides = getInspectorOverrides(compat);
+	const sqliteOverrides = getSqliteOverrides(compat);
 
 	// "dynamic" as they depend on the compatibility date and flags
 	const dynamicNativeModules = [
@@ -96,6 +97,7 @@ export function getCloudflarePreset({
 		...consoleOverrides.nativeModules,
 		...vmOverrides.nativeModules,
 		...inspectorOverrides.nativeModules,
+		...sqliteOverrides.nativeModules,
 	];
 
 	// "dynamic" as they depend on the compatibility date and flags
@@ -113,6 +115,7 @@ export function getCloudflarePreset({
 		...consoleOverrides.hybridModules,
 		...vmOverrides.hybridModules,
 		...inspectorOverrides.hybridModules,
+		...sqliteOverrides.hybridModules,
 	];
 
 	return {
@@ -635,3 +638,39 @@ function getInspectorOverrides({
 				hybridModules: [],
 			};
 }
+
+/**
+ * Returns the overrides for `node:sqlite` (unenv or workerd)
+ *
+ * The native sqlite implementation:
+ * - is experimental and has no default enable date
+ * - can be enabled with the "enable_nodejs_sqlite_module" flag
+ * - can be disabled with the "disable_nodejs_sqlite_module" flag
+ */
+function getSqliteOverrides({
+	compatibilityFlags,
+}: {
+	compatibilityDate: string;
+	compatibilityFlags: string[];
+}): { nativeModules: string[]; hybridModules: string[] } {
+	const disabledByFlag = compatibilityFlags.includes(
+		"disable_nodejs_sqlite_module"
+	);
+
+	const enabledByFlag =
+		compatibilityFlags.includes("enable_nodejs_sqlite_module") &&
+		compatibilityFlags.includes("experimental");
+
+	const enabled = enabledByFlag && !disabledByFlag;
+
+	// When enabled, use the native `sqlite` module from workerd
+	return enabled
+		? {
+				nativeModules: ["sqlite"],
+				hybridModules: [],
+			}
+		: {
+				nativeModules: [],
+				hybridModules: [],
+			};
+}
diff --git a/packages/wrangler/e2e/unenv-preset/preset.test.ts b/packages/wrangler/e2e/unenv-preset/preset.test.ts
@@ -429,6 +429,28 @@ const localTestConfigs: TestConfig[] = [
 			},
 		},
 	],
+	// node:sqlite (experimental, no default enable date)
+	[
+		// TODO: add test for disabled by date (no date defined yet)
+		// TODO: add test for enabled by date (no date defined yet)
+		{
+			name: "sqlite enabled by flag",
+			compatibilityDate: "2024-09-23",
+			compatibilityFlags: ["enable_nodejs_sqlite_module", "experimental"],
+			expectRuntimeFlags: {
+				enable_nodejs_sqlite_module: true,
+			},
+		},
+		// TODO: update the date past the default enable date (when defined)
+		{
+			name: "sqlite disabled by flag",
+			compatibilityDate: "2024-09-23",
+			compatibilityFlags: ["disable_nodejs_sqlite_module", "experimental"],
+			expectRuntimeFlags: {
+				enable_nodejs_sqlite_module: false,
+			},
+		},
+	],
 ].flat() as TestConfig[];
 
 describe.each(localTestConfigs)(
diff --git a/packages/wrangler/e2e/unenv-preset/worker/index.ts b/packages/wrangler/e2e/unenv-preset/worker/index.ts
@@ -783,6 +783,55 @@ export const WorkerdTests: Record<string, () => void> = {
 			assertTypeOf(inspectorPromises.default, "Network", "object");
 		}
 	},
+
+	async testSqlite() {
+		let sqlite;
+		try {
+			// This source file is imported by the Node runtime (to retrieve the list of tests).
+			// As `node:sqlite` has only be added in Node 22.5.0, we need to try/catch to not error with older versions.
+			// Note: This test is not meant to be executed by the Node runtime,
+			// but only by workerd where `node:sqlite` is available.
+			// @ts-expect-error TS2307 - node:sqlite is only available in Node 22.5.0+
+			sqlite = await import("node:sqlite");
+		} catch {
+			throw new Error(
+				"sqlite is not available. This should never happen in workerd."
+			);
+		}
+
+		// Common exports (both unenv stub and native workerd)
+		assertTypeOfProperties(sqlite, {
+			DatabaseSync: "function",
+			StatementSync: "function",
+			constants: "object",
+			default: "object",
+		});
+		assertTypeOfProperties(sqlite.default, {
+			DatabaseSync: "function",
+			StatementSync: "function",
+			constants: "object",
+		});
+
+		if (getRuntimeFlagValue("enable_nodejs_sqlite_module")) {
+			// Native workerd exports `backup` function and non-empty constants
+			assertTypeOf(sqlite, "backup", "function");
+			assertTypeOf(sqlite.default, "backup", "function");
+			assert.strictEqual(
+				"SQLITE_CHANGESET_OMIT" in sqlite.constants,
+				true,
+				"constants should contain SQLITE_CHANGESET_OMIT"
+			);
+		} else {
+			// unenv stub: no backup function and empty constants
+			assertTypeOf(sqlite, "backup", "undefined");
+			assertTypeOf(sqlite.default, "backup", "undefined");
+			assert.deepStrictEqual(
+				Object.keys(sqlite.constants),
+				[],
+				"constants should be empty in unenv stub"
+			);
+		}
+	},
 };
 
 /**

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@cloudflare/unenv-preset": minor
 +---
++
 +Add support for native `node:sqlite` module when the `enable_nodejs_sqlite_module` compatibility flag is enabled. This feature is currently experimental and requires `nodejs_compat`, `experimental`, and `enable_nodejs_sqlite_module` compatibility flags to be set.