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/package.json

@@ -27,6 +27,7 @@
       "types": "./dist/runtime/index.d.ts",
       "default": "./dist/runtime/index.js"
     },
+    "./db-client/*": "./dist/core/db-client/*",
     "./dist/runtime/virtual.js": {
       "default": "./dist/runtime/virtual.js"
     },

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

@@ -46,11 +46,13 @@ export async function cmd({
 			appToken: flags.token ?? dbInfo.token,
 			isBuild: false,
 			output: 'server',
+			__execute: true,
 		});
 	} else {
 		virtualModContents = getLocalVirtualModContents({
 			tables: dbConfig.tables ?? {},
 			root: astroConfig.root,
+			__execute: true,
 		});
 	}
 	const { code } = await bundleFile({ virtualModContents, root: astroConfig.root, fileUrl });

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

@@ -2,8 +2,8 @@ import type { AstroConfig } from 'astro';
 import { sql } from 'drizzle-orm';
 import prompts from 'prompts';
 import type { Arguments } from 'yargs-parser';
-import { createRemoteDatabaseClient } from '../../../../runtime/index.js';
 import { MIGRATION_VERSION } from '../../../consts.js';
+import { createClient } from '../../../db-client/libsql-node.js';
 import type { DBConfig, DBSnapshot } from '../../../types.js';
 import { getRemoteDatabaseInfo, type RemoteDatabaseInfo } from '../../../utils.js';
 import {
@@ -108,7 +108,7 @@ type RequestBody = {
 };
 
 async function pushToDb(requestBody: RequestBody, appToken: string, remoteUrl: string) {
-	const client = createRemoteDatabaseClient({
+	const client = createClient({
 		token: appToken,
 		url: remoteUrl,
 	});

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

@@ -1,12 +1,10 @@
 import type { AstroConfig } from 'astro';
 import { sql } from 'drizzle-orm';
 import type { Arguments } from 'yargs-parser';
-import {
-	createLocalDatabaseClient,
-	createRemoteDatabaseClient,
-} from '../../../../runtime/db-client.js';
 import { normalizeDatabaseUrl } from '../../../../runtime/index.js';
 import { DB_PATH } from '../../../consts.js';
+import { createClient as createLocalDatabaseClient } from '../../../db-client/libsql-local.js';
+import { createClient as createRemoteDatabaseClient } from '../../../db-client/libsql-node.js';
 import { SHELL_QUERY_MISSING_ERROR } from '../../../errors.js';
 import type { DBConfigInput } from '../../../types.js';
 import { getAstroEnv, getRemoteDatabaseInfo } from '../../../utils.js';
@@ -35,7 +33,7 @@ export async function cmd({
 			ASTRO_DATABASE_FILE,
 			new URL(DB_PATH, astroConfig.root).href,
 		);
-		const db = createLocalDatabaseClient({ dbUrl });
+		const db = createLocalDatabaseClient({ url: dbUrl });
 		const result = await db.run(sql.raw(query));
 		console.log(result);
 	}

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

@@ -4,10 +4,10 @@ import { sql } from 'drizzle-orm';
 import { SQLiteAsyncDialect } from 'drizzle-orm/sqlite-core';
 import * as color from 'kleur/colors';
 import { customAlphabet } from 'nanoid';
-import { createRemoteDatabaseClient, hasPrimaryKey } from '../../runtime/index.js';
 import { isSerializedSQL } from '../../runtime/types.js';
-import { isDbError } from '../../runtime/utils.js';
+import { hasPrimaryKey, isDbError } from '../../runtime/utils.js';
 import { MIGRATION_VERSION } from '../consts.js';
+import { createClient } from '../db-client/libsql-node.js';
 import { RENAME_COLUMN_ERROR, RENAME_TABLE_ERROR } from '../errors.js';
 import {
 	getCreateIndexQueries,
@@ -434,7 +434,7 @@ async function getDbCurrentSnapshot(
 	appToken: string,
 	remoteUrl: string,
 ): Promise<DBSnapshot | undefined> {
-	const client = createRemoteDatabaseClient({
+	const client = createClient({
 		token: appToken,
 		url: remoteUrl,
 	});

packages/db/src/core/consts.ts

@@ -15,3 +15,11 @@ export const DB_PATH = '.astro/content.db';
 export const CONFIG_FILE_NAMES = ['config.ts', 'config.js', 'config.mts', 'config.mjs'];
 
 export const MIGRATION_VERSION = '2024-03-12';
+
+export const VIRTUAL_CLIENT_MODULE_ID = 'virtual:astro:db-client';
+
+export const DB_CLIENTS = {
+	node: `${PACKAGE_NAME}/db-client/libsql-node.js`,
+	web: `${PACKAGE_NAME}/db-client/libsql-web.js`,
+	local: `${PACKAGE_NAME}/db-client/libsql-local.js`,
+};

packages/db/src/core/db-client/libsql-local.ts

@@ -0,0 +1,15 @@
+import { createClient as createLibsqlClient } from '@libsql/client';
+import { drizzle as drizzleLibsql, type LibSQLDatabase } from 'drizzle-orm/libsql';
+
+const isWebContainer = !!process.versions?.webcontainer;
+
+type LocalDbClientOptions = {
+	url: string;
+};
+
+export function createClient(options: LocalDbClientOptions): LibSQLDatabase {
+	const url = isWebContainer ? 'file:content.db' : options.url;
+	const client = createLibsqlClient({ url });
+	const db = drizzleLibsql(client);
+	return db;
+}

packages/db/src/core/db-client/libsql-node.ts

@@ -0,0 +1,41 @@
+import { createClient as createLibsqlClient } from '@libsql/client';
+import { drizzle as drizzleLibsql } from 'drizzle-orm/libsql';
+import { parseOpts } from '../../runtime/utils.js';
+
+type RemoteDbClientOptions = {
+	token: string;
+	url: string;
+};
+
+export function createClient(opts: RemoteDbClientOptions) {
+	const { token, url: rawUrl } = opts;
+
+	let parsedUrl = new URL(rawUrl);
+
+	const options: Record<string, string> = Object.fromEntries(parsedUrl.searchParams.entries());
+	parsedUrl.search = '';
+
+	let url = parsedUrl.toString();
+	if (parsedUrl.protocol === 'memory:') {
+		// libSQL expects a special string in place of a URL
+		// for in-memory DBs.
+		url = ':memory:';
+	} else if (
+		parsedUrl.protocol === 'file:' &&
+		parsedUrl.pathname.startsWith('/') &&
+		!rawUrl.startsWith('file:/')
+	) {
+		// libSQL accepts relative and absolute file URLs
+		// for local DBs. This doesn't match the URL specification.
+		// Parsing `file:some.db` and `file:/some.db` should yield
+		// the same result, but libSQL interprets the former as
+		// a relative path, and the latter as an absolute path.
+		// This detects when such a conversion happened during parsing
+		// and undoes it so that the URL given to libSQL is the
+		// same as given by the user.
+		url = 'file:' + parsedUrl.pathname.substring(1);
+	}
+
+	const client = createLibsqlClient({ ...parseOpts(options), url, authToken: token });
+	return drizzleLibsql(client);
+}

packages/db/src/core/db-client/libsql-web.ts

@@ -0,0 +1,31 @@
+import { createClient as createLibsqlClient } from '@libsql/client/web';
+import { drizzle as drizzleLibsql } from 'drizzle-orm/libsql/web';
+import { parseOpts } from '../../runtime/utils.js';
+
+type RemoteDbClientOptions = {
+	token: string;
+	url: string;
+};
+
+export function createClient(opts: RemoteDbClientOptions) {
+	const { token, url: rawUrl } = opts;
+
+	let parsedUrl = new URL(rawUrl);
+
+	const options: Record<string, string> = Object.fromEntries(parsedUrl.searchParams.entries());
+
+	parsedUrl.search = '';
+
+	let url = parsedUrl.toString();
+
+	const supportedProtocols = ['http:', 'https:', 'libsql:'];
+
+	if (!supportedProtocols.includes(parsedUrl.protocol)) {
+		throw new Error(
+			`Unsupported protocol "${parsedUrl.protocol}" for libSQL web client. Supported protocols are: ${supportedProtocols.join(', ')}.`,
+		);
+	}
+
+	const client = createLibsqlClient({ ...parseOpts(options), url, authToken: token });
+	return drizzleLibsql(client);
+}

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';
@@ -27,8 +28,29 @@ import {
 	type SeedHandler,
 	vitePluginDb,
 } from './vite-plugin-db.js';
+import { vitePluginDbClient } from './vite-plugin-db-client.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;
@@ -69,6 +91,11 @@ function astroDBIntegration(): AstroIntegration {
 				const args = parseArgs(process.argv.slice(3));
 				connectToRemote = process.env.ASTRO_INTERNAL_TEST_REMOTE || args['remote'];
 
+				const dbClientPlugin = vitePluginDbClient({
+					connectToRemote,
+					mode: resolvedConfig.mode,
+				});
+
 				if (connectToRemote) {
 					dbPlugin = vitePluginDb({
 						connectToRemote,
@@ -95,7 +122,7 @@ function astroDBIntegration(): AstroIntegration {
 				updateConfig({
 					vite: {
 						assetsInclude: [DB_PATH],
-						plugins: [dbPlugin],
+						plugins: [dbClientPlugin, dbPlugin],
 					},
 				});
 			},
@@ -182,8 +209,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-client.ts

@@ -0,0 +1,52 @@
+import { DB_CLIENTS, VIRTUAL_CLIENT_MODULE_ID } from '../consts.js';
+import type { VitePlugin } from '../utils.js';
+
+type VitePluginDBClientParams = {
+	connectToRemote: boolean;
+	mode: 'node' | 'web';
+};
+
+function getRemoteClientModule(mode: 'node' | 'web') {
+	switch (mode) {
+		case 'web': {
+			return `export { createClient } from '${DB_CLIENTS.web}';`;
+		}
+        case 'node':
+		default:
+			return `export { createClient } from '${DB_CLIENTS.node}';`;
+	}
+}
+
+function getLocalClientModule(mode: 'node' | 'web') {
+	switch (mode) {
+        case 'node':
+        case 'web':
+		default:
+			return `export { createClient } from '${DB_CLIENTS.local}';`;
+	}
+}
+
+const resolved = '\0' + VIRTUAL_CLIENT_MODULE_ID;
+
+export function vitePluginDbClient(params: VitePluginDBClientParams): VitePlugin {
+	return {
+		name: 'virtual:astro:db-client',
+		enforce: 'pre',
+		async resolveId(id) {
+			if (id !== VIRTUAL_CLIENT_MODULE_ID) return;
+			return resolved;
+		},
+		async load(id) {
+			if (id !== resolved) return;
+
+			switch (params.connectToRemote) {
+				case true:
+					return getRemoteClientModule(params.mode);
+				case false:
+				default:
+					// Local client is always available, even if not used.
+					return getLocalClientModule(params.mode);	
+			}
+		},
+	};
+}