@happyvertical/sql 0.79.0 → 0.80.1

package/dist/chunks/duckdb-DykBBzd6.js

@@ -0,0 +1,1056 @@
+import { n as buildWhere, r as formatDbError, t as DatabaseSchemaManager } from "./schema-manager-a8RlxIE2.js";
+import { t as convertUniqueIndexesToInlineConstraints } from "./duckdb-schema-utils-B-XBP8QF.js";
+import { a as validateTableName, i as validateIndexName, n as generateCreateIndexStatement, r as validateColumnName, t as generateAddColumnStatement } from "./alter-utils-K7tiuj5L.js";
+import { resolveSchemas } from "../index.js";
+import { DatabaseError } from "@happyvertical/utils";
+import { readdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { tmpdir } from "node:os";
+//#region src/duckdb.ts
+/**
+* Creates tables from provided schema definitions
+*
+* DuckDB has a known limitation (issue #12684) where ON CONFLICT clauses
+* fail with UNIQUE INDEX but work with inline UNIQUE constraints.
+* This function converts UNIQUE indexes to inline constraints for compatibility.
+*
+* @param connection - DuckDB connection
+* @param schemas - Schema definitions to create
+*/
+async function createTablesFromSchemas(connection, schemas) {
+	for (const [tableName, schema] of Object.entries(schemas)) try {
+		if ((await connection.runAndReadAll(`SELECT name FROM sqlite_master WHERE type='table' AND name='${tableName}'`)).getRowObjects().length > 0) {
+			console.log(`[duckdb] Table ${tableName} already exists, skipping`);
+			continue;
+		}
+		console.log(`[duckdb] Creating table ${tableName} from provided schema`);
+		const transformed = convertUniqueIndexesToInlineConstraints(schema.ddl, schema.indexes);
+		await connection.run(transformed.ddl);
+		if (transformed.indexes && transformed.indexes.length > 0) for (const indexSQL of transformed.indexes) try {
+			await connection.run(indexSQL);
+		} catch (error) {
+			console.warn(`[duckdb] Failed to create index for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (schema.triggers && schema.triggers.length > 0) for (const triggerSQL of schema.triggers) try {
+			await connection.run(triggerSQL);
+		} catch (error) {
+			console.warn(`[duckdb] Failed to create trigger for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	} catch (error) {
+		throw new DatabaseError(`Failed to create table ${tableName} from schema`, {
+			tableName,
+			schema,
+			originalError: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+/**
+* Resolves a DuckDB URL, handling :memory: variants to prevent file leakage.
+*
+* DuckDB interprets any string as a file path unless it's exactly ':memory:'.
+* URLs like ':memory:12345' create files named ':memory:12345' in the working directory.
+*
+* This function:
+* - Returns ':memory:' unchanged (pure in-memory database)
+* - Converts ':memory:*' patterns to temp files in os.tmpdir()
+* - Returns other URLs unchanged (file paths, etc.)
+*
+* @param url - The database URL to resolve
+* @returns The resolved URL safe for DuckDB
+*/
+function resolveDuckDBUrl(url) {
+	if (url === ":memory:") return url;
+	if (url.startsWith(":memory:")) {
+		const suffix = url.slice(8);
+		return join(tmpdir(), `duckdb-memory-${suffix}.db`);
+	}
+	return url;
+}
+/**
+* Creates a DuckDB connection instance
+*
+* @param options - DuckDB connection options
+* @returns Promise resolving to a DuckDB connection
+*/
+async function createDuckDBConnection(options) {
+	const { url = ":memory:", dataDir = "./data", autoRegisterJSON = true } = options;
+	const schemas = resolveSchemas(options.schemas) ?? {};
+	const resolvedUrl = resolveDuckDBUrl(url);
+	try {
+		const { DuckDBInstance } = await import(
+			/* @vite-ignore */
+			"@duckdb/node-api"
+);
+		const connection = await (await DuckDBInstance.create(resolvedUrl)).connect();
+		if (schemas && Object.keys(schemas).length > 0) await createTablesFromSchemas(connection, schemas);
+		if (autoRegisterJSON && dataDir) await registerJSONFiles(connection, dataDir);
+		return connection;
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		throw new DatabaseError(`Failed to create DuckDB connection: ${errorMessage}`, {
+			url,
+			originalError: errorMessage
+		});
+	}
+}
+/**
+* Scans the data directory and registers JSON files as queryable tables
+*
+* @param connection - DuckDB connection
+* @param dataDir - Directory containing JSON files
+*/
+async function registerJSONFiles(connection, dataDir) {
+	try {
+		const jsonFiles = (await readdir(dataDir)).filter((file) => extname(file).toLowerCase() === ".json");
+		for (const file of jsonFiles) {
+			const filePath = join(dataDir, file);
+			const tableName = basename(file, ".json");
+			await connection.run(`CREATE OR REPLACE VIEW ${tableName} AS SELECT * FROM read_json('${filePath}', auto_detect=true, format='auto', timestampformat='iso', dateformat='iso')`);
+		}
+	} catch (error) {
+		if (error.code !== "ENOENT") throw new DatabaseError(`Failed to register JSON files from ${dataDir}`, {
+			dataDir,
+			originalError: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+/**
+* Converts DuckDB-specific type representations to JavaScript types
+*
+* Handles two cases:
+* 1. JavaScript BigInt values → converted to numbers
+* 2. DuckDB timestamp objects ({ micros: number }) → converted to Date objects
+*
+* DuckDB represents TIMESTAMP values as objects with a single property
+* called 'micros' containing microseconds since Unix epoch. This function
+* converts them to JavaScript Date objects for proper serialization.
+*
+* @param obj - Object that may contain BigInt or timestamp values
+* @returns Object with DuckDB types converted to JavaScript types
+*/
+function convertBigInts(obj) {
+	if (obj === null || obj === void 0) return obj;
+	if (typeof obj === "bigint") return Number(obj);
+	if (typeof obj === "object" && !Array.isArray(obj) && "micros" in obj && Object.keys(obj).length === 1 && (typeof obj.micros === "number" || typeof obj.micros === "bigint")) {
+		const milliseconds = (typeof obj.micros === "bigint" ? Number(obj.micros) : obj.micros) / 1e3;
+		return new Date(milliseconds);
+	}
+	if (Array.isArray(obj)) return obj.map(convertBigInts);
+	if (typeof obj === "object") {
+		const result = {};
+		for (const key in obj) result[key] = convertBigInts(obj[key]);
+		return result;
+	}
+	return obj;
+}
+/**
+* Creates a DuckDB database adapter
+*
+* @param options - DuckDB connection options
+* @returns Database interface for DuckDB
+*/
+async function getDatabase(options = {}) {
+	const connection = await createDuckDBConnection(options);
+	const writeStrategy = options.writeStrategy || "none";
+	const dataDir = options.dataDir || "./data";
+	const url = resolveDuckDBUrl(options.url || ":memory:");
+	/**
+	* Inserts one or more records into a table
+	*
+	* @param table - Table name
+	* @param data - Single record or array of records to insert
+	* @returns Promise resolving to operation result
+	* @throws Error if the insert operation fails
+	*/
+	const insert = async (table, data) => {
+		const records = Array.isArray(data) ? data : [data];
+		if (records.length === 0) return {
+			operation: "insert",
+			affected: 0
+		};
+		const keys = Object.keys(records[0]);
+		const values = [];
+		let paramIdx = 1;
+		const placeholders = records.map((record) => {
+			return `(${keys.map((key) => {
+				const value = record[key];
+				if (value === null || value === void 0) return "NULL";
+				else if (value === "" && typeof value === "string") {
+					values.push(value);
+					return `CAST($${paramIdx++} AS TEXT)`;
+				} else if (value instanceof Date) {
+					values.push(value.toISOString());
+					return `$${paramIdx++}`;
+				} else if (Array.isArray(value)) {
+					values.push(JSON.stringify(value));
+					return `CAST($${paramIdx++} AS JSON)`;
+				} else if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+					values.push(JSON.stringify(value));
+					return `CAST($${paramIdx++} AS JSON)`;
+				} else {
+					values.push(value);
+					return `$${paramIdx++}`;
+				}
+			}).join(", ")})`;
+		}).join(", ");
+		const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES ${placeholders}`;
+		try {
+			await connection.run(sql, values);
+			const affected = records.length;
+			if (writeStrategy === "immediate") await exportTableToJSON(connection, table, dataDir);
+			return {
+				operation: "insert",
+				affected
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to insert records into table", {
+				table,
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Retrieves a single record matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records
+	* @returns Promise resolving to matching record or null if not found
+	* @throws Error if the query fails
+	*/
+	const get = async (table, where) => {
+		const { sql: whereClause, values } = buildWhere(where, 1, "duckdb");
+		const sql = `SELECT * FROM ${table} ${whereClause} LIMIT 1`;
+		try {
+			const rows = (await connection.runAndReadAll(sql, values)).getRowObjects();
+			return rows.length > 0 ? convertBigInts(rows[0]) : null;
+		} catch (e) {
+			throw new DatabaseError("Failed to retrieve record from table", {
+				table,
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Retrieves multiple records matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records
+	* @returns Promise resolving to array of matching records
+	* @throws Error if the query fails
+	*/
+	const list = async (table, where) => {
+		const { sql: whereClause, values } = buildWhere(where, 1, "duckdb");
+		const sql = `SELECT * FROM ${table} ${whereClause}`;
+		try {
+			return convertBigInts((await connection.runAndReadAll(sql, values)).getRowObjects());
+		} catch (e) {
+			throw new DatabaseError("Failed to list records from table", {
+				table,
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Updates records matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records to update
+	* @param data - New data to set
+	* @returns Promise resolving to operation result
+	* @throws Error if the update operation fails
+	*/
+	const update = async (table, where, data) => {
+		const keys = Object.keys(data);
+		const setClause = keys.map((key, idx) => `${key} = $${idx + 1}`).join(", ");
+		const { sql: whereClause, values: whereValues } = buildWhere(where, keys.length + 1, "duckdb");
+		const sql = `UPDATE ${table} SET ${setClause} ${whereClause}`;
+		const values = [...Object.values(data), ...whereValues];
+		try {
+			await connection.run(sql, values);
+			if (writeStrategy === "immediate") await exportTableToJSON(connection, table, dataDir);
+			return {
+				operation: "update",
+				affected: 1
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to update records in table", {
+				table,
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	const buildDuckDBValueExpression = (value, values, paramIdx) => {
+		if (value === null || value === void 0) return "NULL";
+		if (value === "" && typeof value === "string") {
+			values.push(value);
+			return `CAST($${paramIdx.value++} AS TEXT)`;
+		}
+		if (value instanceof Date) {
+			values.push(value.toISOString());
+			return `$${paramIdx.value++}`;
+		}
+		if (Array.isArray(value)) {
+			values.push(JSON.stringify(value));
+			return `CAST($${paramIdx.value++} AS JSON)`;
+		}
+		if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+			values.push(JSON.stringify(value));
+			return `CAST($${paramIdx.value++} AS JSON)`;
+		}
+		values.push(value);
+		return `$${paramIdx.value++}`;
+	};
+	const executeNullAwareDuckDBUpsert = async (table, conflictColumns, data) => {
+		const conflictWhere = Object.fromEntries(conflictColumns.map((col) => [col, data[col]]));
+		if (!await get(table, conflictWhere)) return insert(table, data);
+		const keys = Object.keys(data);
+		const values = [];
+		const paramIdx = { value: 1 };
+		const assignments = keys.map((key) => {
+			return `"${key}" = ${buildDuckDBValueExpression(data[key], values, paramIdx)}`;
+		});
+		const { sql: whereClause, values: whereValues } = buildWhere(conflictWhere, paramIdx.value, "duckdb");
+		const sql = `UPDATE ${table} SET ${assignments.join(", ")} ${whereClause}`;
+		try {
+			await connection.run(sql, [...values, ...whereValues]);
+			if (writeStrategy === "immediate") await exportTableToJSON(connection, table, dataDir);
+			return {
+				operation: "upsert",
+				affected: 1
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to upsert record into table", {
+				table,
+				sql,
+				values: [...values, ...whereValues],
+				conflictColumns,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Inserts a record or updates it if it already exists (UPSERT)
+	*
+	* @param table - Table name
+	* @param conflictColumns - Columns that define the uniqueness constraint
+	* @param data - Data to insert or update
+	* @returns Promise resolving to operation result
+	* @throws Error if the upsert operation fails
+	*/
+	const upsert = async (table, conflictColumns, data, options) => {
+		const missingColumns = conflictColumns.filter((col) => !(col in data));
+		if (missingColumns.length > 0) throw new DatabaseError("Conflict columns missing from data", {
+			table,
+			conflictColumns,
+			missingColumns,
+			availableColumns: Object.keys(data),
+			hint: "All columns specified in ON CONFLICT must be present in the data being inserted. Undefined values should be replaced with null or an appropriate default."
+		});
+		if (!options?.nullsDistinct && conflictColumns.some((col) => data[col] === null)) return executeNullAwareDuckDBUpsert(table, conflictColumns, data);
+		const keys = Object.keys(data);
+		const dataValues = Object.values(data);
+		const placeholders = [];
+		const values = [];
+		let paramIdx = 1;
+		for (const value of dataValues) if (value === null || value === void 0) placeholders.push("NULL");
+		else if (value === "" && typeof value === "string") {
+			placeholders.push(`CAST($${paramIdx} AS TEXT)`);
+			values.push(value);
+			paramIdx++;
+		} else if (value instanceof Date) {
+			placeholders.push(`$${paramIdx}`);
+			values.push(value.toISOString());
+			paramIdx++;
+		} else if (Array.isArray(value)) {
+			placeholders.push(`CAST($${paramIdx} AS JSON)`);
+			values.push(JSON.stringify(value));
+			paramIdx++;
+		} else if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+			placeholders.push(`CAST($${paramIdx} AS JSON)`);
+			values.push(JSON.stringify(value));
+			paramIdx++;
+		} else {
+			placeholders.push(`$${paramIdx}`);
+			values.push(value);
+			paramIdx++;
+		}
+		const updateSetParts = [];
+		for (let i = 0; i < keys.length; i++) {
+			const key = keys[i];
+			const value = dataValues[i];
+			if (value === null || value === void 0) updateSetParts.push(`${key} = NULL`);
+			else if (value === "" && typeof value === "string") {
+				updateSetParts.push(`${key} = CAST($${paramIdx} AS TEXT)`);
+				values.push(value);
+				paramIdx++;
+			} else if (value instanceof Date) {
+				updateSetParts.push(`${key} = $${paramIdx}`);
+				values.push(value.toISOString());
+				paramIdx++;
+			} else if (Array.isArray(value)) {
+				updateSetParts.push(`${key} = CAST($${paramIdx} AS JSON)`);
+				values.push(JSON.stringify(value));
+				paramIdx++;
+			} else if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+				updateSetParts.push(`${key} = CAST($${paramIdx} AS JSON)`);
+				values.push(JSON.stringify(value));
+				paramIdx++;
+			} else {
+				updateSetParts.push(`${key} = $${paramIdx}`);
+				values.push(value);
+				paramIdx++;
+			}
+		}
+		const conflict = conflictColumns.map((col) => `"${col}"`).join(", ");
+		const quotedKeys = keys.map((key) => `"${key}"`).join(", ");
+		const quotedUpdateSetParts = keys.map((key, i) => {
+			const part = updateSetParts[i];
+			return `"${key}" = ${part.substring(part.indexOf("=") + 1).trim()}`;
+		});
+		const sql = `INSERT INTO ${table} (${quotedKeys}) VALUES (${placeholders.join(", ")}) ON CONFLICT(${conflict}) DO UPDATE SET ${quotedUpdateSetParts.join(", ")}`;
+		try {
+			await connection.run(sql, values);
+			if (writeStrategy === "immediate") await exportTableToJSON(connection, table, dataDir);
+			return {
+				operation: "upsert",
+				affected: 1
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to upsert record into table", {
+				table,
+				sql,
+				values,
+				conflictColumns,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Gets a record matching the where criteria or inserts it if not found
+	*
+	* @param table - Table name
+	* @param where - Criteria to match existing record
+	* @param data - Data to insert if no record found
+	* @returns Promise resolving to the record (either retrieved or newly inserted)
+	* @throws Error if the operation fails
+	*/
+	const getOrInsert = async (table, where, data) => {
+		const result = await get(table, where);
+		if (result) return result;
+		await insert(table, data);
+		const inserted = await get(table, where);
+		if (!inserted) throw new DatabaseError("Failed to insert and retrieve record", {
+			table,
+			where,
+			data
+		});
+		return inserted;
+	};
+	/**
+	* Deletes records from a table matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records for deletion
+	* @returns Promise resolving to operation result with count of deleted rows
+	* @throws Error if the delete operation fails
+	*/
+	const deleteRecords = async (table, where) => {
+		validateTableName(table);
+		if (Object.keys(where).length === 0) throw new DatabaseError("DELETE requires at least one WHERE condition to prevent accidental deletion of all records", { table });
+		const { sql: whereClause, values } = buildWhere(where, 1, "duckdb");
+		const sql = `DELETE FROM ${table} ${whereClause}`;
+		try {
+			await connection.run(sql, values);
+			if (writeStrategy === "immediate") await exportTableToJSON(connection, table, dataDir);
+			return {
+				operation: "delete",
+				affected: 1
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to delete records from table", {
+				table,
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Counts records in a table matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records (optional, counts all if omitted)
+	* @returns Promise resolving to count of matching records
+	* @throws Error if the count operation fails
+	*/
+	const count = async (table, where) => {
+		validateTableName(table);
+		try {
+			if (!where || Object.keys(where).length === 0) {
+				const rows = (await connection.runAndReadAll(`SELECT COUNT(*) as count FROM ${table}`)).getRowObjects();
+				return Number(rows[0]?.count) || 0;
+			}
+			const { sql: whereClause, values } = buildWhere(where, 1, "duckdb");
+			const sql = `SELECT COUNT(*) as count FROM ${table} ${whereClause}`;
+			const rows = (await connection.runAndReadAll(sql, values)).getRowObjects();
+			return Number(rows[0]?.count) || 0;
+		} catch (e) {
+			throw new DatabaseError("Failed to count records in table", {
+				table,
+				where,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Checks if a table exists in the database
+	*
+	* @param tableName - Name of the table to check
+	* @returns Promise resolving to boolean indicating if the table exists
+	*/
+	const tableExists = async (tableName) => {
+		try {
+			await connection.runAndReadAll(`SELECT * FROM ${tableName} LIMIT 1`);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	/**
+	* Exports a table to a JSON file (for write-back strategies)
+	*
+	* @param connection - DuckDB connection
+	* @param table - Table name
+	* @param dataDir - Directory to write JSON file
+	*/
+	const exportTableToJSON = async (connection, table, dataDir) => {
+		const filePath = join(dataDir, `${table}.json`);
+		await connection.run(`COPY (SELECT * FROM ${table}) TO '${filePath}' (FORMAT JSON, ARRAY true)`);
+	};
+	/**
+	* Manual export method for 'manual' write strategy
+	*
+	* @param table - Table name to export
+	* @returns Promise that resolves when export completes
+	*/
+	const exportTable = async (table) => {
+		if (writeStrategy === "none") throw new DatabaseError("Cannot export table: write strategy is set to none", {
+			table,
+			writeStrategy
+		});
+		await exportTableToJSON(connection, table, dataDir);
+	};
+	/**
+	* Creates a table-specific interface for simplified table operations
+	*
+	* @param tableName - Table name
+	* @returns TableInterface for the specified table
+	*/
+	const table = (tableName) => ({
+		insert: (data) => insert(tableName, data),
+		get: (where) => get(tableName, where),
+		list: (where) => list(tableName, where)
+	});
+	/**
+	* Parses a tagged template literal into a SQL query and values
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Object with SQL query and values array
+	*/
+	const parseTemplate = (strings, ...vars) => {
+		let sql = strings[0];
+		const values = [];
+		for (let i = 0; i < vars.length; i++) {
+			values.push(vars[i]);
+			sql += `$${i + 1}${strings[i + 1]}`;
+		}
+		return {
+			sql,
+			values
+		};
+	};
+	/**
+	* Executes a SQL query using template literals and returns multiple rows
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Promise resolving to array of result records
+	* @throws Error if the query fails
+	*/
+	const many = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			return convertBigInts((await connection.runAndReadAll(sql, values)).getRowObjects());
+		} catch (e) {
+			throw new DatabaseError("Failed to execute many query", {
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Executes a SQL query using template literals and returns a single row
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Promise resolving to a single result record or null
+	* @throws Error if the query fails
+	*/
+	const single = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			const rows = (await connection.runAndReadAll(sql, values)).getRowObjects();
+			return rows[0] ? convertBigInts(rows[0]) : null;
+		} catch (e) {
+			throw new DatabaseError("Failed to execute single query", {
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Executes a SQL query using template literals and returns a single value
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Promise resolving to a single value (first column of first row)
+	* @throws Error if the query fails
+	*/
+	const pluck = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			const rows = (await connection.runAndReadAll(sql, values)).getRowObjects();
+			if (rows.length === 0) return null;
+			const firstRow = rows[0];
+			const firstKey = Object.keys(firstRow)[0];
+			return convertBigInts(firstRow[firstKey]);
+		} catch (e) {
+			throw new DatabaseError("Failed to execute pluck query", {
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Executes a SQL query using template literals without returning results
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Promise that resolves when the query completes
+	* @throws Error if the query fails
+	*/
+	const execute = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			await connection.run(sql, values);
+		} catch (e) {
+			throw new DatabaseError("Failed to execute query", {
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Executes a raw SQL query with parameterized values
+	*
+	* @param str - SQL query string
+	* @param values - Variables to use as parameters
+	* @returns Promise resolving to query result with rows and metadata
+	* @throws Error if the query fails
+	*/
+	const query = async (str, ...values) => {
+		const sql = str;
+		const args = Array.isArray(values[0]) ? values[0] : values;
+		try {
+			const rows = convertBigInts((await connection.runAndReadAll(sql, args)).getRowObjects());
+			return {
+				command: sql.split(" ")[0].toUpperCase(),
+				rowCount: rows.length,
+				oid: null,
+				fields: rows.length > 0 ? Object.keys(rows[0]).map((name) => ({
+					name,
+					tableID: 0,
+					columnID: 0,
+					dataTypeID: 0,
+					dataTypeSize: -1,
+					dataTypeModifier: -1,
+					format: "text"
+				})) : [],
+				rows
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to execute raw query", {
+				sql,
+				args,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	const oo = many;
+	const oO = single;
+	const ox = pluck;
+	const xx = execute;
+	/**
+	* Synchronizes database schema with provided SQL DDL
+	*
+	* DuckDB requires UNIQUE constraints to be defined **inline** in CREATE TABLE
+	* statements for ON CONFLICT clauses to work. This method automatically
+	* transforms UNIQUE indexes to inline constraints before executing the schema.
+	*
+	* @param schema - SQL schema definition with CREATE TABLE and CREATE INDEX statements
+	* @returns Promise that resolves when schema is synchronized
+	*/
+	const syncSchema = async (schema) => {
+		const statements = schema.trim().split(";").filter((stmt) => stmt.trim() !== "");
+		const createTableStatements = [];
+		const indexStatements = [];
+		for (const stmt of statements) {
+			const trimmed = stmt.trim();
+			if (!trimmed) continue;
+			if (trimmed.startsWith("CREATE INDEX") || trimmed.startsWith("CREATE UNIQUE INDEX")) indexStatements.push(trimmed);
+			else if (trimmed.startsWith("CREATE TABLE")) createTableStatements.push(trimmed);
+		}
+		for (const ddl of createTableStatements) {
+			const { ddl: transformedDDL, indexes: remainingIndexes } = convertUniqueIndexesToInlineConstraints(ddl, indexStatements);
+			try {
+				await connection.run(transformedDDL);
+			} catch (e) {
+				console.error("Schema sync error (CREATE TABLE):", e);
+			}
+			for (const indexSQL of remainingIndexes) try {
+				await connection.run(indexSQL);
+			} catch (e) {
+				console.error("Schema sync error (CREATE INDEX):", e);
+			}
+		}
+	};
+	/**
+	* Initialize database schemas from JSON manifest
+	* Supports dependency resolution and schema overrides
+	*
+	* @param options - Schema initialization options
+	* @returns Promise that resolves when schemas are initialized
+	*/
+	const initializeSchemas = async (options) => {
+		const schemaManager = new DatabaseSchemaManager();
+		const currentDb = {
+			url,
+			client: connection,
+			query,
+			insert,
+			update,
+			upsert,
+			get,
+			list,
+			getOrInsert,
+			delete: deleteRecords,
+			count,
+			table,
+			tableExists,
+			many,
+			single,
+			pluck,
+			execute,
+			oo,
+			oO,
+			ox,
+			xx,
+			syncSchema
+		};
+		await schemaManager.initializeSchemas(currentDb, options);
+	};
+	/**
+	* Retrieves the schema information for a table
+	*
+	* @param table - Table name
+	* @returns Promise resolving to table schema info or null if table doesn't exist
+	* @throws Error if the query fails
+	*/
+	const getTableSchema = async (table) => {
+		validateTableName(table);
+		try {
+			if (!await tableExists(table)) return null;
+			const columnRows = await many`
+        SELECT
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns
+        WHERE table_name = ${table}
+        ORDER BY ordinal_position
+      `;
+			const pkRows = await many`
+        SELECT column_name
+        FROM duckdb_constraints() con
+        JOIN duckdb_columns() cols
+          ON con.table_oid = cols.table_oid
+        WHERE con.table_name = ${table}
+          AND con.constraint_type = 'PRIMARY KEY'
+          AND cols.column_name = ANY(con.constraint_column_names)
+      `;
+			const pkColumns = new Set(pkRows.map((row) => row.column_name));
+			const columns = {};
+			for (const row of columnRows) {
+				const colName = row.column_name;
+				columns[colName] = {
+					type: row.data_type,
+					primaryKey: pkColumns.has(colName),
+					notNull: row.is_nullable === "NO",
+					defaultValue: row.column_default
+				};
+			}
+			const indexRows = await many`
+        SELECT
+          index_name,
+          sql
+        FROM duckdb_indexes()
+        WHERE table_name = ${table}
+          AND NOT is_primary
+      `;
+			const indexes = [];
+			for (const row of indexRows) {
+				const indexName = row.index_name;
+				const indexDef = row.sql || "";
+				const colMatch = indexDef.match(/\(([^)]+)\)/);
+				const indexColumns = colMatch ? colMatch[1].split(",").map((col) => col.trim()) : [];
+				const isUnique = indexDef.toUpperCase().includes("UNIQUE");
+				indexes.push({
+					name: indexName,
+					columns: indexColumns,
+					unique: isUnique
+				});
+			}
+			const fkRows = await many`
+        SELECT
+          constraint_column_names,
+          constraint_column_indexes,
+          constraint_text
+        FROM duckdb_constraints()
+        WHERE table_name = ${table}
+          AND constraint_type = 'FOREIGN KEY'
+      `;
+			const foreignKeys = [];
+			for (const fkRow of fkRows) {
+				const fkText = fkRow.constraint_text || "";
+				const referencesMatch = fkText.match(/REFERENCES\s+(\w+)\s*\(([^)]+)\)/i);
+				if (referencesMatch && Array.isArray(fkRow.constraint_column_names) && fkRow.constraint_column_names.length > 0) {
+					const columnName = fkRow.constraint_column_names[0];
+					const referencedTable = referencesMatch[1];
+					const referencedColumn = referencesMatch[2].trim();
+					const onDeleteMatch = fkText.match(/ON DELETE\s+(\w+)/i);
+					const onUpdateMatch = fkText.match(/ON UPDATE\s+(\w+)/i);
+					foreignKeys.push({
+						column: columnName,
+						referencesTable: referencedTable,
+						referencesColumn: referencedColumn,
+						onDelete: onDeleteMatch ? onDeleteMatch[1] : void 0,
+						onUpdate: onUpdateMatch ? onUpdateMatch[1] : void 0
+					});
+				}
+			}
+			return {
+				tableName: table,
+				columns,
+				indexes,
+				foreignKeys
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to retrieve table schema", {
+				table,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* ALTER TABLE operations for schema evolution
+	*/
+	const alterTable = {
+		/**
+		* Adds a new column to an existing table
+		*
+		* @param table - Table name
+		* @param column - Column definition with name
+		* @returns Promise that resolves when column is added
+		* @throws Error if the alter operation fails
+		*/
+		addColumn: async (table, column) => {
+			validateTableName(table);
+			validateColumnName(column.name);
+			try {
+				const sql = generateAddColumnStatement(table, column, "duckdb");
+				await connection.run(sql);
+			} catch (e) {
+				throw new DatabaseError("Failed to add column to table", {
+					table,
+					column: column.name,
+					originalError: formatDbError(e)
+				});
+			}
+		},
+		/**
+		* Adds a new index to an existing table
+		*
+		* @param table - Table name
+		* @param index - Index definition
+		* @returns Promise that resolves when index is created
+		* @throws Error if the create index operation fails
+		*/
+		addIndex: async (table, index) => {
+			validateTableName(table);
+			validateIndexName(index.name);
+			for (const col of index.columns) validateColumnName(col);
+			try {
+				const sql = generateCreateIndexStatement(table, index);
+				await connection.run(sql);
+			} catch (e) {
+				throw new DatabaseError("Failed to create index on table", {
+					table,
+					index: index.name,
+					originalError: formatDbError(e)
+				});
+			}
+		}
+	};
+	/**
+	* Executes a callback within a database transaction
+	* Automatically commits on success or rolls back on error
+	*
+	* @param callback - Function to execute within transaction
+	* @returns Promise resolving to callback result
+	*/
+	const transaction = async (callback) => {
+		try {
+			await connection.run("BEGIN TRANSACTION");
+			const result = await callback({
+				url,
+				client: connection,
+				insert,
+				get,
+				list,
+				update,
+				upsert,
+				getOrInsert,
+				delete: deleteRecords,
+				count,
+				table,
+				many,
+				single,
+				pluck,
+				execute,
+				query,
+				oo,
+				oO,
+				ox,
+				xx,
+				tableExists,
+				syncSchema,
+				transaction
+			});
+			await connection.run("COMMIT");
+			return result;
+		} catch (error) {
+			await connection.run("ROLLBACK");
+			throw error;
+		}
+	};
+	/**
+	* Begins a new transaction and returns a handle for manual control
+	*
+	* Unlike transaction(), this gives you explicit control over commit/rollback.
+	* Ideal for test isolation where you want to rollback after each test.
+	*
+	* @returns Promise resolving to a TransactionHandle
+	*/
+	const beginTransaction = async () => {
+		await connection.run("BEGIN TRANSACTION");
+		let active = true;
+		const commit = async () => {
+			if (!active) throw new DatabaseError("Transaction already ended", {});
+			await connection.run("COMMIT");
+			active = false;
+		};
+		const rollback = async () => {
+			if (!active) throw new DatabaseError("Transaction already ended", {});
+			await connection.run("ROLLBACK");
+			active = false;
+		};
+		const isActive = () => active;
+		return {
+			url,
+			client: connection,
+			insert,
+			get,
+			list,
+			update,
+			upsert,
+			getOrInsert,
+			delete: deleteRecords,
+			count,
+			table,
+			many,
+			single,
+			pluck,
+			execute,
+			query,
+			oo,
+			oO,
+			ox,
+			xx,
+			tableExists,
+			syncSchema,
+			transaction,
+			commit,
+			rollback,
+			isActive
+		};
+	};
+	return {
+		url,
+		requiresSchemaCheck: true,
+		client: connection,
+		query,
+		insert,
+		update,
+		upsert,
+		get,
+		list,
+		getOrInsert,
+		delete: deleteRecords,
+		count,
+		table,
+		tableExists,
+		many,
+		single,
+		pluck,
+		execute,
+		oo,
+		oO,
+		ox,
+		xx,
+		syncSchema,
+		initializeSchemas,
+		transaction,
+		beginTransaction,
+		getTableSchema,
+		alterTable,
+		exportTable
+	};
+}
+//#endregion
+export { getDatabase };
+
+//# sourceMappingURL=duckdb-DykBBzd6.js.map