feat(db): add support for non-node libsql client

.changeset/full-dingos-repeat.md

@@ -0,0 +1,17 @@
+---
+'@astrojs/db': minor
+---
+
+Adds support for environments such as Cloudflare or Deno that require a non-node based libsql client.
+
+To utilize this new feature, you must add the following to your Astro Db config. This will enable the usage of the alterative LibSQL web driver. In most cases this should only be needed on Cloudflare or Deno type environments, and using the default mode `node` will be enough for normal usage.
+
+```ts
+import db from '@astrojs/db';
+import { defineConfig } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [db({ mode: 'web' })],
+});
+```

packages/db/src/core/cli/commands/execute/index.ts

@@ -40,17 +40,19 @@ export async function cmd({
 
 	let virtualModContents: string;
 	if (flags.remote) {
-		const dbInfo = getRemoteDatabaseInfo();
+		const dbInfo = getRemoteDatabaseInfo('node');
 		virtualModContents = getRemoteVirtualModContents({
 			tables: dbConfig.tables ?? {},
 			appToken: flags.token ?? dbInfo.token,
 			isBuild: false,
 			output: 'server',
+			mode: 'node'
 		});
 	} else {
 		virtualModContents = getLocalVirtualModContents({
 			tables: dbConfig.tables ?? {},
 			root: astroConfig.root,
+			mode: 'node'
 		});
 	}
 	const { code } = await bundleFile({ virtualModContents, root: astroConfig.root, fileUrl });

packages/db/src/core/cli/commands/push/index.ts

@@ -24,7 +24,7 @@ export async function cmd({
 }) {
 	const isDryRun = flags.dryRun;
 	const isForceReset = flags.forceReset;
-	const dbInfo = getRemoteDatabaseInfo();
+	const dbInfo = getRemoteDatabaseInfo('node');
 	const productionSnapshot = await getProductionCurrentSnapshot(dbInfo);
 	const currentSnapshot = createCurrentSnapshot(dbConfig);
 	const isFromScratch = !productionSnapshot;
@@ -111,6 +111,7 @@ async function pushToDb(requestBody: RequestBody, appToken: string, remoteUrl: s
 	const client = createRemoteDatabaseClient({
 		token: appToken,
 		url: remoteUrl,
+		mode: 'node',
 	});
 
 	await client.run(sql`create table if not exists _astro_db_snapshot (

packages/db/src/core/cli/commands/shell/index.ts

@@ -24,7 +24,7 @@ export async function cmd({
 		console.error(SHELL_QUERY_MISSING_ERROR);
 		process.exit(1);
 	}
-	const dbInfo = getRemoteDatabaseInfo();
+	const dbInfo = getRemoteDatabaseInfo('node');
 	if (flags.remote) {
 		const db = createRemoteDatabaseClient(dbInfo);
 		const result = await db.run(sql.raw(query));

packages/db/src/core/cli/commands/verify/index.ts

@@ -19,7 +19,7 @@ export async function cmd({
 	flags: Arguments;
 }) {
 	const isJson = flags.json;
-	const dbInfo = getRemoteDatabaseInfo();
+	const dbInfo = getRemoteDatabaseInfo('node');
 	const productionSnapshot = await getProductionCurrentSnapshot(dbInfo);
 	const currentSnapshot = createCurrentSnapshot(dbConfig);
 	const { queries: migrationQueries, confirmations } = await getMigrationQueries({

packages/db/src/core/cli/migration-queries.ts

@@ -437,6 +437,7 @@ async function getDbCurrentSnapshot(
 	const client = createRemoteDatabaseClient({
 		token: appToken,
 		url: remoteUrl,
+		mode: 'node',
 	});
 
 	try {

packages/db/src/core/integration/index.ts

@@ -13,6 +13,7 @@ import {
 	type ViteDevServer,
 } from 'vite';
 import parseArgs from 'yargs-parser';
+import { z } from 'zod';
 import { AstroDbError, isDbError } from '../../runtime/utils.js';
 import { CONFIG_FILE_NAMES, DB_PATH, VIRTUAL_MODULE_ID } from '../consts.js';
 import { EXEC_DEFAULT_EXPORT_ERROR, EXEC_ERROR } from '../errors.js';
@@ -28,7 +29,27 @@ import {
 	vitePluginDb,
 } from './vite-plugin-db.js';
 
-function astroDBIntegration(): AstroIntegration {
+const astroDBConfigSchema = z
+	.object({
+		/**
+		 * Sets the mode of the underlying `@libsql/client` connection.
+		 *
+		 * In most cases, the default 'node' mode is sufficient. On platforms like Cloudflare, or Deno, you may need to set this to 'web'.
+		 *
+		 * @default 'node'
+		 */
+		mode: z
+			.union([z.literal('node'), z.literal('web')])
+			.optional()
+			.default('node'),
+	})
+	.optional()
+	.default({});
+
+export type AstroDBConfig = z.infer<typeof astroDBConfigSchema>;
+
+function astroDBIntegration(options?: AstroDBConfig): AstroIntegration {
+	const resolvedConfig = astroDBConfigSchema.parse(options);
 	let connectToRemote = false;
 	let configFileDependencies: string[] = [];
 	let root: URL;
@@ -72,12 +93,13 @@ function astroDBIntegration(): AstroIntegration {
 				if (connectToRemote) {
 					dbPlugin = vitePluginDb({
 						connectToRemote,
-						appToken: getRemoteDatabaseInfo().token,
+						appToken: getRemoteDatabaseInfo(resolvedConfig.mode).token,
 						tables,
 						root: config.root,
 						srcDir: config.srcDir,
 						output: config.output,
 						seedHandler,
+						mode: resolvedConfig.mode,
 					});
 				} else {
 					dbPlugin = vitePluginDb({
@@ -89,6 +111,7 @@ function astroDBIntegration(): AstroIntegration {
 						output: config.output,
 						logger,
 						seedHandler,
+						mode: resolvedConfig.mode,
 					});
 				}
 
@@ -182,8 +205,8 @@ function databaseFileEnvDefined() {
 	return env.ASTRO_DATABASE_FILE != null || process.env.ASTRO_DATABASE_FILE != null;
 }
 
-export function integration(): AstroIntegration[] {
-	return [astroDBIntegration(), fileURLIntegration()];
+export function integration(options?: AstroDBConfig): AstroIntegration[] {
+	return [astroDBIntegration(options), fileURLIntegration()];
 }
 
 async function executeSeedFile({

packages/db/src/core/integration/vite-plugin-db.ts

@@ -42,6 +42,7 @@ type VitePluginDBParams =
 			logger?: AstroIntegrationLogger;
 			output: AstroConfig['output'];
 			seedHandler: SeedHandler;
+			mode: 'node' | 'web';
 	  }
 	| {
 			connectToRemote: true;
@@ -51,6 +52,7 @@ type VitePluginDBParams =
 			root: URL;
 			output: AstroConfig['output'];
 			seedHandler: SeedHandler;
+			mode: 'node' | 'web';
 	  };
 
 export function vitePluginDb(params: VitePluginDBParams): VitePlugin {
@@ -77,6 +79,7 @@ export function vitePluginDb(params: VitePluginDBParams): VitePlugin {
 					tables: params.tables.get(),
 					isBuild: command === 'build',
 					output: params.output,
+					mode: params.mode,
 				});
 			}
 
@@ -87,6 +90,7 @@ export function vitePluginDb(params: VitePluginDBParams): VitePlugin {
 				return getLocalVirtualModContents({
 					root: params.root,
 					tables: params.tables.get(),
+					mode: 'node',
 				});
 			}
 
@@ -108,6 +112,7 @@ export function vitePluginDb(params: VitePluginDBParams): VitePlugin {
 			return getLocalVirtualModContents({
 				root: params.root,
 				tables: params.tables.get(),
+				mode: params.mode,
 			});
 		},
 	};
@@ -117,9 +122,9 @@ export function getConfigVirtualModContents() {
 	return `export * from ${RUNTIME_VIRTUAL_IMPORT}`;
 }
 
-export function getLocalVirtualModContents({ tables, root }: { tables: DBTables; root: URL }) {
+export function getLocalVirtualModContents({ tables, root, mode }: { tables: DBTables; root: URL; mode: 'node' | 'web' }) {
 	const { ASTRO_DATABASE_FILE } = getAstroEnv();
-	const dbInfo = getRemoteDatabaseInfo();
+	const dbInfo = getRemoteDatabaseInfo(mode);
 	const dbUrl = new URL(DB_PATH, root);
 	return `
 import { asDrizzleTable, createLocalDatabaseClient, normalizeDatabaseUrl } from ${RUNTIME_IMPORT};
@@ -137,13 +142,15 @@ export function getRemoteVirtualModContents({
 	appToken,
 	isBuild,
 	output,
+	mode
 }: {
 	tables: DBTables;
 	appToken: string;
 	isBuild: boolean;
 	output: AstroConfig['output'];
+	mode: 'node' | 'web';
 }) {
-	const dbInfo = getRemoteDatabaseInfo();
+	const dbInfo = getRemoteDatabaseInfo(mode);
 
 	function appTokenArg() {
 		if (isBuild) {
@@ -176,6 +183,7 @@ import {asDrizzleTable, createRemoteDatabaseClient} from ${RUNTIME_IMPORT};
 export const db = await createRemoteDatabaseClient({
   url: ${dbUrlArg()},
   token: ${appTokenArg()},
+  mode: ${JSON.stringify(mode)},
 });
 
 export * from ${RUNTIME_VIRTUAL_IMPORT};

packages/db/src/core/utils.ts

@@ -12,14 +12,16 @@ export function getAstroEnv(envMode = ''): Record<`ASTRO_${string}`, string> {
 export type RemoteDatabaseInfo = {
 	url: string;
 	token: string;
+	mode: 'node' | 'web';
 };
 
-export function getRemoteDatabaseInfo(): RemoteDatabaseInfo {
+export function getRemoteDatabaseInfo(mode: 'node' | 'web'): RemoteDatabaseInfo {
 	const astroEnv = getAstroEnv();
 
 	return {
 		url: astroEnv.ASTRO_DB_REMOTE_URL,
 		token: astroEnv.ASTRO_DB_APP_TOKEN,
+		mode,
 	};
 }
 

packages/db/src/index.ts

@@ -1,3 +1,3 @@
 export { cli } from './core/cli/index.js';
-export { integration as default } from './core/integration/index.js';
+export { type AstroDBConfig, integration as default } from './core/integration/index.js';
 export type { TableConfig } from './core/types.js';

packages/db/src/runtime/db-client.ts

@@ -1,6 +1,7 @@
 import { createClient, type Config as LibSQLConfig } from '@libsql/client';
-import type { LibSQLDatabase } from 'drizzle-orm/libsql';
-import { drizzle as drizzleLibsql } from 'drizzle-orm/libsql';
+import { createClient as createClientWeb } from '@libsql/client/web';
+import { drizzle as drizzleLibsql, type LibSQLDatabase } from 'drizzle-orm/libsql';
+import { drizzle as drizzleLibsqlWeb } from 'drizzle-orm/libsql/web';
 
 const isWebContainer = !!process.versions?.webcontainer;
 
@@ -18,12 +19,18 @@ export function createLocalDatabaseClient(options: LocalDbClientOptions): LibSQL
 type RemoteDbClientOptions = {
 	token: string;
 	url: string | URL;
+	mode: 'node' | 'web';
 };
 
 export function createRemoteDatabaseClient(options: RemoteDbClientOptions) {
 	const url = new URL(options.url);
 
-	return createRemoteLibSQLClient(options.token, url, options.url.toString());
+	switch (options.mode) {
+		case 'web':
+			return createRemoteLibSQLWebClient(options.token, url);
+		case 'node':
+			return createRemoteLibSQLClient(options.token, url, options.url.toString());
+	}
 }
 
 // this function parses the options from a `Record<string, string>`
@@ -69,3 +76,21 @@ function createRemoteLibSQLClient(authToken: string, dbURL: URL, rawUrl: string)
 	const client = createClient({ ...parseOpts(options), url, authToken });
 	return drizzleLibsql(client);
 }
+
+function createRemoteLibSQLWebClient(authToken: string, dbURL: URL) {
+	const options: Record<string, string> = Object.fromEntries(dbURL.searchParams.entries());
+	dbURL.search = '';
+
+	let url = dbURL.toString();
+
+	const supportedProtocols = ['http:', 'https:', 'libsql:'];
+
+	if (!supportedProtocols.includes(dbURL.protocol)) {
+		throw new Error(
+			`Unsupported protocol "${dbURL.protocol}" for libSQL web client. Supported protocols are: ${supportedProtocols.join(', ')}.`
+		);
+	}
+
+	const client = createClientWeb({ ...parseOpts(options), url, authToken });
+	return drizzleLibsqlWeb(client);
+}

packages/db/test/unit/remote-info.test.js

@@ -9,22 +9,24 @@ describe('RemoteDatabaseInfo', () => {
 	});
 
 	test('default remote info', () => {
-		const dbInfo = getRemoteDatabaseInfo();
+		const dbInfo = getRemoteDatabaseInfo('node');
 
 		assert.deepEqual(dbInfo, {
 			url: undefined,
 			token: undefined,
+			mode: 'node',
 		});
 	});
 
 	test('configured libSQL remote', () => {
 		process.env.ASTRO_DB_REMOTE_URL = 'libsql://libsql.self.hosted';
 		process.env.ASTRO_DB_APP_TOKEN = 'foo';
-		const dbInfo = getRemoteDatabaseInfo();
+		const dbInfo = getRemoteDatabaseInfo('node');
 
 		assert.deepEqual(dbInfo, {
 			url: 'libsql://libsql.self.hosted',
 			token: 'foo',
+			mode: 'node'
 		});
 	});
 });