@happyvertical/sql 0.80.0 → 0.80.1

package/dist/index.js

@@ -1,36 +1,3245 @@
-import "@happyvertical/utils";
-import { D, P, h, i, d, j, k, l, m, n, e, o, p, f, q, r, s, t, u, w } from "./chunks/index-CzdYvRFp.js";
-import { a, b, c, d as d2, e as e2, f as f2, i as i2, p as p2, r as r2, g } from "./chunks/postgres-cli-Cr6bBZ3q.js";
-export {
-  D as DatabaseSchemaManager,
-  P as PACKAGE_VERSION_INITIALIZED,
-  a as assertCanExportDatabase,
-  b as assertCanImportDatabase,
-  h as bucketExpr,
-  i as buildAggregate,
-  d as buildWhere,
-  j as checkExpectedTables,
-  k as checkRelationship,
-  l as checkUniqueColumn,
-  m as clearConnectionCache,
-  n as clearPostgresConnectionCache,
-  e as convertUniqueIndexesToInlineConstraints,
-  c as createPostgresDatabase,
-  d2 as databaseNameFromUrl,
-  o as default,
-  e2 as dropPostgresDatabase,
-  f2 as dumpPostgresDatabase,
-  p as escapeSqlValue,
-  f as formatDbError,
-  q as getDatabase,
-  i2 as isLocalDatabaseUrl,
-  p2 as postgresEnvFromUrl,
-  r2 as redactDatabaseUrl,
-  r as resolveSchemas,
-  g as restorePostgresDatabase,
-  s as runDoctor,
-  t as syncSchema,
-  u as tableExists,
-  w as validateColumnName
+import { i as parseConditionKey, n as buildWhere, r as formatDbError, t as DatabaseSchemaManager } from "./chunks/schema-manager-a8RlxIE2.js";
+import { t as convertUniqueIndexesToInlineConstraints } from "./chunks/duckdb-schema-utils-B-XBP8QF.js";
+import { a as dropPostgresDatabase, c as postgresEnvFromUrl, i as databaseNameFromUrl, l as redactDatabaseUrl, n as assertCanImportDatabase, o as dumpPostgresDatabase, r as createPostgresDatabase, s as isLocalDatabaseUrl, t as assertCanExportDatabase, u as restorePostgresDatabase } from "./chunks/postgres-cli-DzZcXSIG.js";
+import { a as validateTableName$1, i as validateIndexName, n as generateCreateIndexStatement, r as validateColumnName$1, t as generateAddColumnStatement } from "./chunks/alter-utils-K7tiuj5L.js";
+import { DatabaseError, loadEnvConfig } from "@happyvertical/utils";
+import { mkdir, readdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { Pool } from "pg";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
 };
-//# sourceMappingURL=index.js.map
+//#endregion
+//#region src/aggregate.ts
+var VALID_DIRECTIONS = /* @__PURE__ */ new Set(["ASC", "DESC"]);
+var VALID_BUCKET_UNITS = /* @__PURE__ */ new Set([
+	"minute",
+	"hour",
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"year"
+]);
+function validateSqlIdentifier(identifier) {
+	if (!/^[a-zA-Z0-9_.]+$/.test(identifier)) throw new Error(`Invalid SQL identifier: ${identifier}`);
+	return identifier;
+}
+function normalizeAdapter(adapterType) {
+	return adapterType ?? "sqlite";
+}
+function placeholder(index) {
+	return `$${index}`;
+}
+function bucketExpr(adapterType, unit, column) {
+	if (!VALID_BUCKET_UNITS.has(unit)) throw new Error(`Invalid aggregate bucket unit: ${unit}`);
+	const col = validateSqlIdentifier(column);
+	const adapter = normalizeAdapter(adapterType);
+	if (adapter === "postgres" || adapter === "duckdb" || adapter === "json") return `date_trunc('${unit}', ${col})`;
+	switch (unit) {
+		case "minute": return `strftime('%Y-%m-%d %H:%M:00', ${col})`;
+		case "hour": return `strftime('%Y-%m-%d %H:00:00', ${col})`;
+		case "day": return `strftime('%Y-%m-%d 00:00:00', ${col})`;
+		case "week": return `strftime('%Y-%m-%d 00:00:00', date(${col}, printf('-%d days', (CAST(strftime('%w', ${col}) AS INTEGER) + 6) % 7)))`;
+		case "month": return `strftime('%Y-%m-01 00:00:00', ${col})`;
+		case "quarter": return `strftime('%Y-%m-%d 00:00:00', date(strftime('%Y-', ${col}) || printf('%02d', ((CAST(strftime('%m', ${col}) AS INTEGER) - 1) / 3) * 3 + 1) || '-01'))`;
+		case "year": return `strftime('%Y-01-01 00:00:00', ${col})`;
+	}
+}
+function aggregateExpression(expr) {
+	const normalizedFn = String(expr.fn).toLowerCase();
+	const fn = validateSqlIdentifier(String(expr.fn)).toUpperCase();
+	if (normalizedFn === "count" && !expr.column) {
+		if (expr.distinct) throw new Error(`Aggregate ${expr.fn} with distinct requires a column`);
+		return "COUNT(*)";
+	}
+	if (!expr.column) throw new Error(`Aggregate ${expr.fn} requires a column`);
+	const col = validateSqlIdentifier(expr.column);
+	return `${fn}(${expr.distinct ? "DISTINCT " : ""}${col})`;
+}
+function selectExpression(expr, adapterType) {
+	if ("column" in expr && !("fn" in expr) && !("bucket" in expr)) return {
+		expression: validateSqlIdentifier(expr.column),
+		alias: validateSqlIdentifier(expr.as ?? expr.column),
+		groupingCandidate: true
+	};
+	if ("bucket" in expr) return {
+		expression: bucketExpr(adapterType, expr.bucket, expr.column),
+		alias: validateSqlIdentifier(expr.as),
+		groupingCandidate: true
+	};
+	return {
+		expression: aggregateExpression(expr),
+		alias: validateSqlIdentifier(expr.as),
+		groupingCandidate: false
+	};
+}
+function validateWhereShape(where) {
+	if (!where) return;
+	const validateKey = (key) => {
+		const { field } = parseConditionKey(key);
+		if (field) validateSqlIdentifier(field);
+	};
+	if (Array.isArray(where)) {
+		for (const andGroup of where) for (const condition of andGroup) for (const key of Object.keys(condition)) validateKey(key);
+		return;
+	}
+	for (const key of Object.keys(where)) validateKey(key);
+}
+function expandHavingKey(key, expressionByAlias) {
+	const parsed = parseConditionKey(key);
+	return `${expressionByAlias.get(parsed.field) ?? validateSqlIdentifier(parsed.field)} ${parsed.operator}`;
+}
+function expandHaving(having, expressionByAlias) {
+	const expandCondition = (condition) => Object.fromEntries(Object.entries(condition).map(([key, value]) => [expandHavingKey(key, expressionByAlias), value]));
+	if (Array.isArray(having)) return having.map((andGroup) => andGroup.map((condition) => expandCondition(condition)));
+	return expandCondition(having);
+}
+function buildHaving(having, expressionByAlias, startIndex, adapterType) {
+	if (!having) return {
+		sql: "",
+		values: []
+	};
+	const built = buildWhere(expandHaving(having, expressionByAlias), startIndex, adapterType);
+	return {
+		sql: built.sql ? built.sql.replace(/^WHERE/, "HAVING") : "",
+		values: built.values
+	};
+}
+function buildOrderBy(orderBy) {
+	if (!orderBy) return "";
+	return `ORDER BY ${(Array.isArray(orderBy) ? orderBy : [orderBy]).map((item) => {
+		const [field, direction = "ASC"] = item.trim().split(/\s+/);
+		const normalizedDirection = direction.toUpperCase();
+		if (!VALID_DIRECTIONS.has(normalizedDirection)) throw new Error(`Invalid aggregate order direction: ${direction}`);
+		return `${validateSqlIdentifier(field)} ${normalizedDirection}`;
+	}).join(", ")}`;
+}
+function buildAggregate(spec, startIndex = 1, adapterType) {
+	const from = validateSqlIdentifier(spec.from);
+	if (spec.select.length === 0) throw new Error("AggregateSpec.select must contain at least one expression");
+	validateWhereShape(spec.where);
+	const expressionByAlias = /* @__PURE__ */ new Map();
+	const groupingAliases = [];
+	const selectSql = spec.select.map((expr) => {
+		const selected = selectExpression(expr, adapterType);
+		expressionByAlias.set(selected.alias, selected.expression);
+		if (selected.groupingCandidate) groupingAliases.push(selected.alias);
+		return `${selected.expression} AS ${selected.alias}`;
+	});
+	const where = spec.where ? buildWhere(spec.where, startIndex, adapterType) : {
+		sql: "",
+		values: []
+	};
+	let nextParamIndex = startIndex + where.values.length;
+	const groupByItems = spec.groupBy ?? groupingAliases;
+	const groupBySql = groupByItems.length > 0 ? `GROUP BY ${groupByItems.map((item) => expressionByAlias.has(item) ? expressionByAlias.get(item) : validateSqlIdentifier(item)).join(", ")}` : "";
+	const having = buildHaving(spec.having, expressionByAlias, nextParamIndex, adapterType);
+	nextParamIndex += having.values.length;
+	const orderBySql = buildOrderBy(spec.orderBy);
+	const pagingValues = [];
+	const pagingSql = [];
+	if (spec.limit !== void 0) {
+		pagingSql.push(`LIMIT ${placeholder(nextParamIndex++)}`);
+		pagingValues.push(spec.limit);
+	} else if (spec.offset !== void 0 && normalizeAdapter(adapterType) === "sqlite") pagingSql.push("LIMIT -1");
+	if (spec.offset !== void 0) {
+		pagingSql.push(`OFFSET ${placeholder(nextParamIndex++)}`);
+		pagingValues.push(spec.offset);
+	}
+	return {
+		sql: [
+			`SELECT ${selectSql.join(", ")}`,
+			`FROM ${from}`,
+			where.sql,
+			groupBySql,
+			having.sql,
+			orderBySql,
+			pagingSql.join(" ")
+		].filter(Boolean).join(" "),
+		values: [
+			...where.values,
+			...having.values,
+			...pagingValues
+		]
+	};
+}
+//#endregion
+//#region src/doctor.ts
+/**
+* Database integrity-check framework.
+*
+* The runner is a thin loop over user-supplied checks; the value here is
+* the reusable check builders (expected tables, unique columns, FK-like
+* relationships) that codify the common shapes of integrity bugs that
+* sneak past schema migrations.
+*
+* No SMRT awareness — checks operate on the `DatabaseInterface` from this
+* package and on plain table/column names.
+*
+* **Postgres-only today.** The bundled check builders and
+* `listPublicTables` use Postgres syntax (`pg_tables`, `::int`/`::text`
+* casts). The shape is portable in principle — `DoctorContext` carries a
+* generic `DatabaseInterface` so apps can add engine-aware checks — but
+* the out-of-the-box runner expects a Postgres connection. `runDoctor`
+* throws early if pointed at a non-Postgres URL rather than failing
+* mid-execution with a confusing `pg_tables`-doesn't-exist error.
+*/
+/**
+* Execute every check against the public-schema tables of `db` and
+* partition the results by severity. Returns the aggregate; callers
+* format/exit as they see fit.
+*
+* The current table set is enumerated once and shared across checks so
+* each check can cheaply decide whether its target tables exist.
+*/
+async function runDoctor(options) {
+	assertPostgresAdapter(options.db);
+	const tables = await listPublicTables(options.db);
+	const issues = [];
+	for (const check of options.checks) {
+		const checkIssues = await check({
+			db: options.db,
+			tables
+		});
+		issues.push(...checkIssues);
+	}
+	return {
+		failures: issues.filter((issue) => issue.level === "fail"),
+		warnings: issues.filter((issue) => issue.level === "warn"),
+		issues
+	};
+}
+/**
+* Throw early if the supplied database isn't Postgres. The check builders
+* and `listPublicTables` use Postgres syntax; pointing them at SQLite or
+* DuckDB would fail mid-execution with a confusing "table pg_tables does
+* not exist" error from the adapter. Fail fast with a useful message
+* instead.
+*/
+function assertPostgresAdapter(db) {
+	const url = String(db.url ?? "");
+	if (!url.startsWith("postgres://") && !url.startsWith("postgresql://")) throw new Error(`runDoctor requires a Postgres database connection. Got URL: ${url ? redactDatabaseUrl(url) : "(empty)"}. The bundled check builders use Postgres-specific syntax (pg_tables, ::int/::text casts).`);
+}
+/**
+* Emit a 'warn' for each table in `expected` that's missing.
+*
+* Marked as `warn` rather than `fail` because a missing table often
+* indicates a migration that hasn't been run yet, not active data
+* corruption — callers can promote to fail by mapping the issues.
+*/
+function checkExpectedTables(expected) {
+	return async ({ tables }) => {
+		const issues = [];
+		for (const table of expected) if (!tables.has(table)) issues.push({
+			level: "warn",
+			message: `Missing expected table: ${table}`
+		});
+		return issues;
+	};
+}
+/**
+* Emit a 'fail' for each value that appears more than once in
+* `(table, column)` (ignoring NULL and empty-string values).
+*
+* Useful for catching slug/key collisions that the schema didn't
+* declare a UNIQUE constraint for (or where the constraint was added
+* after data already existed).
+*/
+function checkUniqueColumn(spec) {
+	return async ({ db, tables }) => {
+		if (!tables.has(spec.table)) return [];
+		return (await db.query(`
+      SELECT ${quoteIdentifier(spec.column)} AS value, count(*)::text AS count
+      FROM ${quoteIdentifier(spec.table)}
+      WHERE NULLIF(trim(${quoteIdentifier(spec.column)}::text), '') IS NOT NULL
+      GROUP BY ${quoteIdentifier(spec.column)}
+      HAVING count(*) > 1
+      ORDER BY count DESC, ${quoteIdentifier(spec.column)}
+    `)).rows.map((row) => ({
+			level: "fail",
+			message: `Duplicate ${spec.label} "${String(row.value)}" in ${spec.table} (${countValueFromRow(row.count)} rows).`
+		}));
+	};
+}
+/**
+* Emit a 'fail' counting orphan rows where the child column points at a
+* parent row that doesn't exist (FK-shaped check, but doesn't require an
+* actual FK constraint to be declared — useful for soft references like
+* tag-id-or-slug lookup columns).
+*/
+function checkRelationship(spec) {
+	return async ({ db, tables }) => {
+		if (!tables.has(spec.childTable) || !tables.has(spec.parentTable)) return [];
+		const parentColumn = spec.parentColumn ?? "id";
+		const orphanCount = countValueFromRow((await db.query(`
+      SELECT count(*)::text AS count
+      FROM ${quoteIdentifier(spec.childTable)} child
+      LEFT JOIN ${quoteIdentifier(spec.parentTable)} parent
+        ON parent.${quoteIdentifier(parentColumn)} = child.${quoteIdentifier(spec.childColumn)}
+      WHERE NULLIF(trim(child.${quoteIdentifier(spec.childColumn)}::text), '') IS NOT NULL
+        AND parent.${quoteIdentifier(parentColumn)} IS NULL
+    `)).rows[0]?.count);
+		if (orphanCount === "0") return [];
+		return [{
+			level: "fail",
+			message: `${spec.label}: ${orphanCount} orphaned row${orphanCount === "1" ? "" : "s"}.`
+		}];
+	};
+}
+async function listPublicTables(db) {
+	const result = await db.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename");
+	return new Set(result.rows.map((row) => String(row.tablename ?? "")));
+}
+function quoteIdentifier(value) {
+	return `"${value.replace(/"/gu, "\"\"")}"`;
+}
+function countValueFromRow(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	return "0";
+}
+//#endregion
+//#region src/shared/types.ts
+/**
+* Resolves a SchemasOption to its concrete value.
+*
+* Adapters that need schemas (JSON, DuckDB) call this to unwrap the
+* lazy function. Adapters that don't (Postgres, SQLite) simply ignore
+* the `schemas` option without calling this.
+*/
+function resolveSchemas(schemas) {
+	if (!schemas) return void 0;
+	if (typeof schemas === "function") return schemas();
+	return schemas;
+}
+//#endregion
+//#region src/json.ts
+var json_exports = /* @__PURE__ */ __exportAll({
+	clearConnectionCache: () => clearConnectionCache,
+	getDatabase: () => getDatabase$2
+});
+/**
+* Connection cache for in-memory DuckDB instances keyed by data directory URL
+* Enables sharing of in-memory databases across multiple getDatabase() calls
+* with the same data directory.
+*
+* Uses globalThis to ensure cache is shared across all module instances,
+* fixing the lost update bug in monorepos with workspace symlinks.
+*
+* @see https://github.com/happyvertical/sdk/issues/678
+*/
+globalThis.__haveSqlMemoryConnectionCache ??= /* @__PURE__ */ new Map();
+var memoryConnectionCache = globalThis.__haveSqlMemoryConnectionCache;
+/**
+* Pending connection promises to handle concurrent getDatabase() calls
+* Prevents creating duplicate connections when parallel calls happen.
+*
+* Uses globalThis to ensure cache is shared across all module instances.
+*
+* @see https://github.com/happyvertical/sdk/issues/678
+*/
+globalThis.__haveSqlPendingConnections ??= /* @__PURE__ */ new Map();
+var pendingConnections$1 = globalThis.__haveSqlPendingConnections;
+/**
+* Clears all cached connections
+* Useful for testing to ensure test isolation
+*/
+function clearConnectionCache() {
+	memoryConnectionCache.clear();
+	pendingConnections$1.clear();
+}
+/**
+* Creates a JSON database connection using DuckDB in-memory engine
+*
+* This adapter uses DuckDB as a query engine for JSON files, storing everything
+* in-memory and writing changes back to JSON files. No WAL files or persistent
+* database files are created.
+*
+* @param options - JSON database options
+* @returns Promise resolving to a DuckDB connection
+*/
+async function createJSONConnection(options) {
+	const { url, autoRegister = true, eagerLoadTables = true } = options;
+	const schemas = resolveSchemas(options.schemas) ?? {};
+	if (!url) throw new DatabaseError("url is required for JSON adapter", { options });
+	const pendingJSONFiles = /* @__PURE__ */ new Map();
+	const inferredSchemaTables = /* @__PURE__ */ new Set();
+	try {
+		const { DuckDBInstance } = await import(
+			/* @vite-ignore */
+			"@duckdb/node-api"
+);
+		const connection = await (await DuckDBInstance.create(":memory:")).connect();
+		try {
+			await mkdir(url, { recursive: true });
+		} catch (_error) {}
+		if (autoRegister) await loadJSONTables(connection, url, schemas, pendingJSONFiles, eagerLoadTables, inferredSchemaTables);
+		return {
+			connection,
+			pendingJSONFiles,
+			inferredSchemaTables
+		};
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		throw new DatabaseError(`Failed to create JSON database connection: ${errorMessage}`, {
+			url,
+			originalError: errorMessage
+		});
+	}
+}
+/**
+* Loads JSON data into an existing table
+*
+* This function only loads data - it assumes the table already exists with proper schema.
+* Used after DDL creates the table to load persisted JSON data.
+*
+* @param connection - DuckDB connection
+* @param tableName - Name of the table to load data into
+* @param filePath - Path to the JSON file
+*/
+async function loadJSONData(connection, tableName, filePath) {
+	try {
+		const { readFile } = await import("node:fs/promises");
+		const jsonContent = await readFile(filePath, "utf-8");
+		const records = JSON.parse(jsonContent);
+		if (Array.isArray(records) && records.length > 0) {
+			await insertRecordsWithCast(connection, tableName, records);
+			console.log(`[json-adapter] Loaded ${records.length} records into ${tableName} from JSON`);
+		}
+	} catch (error) {
+		console.warn(`[json-adapter] Could not load data for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Scans the data directory and registers JSON files for deferred loading
+*
+* Unlike the DuckDB adapter which creates views, this creates actual tables
+* so that indexes can be added.
+*
+* Schema resolution priority:
+* 1. Explicit schemas provided via options.schemas - table created immediately
+* 2. Schema file (.schema.sql) in data directory - table created with schema
+* 3. All other tables - DEFERRED until syncSchema() provides DDL
+*
+* IMPORTANT: Tables without explicit schemas are NOT auto-created from JSON.
+* This ensures UNIQUE constraints from syncSchema() are in place before data
+* is loaded, which is required for UPSERT operations to work correctly.
+*
+* For users who want auto-inference, use the inferSchemaFromJSON() method
+* after database creation.
+*
+* @param connection - DuckDB connection
+* @param dataDir - Directory containing JSON files
+* @param providedSchemas - Explicit schema definitions provided by caller (optional)
+* @param pendingJSONFiles - Map to store JSON files pending deferred loading
+* @param eagerLoadTables - Whether to eagerly create tables with inferred schemas
+* @param inferredSchemaTables - Set to track tables created with inferred schemas
+*/
+async function loadJSONTables(connection, dataDir, providedSchemas = {}, pendingJSONFiles = /* @__PURE__ */ new Map(), eagerLoadTables = true, inferredSchemaTables = /* @__PURE__ */ new Set()) {
+	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");
+			const schema = providedSchemas[tableName];
+			if (schema) {
+				console.log(`[json-adapter] Creating ${tableName} with provided schema definition`);
+				await createTableFromSchema(connection, tableName, schema);
+				await loadJSONData(connection, tableName, filePath);
+			} else {
+				const schemaPath = join(dataDir, `${tableName}.schema.sql`);
+				const { readFile, access } = await import("node:fs/promises");
+				const { constants } = await import("node:fs");
+				let schemaExists = false;
+				try {
+					await access(schemaPath, constants.F_OK);
+					schemaExists = true;
+				} catch {
+					schemaExists = false;
+				}
+				if (schemaExists) try {
+					const schemaDDL = await readFile(schemaPath, "utf-8");
+					await connection.run(schemaDDL);
+					await loadJSONData(connection, tableName, filePath);
+				} catch (error) {
+					console.warn(`[json-adapter] Could not load ${tableName} with schema file: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				else {
+					if (eagerLoadTables) try {
+						await connection.run(`CREATE TABLE IF NOT EXISTS "${tableName}" AS SELECT * FROM read_json_auto('${filePath}')`);
+						inferredSchemaTables.add(tableName);
+						console.log(`[json-adapter] Eagerly created ${tableName} with inferred schema (no UNIQUE constraints)`);
+					} catch (error) {
+						console.warn(`[json-adapter] Could not eagerly load ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+					}
+					else console.log(`[json-adapter] Deferring ${tableName} - will load after syncSchema() creates table`);
+					pendingJSONFiles.set(tableName, filePath);
+				}
+			}
+		}
+	} catch (error) {
+		if (error.code !== "ENOENT") {
+			console.error("[json-adapter] Error loading JSON tables:", error);
+			throw new DatabaseError(`Failed to load JSON tables from ${dataDir}`, {
+				dataDir,
+				originalError: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : void 0
+			});
+		}
+	}
+}
+/**
+* Converts DuckDB-specific type representations to JavaScript types
+*
+* Handles three cases:
+* 1. JavaScript BigInt values → converted to numbers
+* 2. DuckDB hugeint objects ({ hugeint: number }) → converted to strings
+* 3. DuckDB timestamp objects ({ micros: number }) → converted to Date objects
+*
+* DuckDB represents HUGEINT (128-bit integers) as objects with a single
+* property called 'hugeint'. When UUID strings (stored as TEXT) are
+* exported to JSON via COPY TO, DuckDB sometimes converts them to hugeint
+* representation. This function converts them back to strings.
+*
+* 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 round-trip serialization.
+*
+* @param obj - Object that may contain BigInt, hugeint, 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) && "hugeint" in obj && Object.keys(obj).length === 1) return String(obj.hugeint);
+	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 table from a schema definition with proper typing
+*
+* DuckDB has issues with type inference when DEFAULT values are empty strings.
+* This function explicitly casts all DEFAULT values to their column types to
+* prevent DuckDB from inferring ANY type.
+*
+* Additionally, 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 tableName - Name of the table to create
+* @param schema - Schema definition with DDL and indexes
+*/
+async function createTableFromSchema(connection, tableName, schema) {
+	const ddlLines = schema.ddl.split("\n");
+	const createTableEnd = ddlLines.findIndex((line) => {
+		const trimmed = line.trim();
+		return trimmed === ")" || trimmed.startsWith(");");
+	});
+	if (createTableEnd === -1) throw new DatabaseError("Invalid schema DDL - no closing parenthesis", {
+		tableName,
+		ddl: schema.ddl
+	});
+	let createTableSQL = ddlLines.slice(0, createTableEnd + 1).join("\n");
+	createTableSQL = createTableSQL.replace(/\b(\w+)\s+(TEXT|VARCHAR)\s+DEFAULT\s+''/g, "$1 $2 DEFAULT CAST('' AS $2)");
+	createTableSQL = createTableSQL.replace(/\b(\w+)\s+(TEXT|VARCHAR)\s+DEFAULT\s+NULL/g, "$1 $2 DEFAULT CAST(NULL AS $2)");
+	const transformed = convertUniqueIndexesToInlineConstraints(createTableSQL, schema.indexes);
+	createTableSQL = transformed.ddl;
+	const indexesToCreate = transformed.indexes;
+	try {
+		await connection.run(createTableSQL);
+		let existingColumns = /* @__PURE__ */ new Set();
+		try {
+			const columns = (await connection.runAndReadAll(`DESCRIBE ${tableName}`)).getRowObjects();
+			existingColumns = new Set(columns.map((col) => col.column_name.toLowerCase()));
+			console.log(`[json-adapter] Created ${tableName} with schema:`, { columns: columns.map((col) => ({
+				name: col.column_name,
+				type: col.column_type,
+				null: col.null
+			})) });
+		} catch (error) {
+			console.warn(`[json-adapter] Could not verify schema for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (schema.fields && existingColumns.size > 0) {
+			const fieldEntries = schema.fields instanceof Map ? Array.from(schema.fields.entries()) : Object.entries(schema.fields);
+			for (const [fieldName, fieldDef] of fieldEntries) {
+				const columnName = fieldName.toLowerCase();
+				if (!existingColumns.has(columnName)) {
+					const sqlType = fieldDef?.type || "TEXT";
+					try {
+						await connection.run(`ALTER TABLE ${tableName} ADD COLUMN "${fieldName}" ${sqlType}`);
+						console.log(`[json-adapter] Added missing column '${fieldName}' (${sqlType}) to ${tableName}`);
+					} catch (alterError) {
+						console.warn(`[json-adapter] Could not add column '${fieldName}' to ${tableName}: ${alterError instanceof Error ? alterError.message : String(alterError)}`);
+					}
+				}
+			}
+		}
+		if (indexesToCreate && indexesToCreate.length > 0) for (const indexSQL of indexesToCreate) try {
+			await connection.run(indexSQL);
+		} catch (error) {
+			console.warn(`[json-adapter] Failed to create index: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	} catch (error) {
+		throw new DatabaseError("Failed to create table from schema", {
+			tableName,
+			sql: createTableSQL,
+			originalError: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+/**
+* Inserts records with proper CAST handling for empty strings
+*
+* This helper avoids using read_json() with auto_detect, which causes DuckDB
+* to re-infer column types from data (causing ANY type for empty strings).
+* Instead, it uses parameterized INSERT with CAST to maintain table schema.
+*
+* @param connection - DuckDB connection
+* @param tableName - Name of the table to insert into
+* @param records - Array of records to insert
+*/
+async function insertRecordsWithCast(connection, tableName, records) {
+	if (records.length === 0) return;
+	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) 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 `CAST($${paramIdx++} AS TIMESTAMP)`;
+			} 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 ${tableName} (${keys.join(", ")}) VALUES ${placeholders}`;
+	await connection.run(sql, values);
+}
+/**
+* Validates that a table name is valid (alphanumeric + underscores only)
+*
+* @param table - Table name to validate
+* @throws DatabaseError if table name is invalid
+*/
+function validateTableName(table) {
+	if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) throw new DatabaseError(`Invalid table name: ${table}`, { table });
+}
+/**
+* Creates a JSON database adapter using DuckDB in-memory engine
+*
+* This adapter provides SQL query capabilities over JSON files without creating
+* persistent database files or WAL files. All data is stored in-memory during
+* runtime and written back to JSON files based on the write strategy.
+*
+* @param options - JSON database options
+* @returns Database interface for JSON files
+*/
+async function getDatabase$2(options) {
+	const cacheKey = options.dbid || `json:${options.url}:${options.writeStrategy || "immediate"}:${options.autoRegister !== false}`;
+	if (options.clearCache) {
+		memoryConnectionCache.delete(cacheKey);
+		pendingConnections$1.delete(cacheKey);
+	}
+	const cached = memoryConnectionCache.get(cacheKey);
+	if (cached) return cached;
+	const pending = pendingConnections$1.get(cacheKey);
+	if (pending) return pending;
+	const connectionPromise = (async () => {
+		const { connection, pendingJSONFiles, inferredSchemaTables } = await createJSONConnection(options);
+		const writeStrategy = options.writeStrategy || "immediate";
+		const { url } = options;
+		/**
+		* 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) => {
+			validateTableName(table);
+			if (writeStrategy === "none") throw new DatabaseError("Cannot insert: write strategy is set to none (read-only mode)", {
+				table,
+				writeStrategy
+			});
+			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) 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 `CAST($${paramIdx++} AS TIMESTAMP)`;
+					} 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, url);
+				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) => {
+			validateTableName(table);
+			const { sql: whereClause, values } = buildWhere(where, 1, "json");
+			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) => {
+			validateTableName(table);
+			const { sql: whereClause, values } = buildWhere(where, 1, "json");
+			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) => {
+			validateTableName(table);
+			if (writeStrategy === "none") throw new DatabaseError("Cannot update: write strategy is set to none (read-only mode)", {
+				table,
+				writeStrategy
+			});
+			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, "json");
+			const dataValues = Object.values(data).map((value) => value instanceof Date ? value.toISOString() : value);
+			const sql = `UPDATE "${table}" SET ${setClause} ${whereClause}`;
+			const values = [...dataValues, ...whereValues];
+			try {
+				await connection.run(sql, values);
+				if (writeStrategy === "immediate") await exportTableToJSON(connection, table, url);
+				return {
+					operation: "update",
+					affected: 1
+				};
+			} catch (e) {
+				throw new DatabaseError("Failed to update records in table", {
+					table,
+					sql,
+					values,
+					originalError: formatDbError(e)
+				});
+			}
+		};
+		const buildJSONValueExpression = (value, values, paramIdx) => {
+			if (value === null) 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 `CAST($${paramIdx.value++} AS TIMESTAMP)`;
+			}
+			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 executeNullAwareJSONUpsert = 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}" = ${buildJSONValueExpression(data[key], values, paramIdx)}`;
+			});
+			const { sql: whereClause, values: whereValues } = buildWhere(conflictWhere, paramIdx.value, "json");
+			const sql = `UPDATE "${table}" SET ${assignments.join(", ")} ${whereClause}`;
+			try {
+				await connection.run(sql, [...values, ...whereValues]);
+				if (writeStrategy === "immediate") await exportTableToJSON(connection, table, url);
+				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) => {
+			validateTableName(table);
+			if (writeStrategy === "none") throw new DatabaseError("Cannot upsert: write strategy is set to none (read-only mode)", {
+				table,
+				writeStrategy
+			});
+			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 executeNullAwareJSONUpsert(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) 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(`CAST($${paramIdx} AS TIMESTAMP)`);
+				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) 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} = CAST($${paramIdx} AS TIMESTAMP)`);
+					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, url);
+				return {
+					operation: "upsert",
+					affected: 1
+				};
+			} catch (e) {
+				console.error("UPSERT failed:", {
+					table,
+					sql,
+					values,
+					valueTypes: values.map((v) => `${typeof v} (${v})`),
+					conflictColumns,
+					error: formatDbError(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 (writeStrategy === "none") throw new DatabaseError("Cannot delete: write strategy is set to none (read-only mode)", {
+				table,
+				writeStrategy
+			});
+			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, "json");
+			const sql = `DELETE FROM "${table}" ${whereClause}`;
+			try {
+				await connection.run(sql, values);
+				if (writeStrategy === "immediate") await exportTableToJSON(connection, table, url);
+				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, "json");
+				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 JSON and schema files
+		*
+		* Exports two files:
+		* 1. {table}.json - Table data with columns cast appropriately
+		* 2. {table}.schema.sql - CREATE TABLE statement to preserve constraints
+		*
+		* Note: JSON columns are NOT cast to TEXT to preserve object structure.
+		* Other columns are cast to TEXT to prevent DuckDB from converting UUIDs
+		* and other TEXT values to hugeint representation in JSON output.
+		*
+		* @param connection - DuckDB connection
+		* @param table - Table name
+		* @param dataDir - Directory to write files
+		*/
+		const exportTableToJSON = async (connection, table, dataDir) => {
+			const filePath = join(dataDir, `${table}.json`);
+			const schemaPath = join(dataDir, `${table}.schema.sql`);
+			try {
+				const rows = (await connection.runAndReadAll(`SELECT sql FROM sqlite_master WHERE type='table' AND name='${table}'`)).getRowObjects();
+				if (rows.length > 0 && rows[0].sql) {
+					const { writeFile } = await import("node:fs/promises");
+					await writeFile(schemaPath, rows[0].sql, "utf-8");
+				}
+			} catch (error) {
+				console.warn(`[json-adapter] Could not export schema for ${table}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const columnInfo = (await connection.runAndReadAll(`SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '${table}' ORDER BY ordinal_position`)).getRowObjects();
+			if (columnInfo.length === 0) {
+				await connection.run(`COPY (SELECT * FROM "${table}") TO '${filePath}' (FORMAT JSON, ARRAY true)`);
+				return;
+			}
+			const sql = `COPY (SELECT ${columnInfo.map(({ column_name, data_type }) => {
+				const upperType = data_type.toUpperCase();
+				if (upperType === "JSON" || upperType.startsWith("STRUCT")) return `"${column_name}"`;
+				if ([
+					"DOUBLE",
+					"REAL",
+					"FLOAT",
+					"INTEGER",
+					"BIGINT",
+					"SMALLINT",
+					"TINYINT",
+					"DECIMAL",
+					"NUMERIC",
+					"HUGEINT",
+					"UBIGINT",
+					"UINTEGER",
+					"USMALLINT",
+					"UTINYINT"
+				].some((t) => upperType.includes(t))) return `"${column_name}"`;
+				if (upperType === "BOOLEAN" || upperType === "BOOL") return `"${column_name}"`;
+				return `CAST("${column_name}" AS TEXT) AS "${column_name}"`;
+			}).join(", ")} FROM "${table}") TO '${filePath}' (FORMAT JSON, ARRAY true)`;
+			await connection.run(sql);
+		};
+		/**
+		* Manual export method for 'manual' write strategy
+		*
+		* Allows explicit control over when tables are written back to JSON files.
+		*
+		* @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 (read-only mode)", {
+				table,
+				writeStrategy
+			});
+			await exportTableToJSON(connection, table, url);
+		};
+		/**
+		* Creates a table by inferring schema from a JSON file
+		*
+		* This utility is for users who want automatic schema inference from JSON.
+		* Note: Inferred schemas do NOT include UNIQUE constraints, so UPSERT
+		* operations will fail. Use syncSchema() with explicit DDL for UPSERT support.
+		*
+		* @param tableName - Name of the table to create
+		* @param jsonPath - Optional path to JSON file (defaults to {dataDir}/{tableName}.json)
+		* @returns Promise that resolves when table is created
+		* @throws Error if JSON file doesn't exist or table creation fails
+		*/
+		const inferSchemaFromJSON = async (tableName, jsonPath) => {
+			validateTableName(tableName);
+			const filePath = jsonPath || join(url, `${tableName}.json`);
+			try {
+				const { access } = await import("node:fs/promises");
+				const { constants } = await import("node:fs");
+				await access(filePath, constants.F_OK);
+				console.log(`[json-adapter] Inferring schema for ${tableName} from JSON file`);
+				await connection.run(`CREATE TABLE "${tableName}" AS SELECT * FROM read_json_auto('${filePath}')`);
+				pendingJSONFiles.delete(tableName);
+				console.log(`[json-adapter] Created ${tableName} with inferred schema (no UNIQUE constraints)`);
+			} catch (error) {
+				throw new DatabaseError(`Failed to infer schema from JSON for table ${tableName}`, {
+					tableName,
+					jsonPath: filePath,
+					originalError: error instanceof Error ? error.message : String(error)
+				});
+			}
+		};
+		/**
+		* 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);
+				const createTableMatch = sql.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i);
+				if (createTableMatch) {
+					const tableName = createTableMatch[1];
+					const pendingFile = pendingJSONFiles.get(tableName);
+					if (pendingFile) {
+						await loadJSONData(connection, tableName, pendingFile);
+						pendingJSONFiles.delete(tableName);
+					} else if (writeStrategy !== "none") try {
+						const { access } = await import("node:fs/promises");
+						const jsonFilePath = join(url, `${tableName}.json`);
+						try {
+							await access(jsonFilePath);
+						} catch {
+							await exportTableToJSON(connection, tableName, url);
+						}
+					} catch (error) {
+						console.warn(`[json-adapter] Could not export newly created table ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+					}
+				}
+			} 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
+		*
+		* Filters out CREATE TRIGGER statements since triggers are not supported
+		* in the JSON adapter (timestamps managed at application level).
+		*
+		* @param schema - SQL schema definition with CREATE TABLE 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 = [];
+			const otherStatements = [];
+			for (const stmt of statements) {
+				const trimmed = stmt.trim();
+				if (!trimmed) continue;
+				const upperTrimmed = trimmed.toUpperCase();
+				if (upperTrimmed.startsWith("CREATE TRIGGER")) {
+					console.warn("[json-adapter] Skipping trigger creation - timestamps managed at application level");
+					continue;
+				}
+				if (upperTrimmed.startsWith("CREATE INDEX") || upperTrimmed.startsWith("CREATE UNIQUE INDEX")) indexStatements.push(trimmed);
+				else if (upperTrimmed.startsWith("CREATE TABLE")) createTableStatements.push(trimmed);
+				else otherStatements.push(trimmed);
+			}
+			for (const ddl of createTableStatements) {
+				const { ddl: transformedDDL, indexes: remainingIndexes } = convertUniqueIndexesToInlineConstraints(ddl, indexStatements);
+				const createTableMatch = transformedDDL.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i);
+				const tableName = createTableMatch ? createTableMatch[1] : null;
+				if (tableName && inferredSchemaTables.has(tableName)) try {
+					await connection.run(`DROP TABLE IF EXISTS "${tableName}"`);
+					inferredSchemaTables.delete(tableName);
+					console.log(`[json-adapter] Dropped inferred-schema table ${tableName} for schema upgrade`);
+				} catch (error) {
+					console.warn(`[json-adapter] Could not drop inferred-schema table ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				try {
+					await connection.run(transformedDDL);
+					if (tableName) {
+						const pendingFile = pendingJSONFiles.get(tableName);
+						if (pendingFile) {
+							await loadJSONData(connection, tableName, pendingFile);
+							pendingJSONFiles.delete(tableName);
+						} else if (writeStrategy !== "none") try {
+							const { access } = await import("node:fs/promises");
+							const jsonFilePath = join(url, `${tableName}.json`);
+							try {
+								await access(jsonFilePath);
+							} catch {
+								await exportTableToJSON(connection, tableName, url);
+							}
+						} catch (error) {
+							console.warn(`[json-adapter] Could not export newly created table ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+						}
+					}
+				} 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);
+				}
+			}
+			for (const stmt of otherStatements) try {
+				await connection.run(stmt);
+			} catch (e) {
+				console.error("Schema sync error:", 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);
+		};
+		/**
+		* 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,
+			exportTable,
+			inferSchemaFromJSON
+		};
+	})();
+	pendingConnections$1.set(cacheKey, connectionPromise);
+	try {
+		const db = await connectionPromise;
+		memoryConnectionCache.set(cacheKey, db);
+		return db;
+	} finally {
+		pendingConnections$1.delete(cacheKey);
+	}
+}
+//#endregion
+//#region src/postgres.ts
+var postgres_exports = /* @__PURE__ */ __exportAll({
+	clearPostgresConnectionCache: () => clearPostgresConnectionCache,
+	getDatabase: () => getDatabase$1
+});
+/**
+* Module-level cache for PostgreSQL connections.
+* Keyed by dbid (or derived from connection URL).
+* Prevents creating multiple pg.Pool instances for the same database.
+*/
+var connectionCache = /* @__PURE__ */ new Map();
+var pendingConnections = /* @__PURE__ */ new Map();
+/**
+* Clears the PostgreSQL connection cache.
+* Useful for test isolation and reconnection scenarios.
+*/
+function clearPostgresConnectionCache() {
+	connectionCache.clear();
+	pendingConnections.clear();
+}
+/**
+* Operator for the given distance metric in pgvector
+*/
+function vectorOperator(metric) {
+	switch (metric) {
+		case "cosine": return "<=>";
+		case "l2": return "<->";
+		case "ip": return "<#>";
+		default: return "<=>";
+	}
+}
+function getMaxPostgresParameterIndex(sql) {
+	let maxIndex = 0;
+	for (const match of sql.matchAll(/\$(\d+)/g)) {
+		const index = Number(match[1]);
+		if (Number.isSafeInteger(index) && index > maxIndex) maxIndex = index;
+	}
+	return maxIndex;
+}
+function usesSingleArrayParameter(sql) {
+	const identifier = String.raw`(?:"[^"]+"|[a-z_][\w$]*)`;
+	const qualifiedIdentifier = String.raw`${identifier}(?:\s*\.\s*${identifier})?`;
+	const arrayType = String.raw`${qualifiedIdentifier}(?:\s*\([^)]*\))?\s*\[\]`;
+	return new RegExp(String.raw`\$1\s*::\s*${arrayType}`, "i").test(sql) || new RegExp(String.raw`\bCAST\s*\(\s*\$1\s+AS\s+${arrayType}\s*\)`, "i").test(sql) || /\b(?:ANY|ALL|SOME)\s*\(\s*\$1\s*\)/i.test(sql);
+}
+function normalizeRawQueryValues(sql, values) {
+	if (values.length !== 1 || !Array.isArray(values[0])) return values;
+	const valuesArray = values[0];
+	const maxParameterIndex = getMaxPostgresParameterIndex(sql);
+	if (maxParameterIndex === 1 && usesSingleArrayParameter(sql)) return values;
+	if (maxParameterIndex === 0 || maxParameterIndex === valuesArray.length) return valuesArray;
+	return values;
+}
+function rewriteQuestionMarkPlaceholders(sql) {
+	let output = "";
+	let count = 0;
+	let index = 0;
+	const copyQuoted = (quote, escaped = false) => {
+		output += quote;
+		index += 1;
+		while (index < sql.length) {
+			const char = sql[index];
+			output += char;
+			index += 1;
+			if (escaped && char === "\\" && index < sql.length) {
+				output += sql[index];
+				index += 1;
+				continue;
+			}
+			if (char === quote) {
+				if (sql[index] === quote) {
+					output += sql[index];
+					index += 1;
+					continue;
+				}
+				break;
+			}
+		}
+	};
+	const copyUntil = (end) => {
+		const endIndex = sql.indexOf(end, index + end.length);
+		if (endIndex === -1) {
+			output += sql.slice(index);
+			index = sql.length;
+			return;
+		}
+		output += sql.slice(index, endIndex + end.length);
+		index = endIndex + end.length;
+	};
+	while (index < sql.length) {
+		const char = sql[index];
+		const next = sql[index + 1];
+		if ((char === "E" || char === "e") && next === "'") {
+			output += char;
+			index += 1;
+			copyQuoted("'", true);
+			continue;
+		}
+		if (char === "'") {
+			copyQuoted("'");
+			continue;
+		}
+		if (char === "\"") {
+			copyQuoted("\"");
+			continue;
+		}
+		if (char === "-" && next === "-") {
+			const endIndex = sql.indexOf("\n", index + 2);
+			if (endIndex === -1) {
+				output += sql.slice(index);
+				index = sql.length;
+			} else {
+				output += sql.slice(index, endIndex + 1);
+				index = endIndex + 1;
+			}
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			copyUntil("*/");
+			continue;
+		}
+		if (char === "$") {
+			const tag = sql.slice(index).match(/^\$[A-Za-z_][\w$]*\$|^\$\$/);
+			if (tag) {
+				copyUntil(tag[0]);
+				continue;
+			}
+		}
+		if (char === "?" && next !== "|" && next !== "&") {
+			count += 1;
+			output += `$${count}`;
+			index += 1;
+			continue;
+		}
+		output += char;
+		index += 1;
+	}
+	return {
+		sql: output,
+		count
+	};
+}
+function usesSingleQuestionArrayParameter(sql) {
+	const identifier = String.raw`(?:"[^"]+"|[a-z_][\w$]*)`;
+	const qualifiedIdentifier = String.raw`${identifier}(?:\s*\.\s*${identifier})?`;
+	const arrayType = String.raw`${qualifiedIdentifier}(?:\s*\([^)]*\))?\s*\[\]`;
+	return new RegExp(String.raw`\?\s*::\s*${arrayType}`, "i").test(sql) || new RegExp(String.raw`\bCAST\s*\(\s*\?\s+AS\s+${arrayType}\s*\)`, "i").test(sql) || /\b(?:ANY|ALL|SOME)\s*\(\s*\?\s*\)/i.test(sql);
+}
+function normalizeQuestionMarkQueryValues(sql, values, placeholderCount) {
+	if (values.length !== 1 || !Array.isArray(values[0])) return values;
+	if (placeholderCount === 1 && usesSingleQuestionArrayParameter(sql)) return values;
+	if (placeholderCount === values[0].length) return values[0];
+	return values;
+}
+function normalizePostgresRawQuery(sql, values) {
+	if (getMaxPostgresParameterIndex(sql) > 0) return {
+		sql,
+		values: normalizeRawQueryValues(sql, values)
+	};
+	const rewritten = rewriteQuestionMarkPlaceholders(sql);
+	const placeholderCount = rewritten.count;
+	const queryValues = normalizeQuestionMarkQueryValues(sql, values, placeholderCount);
+	if (placeholderCount > 0 && placeholderCount === queryValues.length) return {
+		sql: rewritten.sql,
+		values: queryValues
+	};
+	return {
+		sql,
+		values: normalizeRawQueryValues(sql, values)
+	};
+}
+/**
+* pgvector index operator class for CREATE INDEX
+*/
+function vectorOpsClass(metric) {
+	switch (metric) {
+		case "cosine": return "vector_cosine_ops";
+		case "l2": return "vector_l2_ops";
+		case "ip": return "vector_ip_ops";
+		default: return "vector_cosine_ops";
+	}
+}
+/**
+* Convert a number[] to a pgvector literal string: '[0.1,0.2,0.3]'
+*/
+function toVectorLiteral(embedding) {
+	if (embedding.length === 0) throw new DatabaseError("Vector embedding must not be empty", {});
+	for (let i = 0; i < embedding.length; i++) if (!Number.isFinite(embedding[i])) throw new DatabaseError("Vector embedding contains invalid value (NaN or Infinity)", {
+		index: i,
+		value: embedding[i]
+	});
+	return `[${embedding.join(",")}]`;
+}
+/**
+* Creates vector capabilities backed by pgvector for a PostgreSQL pool.
+*
+* @param pool - PostgreSQL connection pool
+* @returns VectorCapabilities implementation
+*/
+function createVectorCapabilities(pool) {
+	return {
+		async ensureColumn(table, column, dimensions) {
+			if (!Number.isInteger(dimensions) || dimensions <= 0) throw new DatabaseError("Vector dimensions must be a positive integer", { dimensions });
+			try {
+				await pool.query("CREATE EXTENSION IF NOT EXISTS vector");
+				await pool.query(`ALTER TABLE "${table}" ADD COLUMN IF NOT EXISTS "${column}" vector(${dimensions})`);
+			} catch (e) {
+				throw new DatabaseError("Failed to ensure vector column", {
+					table,
+					column,
+					dimensions,
+					originalError: formatDbError(e)
+				});
+			}
+		},
+		async ensureIndex(table, column, options) {
+			const metric = options?.metric || "cosine";
+			const indexType = options?.type || "hnsw";
+			const opsClass = vectorOpsClass(metric);
+			const indexName = `idx_${table}_${column}_${metric}_${indexType}`;
+			try {
+				await pool.query(`CREATE INDEX IF NOT EXISTS "${indexName}" ON "${table}" USING ${indexType} ("${column}" ${opsClass})`);
+			} catch (e) {
+				throw new DatabaseError("Failed to ensure vector index", {
+					table,
+					column,
+					indexName,
+					originalError: formatDbError(e)
+				});
+			}
+		},
+		async upsertVector(table, where, column, embedding) {
+			const keys = Object.keys(where);
+			const values = Object.values(where);
+			const conditions = keys.map((key, i) => `"${key}" IS NOT DISTINCT FROM $${i + 1}`).join(" AND ");
+			const vectorParam = `$${values.length + 1}`;
+			try {
+				await pool.query(`UPDATE "${table}" SET "${column}" = ${vectorParam}::vector WHERE ${conditions}`, [...values, toVectorLiteral(embedding)]);
+			} catch (e) {
+				throw new DatabaseError("Failed to upsert vector", {
+					table,
+					column,
+					where,
+					originalError: formatDbError(e)
+				});
+			}
+		},
+		async search(table, column, embedding, options) {
+			const metric = options?.metric || "cosine";
+			const limit = options?.limit || 10;
+			const op = vectorOperator(metric);
+			const queryParams = [toVectorLiteral(embedding)];
+			let whereClause = `"${column}" IS NOT NULL`;
+			if (options?.where) {
+				whereClause += ` AND (${options.where})`;
+				if (options.params) queryParams.push(...options.params);
+			}
+			const limitParam = `$${queryParams.length + 1}`;
+			queryParams.push(limit);
+			const sql = `SELECT *, ("${column}" ${op} $1::vector) AS distance FROM "${table}" WHERE ${whereClause} ORDER BY "${column}" ${op} $1::vector LIMIT ${limitParam}`;
+			try {
+				return (await pool.query(sql, queryParams)).rows.map((row) => ({
+					...row,
+					id: row.id,
+					distance: Number.parseFloat(row.distance)
+				}));
+			} catch (e) {
+				throw new DatabaseError("Failed to execute vector search", {
+					table,
+					column,
+					metric,
+					limit,
+					originalError: formatDbError(e)
+				});
+			}
+		}
+	};
+}
+/**
+* Creates a PostgreSQL database adapter
+*
+* Loads configuration from environment variables with backward compatibility:
+* - First checks HAVE_SQL_* environment variables (new standard)
+* - Falls back to SQLOO_* environment variables (legacy)
+* - User-provided options always take precedence
+*
+* Environment variables:
+* - HAVE_SQL_URL / SQLOO_URL → Connection string (takes precedence)
+* - HAVE_SQL_DATABASE / SQLOO_DATABASE → Database name
+* - HAVE_SQL_HOST / SQLOO_HOST → Host (default: 'localhost')
+* - HAVE_SQL_USER / SQLOO_USER → Username
+* - HAVE_SQL_PASSWORD / SQLOO_PASSWORD → Password
+* - HAVE_SQL_PORT / SQLOO_PORT → Port (default: 5432)
+*
+* @param options - PostgreSQL connection options
+* @returns Database interface for PostgreSQL
+*/
+async function getDatabase$1(options = {}) {
+	const envUrl = process.env.HAVE_SQL_URL || process.env.SQLOO_URL || null;
+	const envDatabase = process.env.HAVE_SQL_DATABASE || process.env.SQLOO_DATABASE || null;
+	const envHost = process.env.HAVE_SQL_HOST || process.env.SQLOO_HOST || "localhost";
+	const envUser = process.env.HAVE_SQL_USER || process.env.SQLOO_USER || "";
+	const envPortRaw = process.env.HAVE_SQL_PORT || process.env.SQLOO_PORT;
+	const envPort = envPortRaw ? Number(envPortRaw) || 5432 : 5432;
+	const derivedHost = options.host || envHost;
+	const derivedPort = options.port || envPort;
+	const derivedDatabase = options.database || envDatabase;
+	const derivedUser = options.user || envUser;
+	const cacheKey = options.dbid || options.url || (derivedDatabase ? `pg:${derivedUser ? `${derivedUser}@` : ""}${derivedHost}:${derivedPort}/${derivedDatabase}` : envUrl || null);
+	if (cacheKey) {
+		const cached = connectionCache.get(cacheKey);
+		if (cached) return cached;
+		const pending = pendingConnections.get(cacheKey);
+		if (pending) return pending;
+	}
+	const connectionPromise = createDatabase(options, cacheKey);
+	if (cacheKey) {
+		pendingConnections.set(cacheKey, connectionPromise);
+		connectionPromise.finally(() => {
+			if (cacheKey) pendingConnections.delete(cacheKey);
+		});
+	}
+	return connectionPromise;
+}
+/**
+* Internal: creates the actual database connection and caches it.
+*/
+async function createDatabase(options, cacheKey) {
+	const config = loadEnvConfig(options, {
+		packageName: "sql",
+		schema: {
+			url: "string",
+			database: "string",
+			host: "string",
+			port: "number",
+			user: "string",
+			password: "string"
+		}
+	});
+	if (!config.url && !config.host && !config.database && !config.user) {
+		const legacyConfig = loadEnvConfig({}, {
+			prefix: "SQLOO",
+			schema: {
+				url: "string",
+				database: "string",
+				host: "string",
+				port: "number",
+				user: "string",
+				password: "string"
+			}
+		});
+		for (const [key, value] of Object.entries(legacyConfig)) if (config[key] === void 0 && value !== void 0) config[key] = value;
+	}
+	const { database, host = "localhost", user, password, port = 5432 } = config;
+	const url = config.url || `postgresql://${user}${password ? `:${password}` : ""}@${host}:${port}/${database || "postgres"}`;
+	const poolMax = options.max ?? 20;
+	const pool = new Pool(config.url ? {
+		connectionString: config.url,
+		max: poolMax
+	} : {
+		host,
+		user,
+		password,
+		port,
+		database,
+		max: poolMax
+	});
+	const originalEnd = pool.end.bind(pool);
+	const evictFromCache = () => {
+		for (const [key, cached] of connectionCache.entries()) if (cached.client === pool) connectionCache.delete(key);
+	};
+	pool.end = (callback) => {
+		evictFromCache();
+		if (callback) return originalEnd(callback);
+		return originalEnd();
+	};
+	const client = pool;
+	/**
+	* Serializes a value for database storage
+	* Converts objects and arrays to JSON strings
+	* Converts Dates to ISO strings
+	* Passes through primitives unchanged
+	*/
+	const serializeValue = (value) => {
+		if (value === null || value === void 0) return value;
+		if (value instanceof Date) return value.toISOString();
+		if (typeof value === "object") return JSON.stringify(value);
+		return value;
+	};
+	/**
+	* Serializes all values in an object for database storage
+	*/
+	const serializeRecord = (record) => {
+		const serialized = {};
+		for (const [key, value] of Object.entries(record)) {
+			if (value === void 0) continue;
+			serialized[key] = serializeValue(value);
+		}
+		return serialized;
+	};
+	let serverVersionNumPromise;
+	const nullsNotDistinctIndexCache = /* @__PURE__ */ new Map();
+	const hasNullConflictValue = (conflictColumns, data) => conflictColumns.some((col) => data[col] === null);
+	const validateUpsertConflictColumns = (table, conflictColumns, serializedData) => {
+		const missingColumns = conflictColumns.filter((col) => !(col in serializedData));
+		if (missingColumns.length > 0) throw new DatabaseError("Conflict columns missing from data", {
+			table,
+			conflictColumns,
+			missingColumns,
+			availableColumns: Object.keys(serializedData),
+			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."
+		});
+	};
+	const getServerVersionNum = async () => {
+		serverVersionNumPromise ??= client.query("SHOW server_version_num").then((result) => Number(result.rows[0]?.server_version_num) || 0);
+		return serverVersionNumPromise;
+	};
+	const hasNativeNullsNotDistinctIndex = async (table, conflictColumns) => {
+		if (await getServerVersionNum() < 15e4) return false;
+		const cacheKey = `${table}:${conflictColumns.join(",")}`;
+		let cached = nullsNotDistinctIndexCache.get(cacheKey);
+		if (!cached) {
+			cached = client.query(`
+            SELECT 1
+            FROM pg_index i
+            WHERE i.indrelid = to_regclass($1)
+              AND i.indisunique
+              AND i.indnullsnotdistinct
+              AND ARRAY(
+                SELECT a.attname::text
+                FROM unnest(i.indkey) WITH ORDINALITY AS cols(attnum, ord)
+                JOIN pg_attribute a
+                  ON a.attrelid = i.indrelid
+                 AND a.attnum = cols.attnum
+                ORDER BY cols.ord
+              ) = $2::text[]
+            LIMIT 1
+          `, [table, conflictColumns]).then((result) => result.rows.length > 0).catch(() => false);
+			nullsNotDistinctIndexCache.set(cacheKey, cached);
+		}
+		return cached;
+	};
+	const buildPostgresUpsertParts = (conflictColumns, serializedData) => {
+		const keys = Object.keys(serializedData);
+		return {
+			keys,
+			values: Object.values(serializedData),
+			placeholders: keys.map((_, i) => `$${i + 1}`).join(", "),
+			updateSet: keys.map((key, i) => `${key} = $${i + 1}`).join(", "),
+			conflict: conflictColumns.join(", ")
+		};
+	};
+	const executeStandardPostgresUpsert = async (executor, table, conflictColumns, serializedData) => {
+		const { keys, values, placeholders, updateSet, conflict } = buildPostgresUpsertParts(conflictColumns, serializedData);
+		const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders}) ON CONFLICT(${conflict}) DO UPDATE SET ${updateSet}`;
+		return {
+			operation: "upsert",
+			affected: (await executor.query(sql, values)).rowCount ?? 0
+		};
+	};
+	const executeNullAwarePostgresUpsert = async (executor, table, conflictColumns, serializedData) => {
+		const { keys, values, placeholders } = buildPostgresUpsertParts(conflictColumns, serializedData);
+		const lockKey = conflictColumns.map((col) => `${col}:${JSON.stringify(serializedData[col])}`).join("|");
+		await executor.query("SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))", [`@happyvertical/sql.upsert:${table}`, lockKey]);
+		const updateSet = keys.map((key, i) => `${key} = $${i + 1}`).join(", ");
+		const whereStart = values.length + 1;
+		const whereClause = conflictColumns.map((col, i) => `${col} IS NOT DISTINCT FROM $${whereStart + i}`).join(" AND ");
+		const whereValues = conflictColumns.map((col) => serializedData[col]);
+		const updateSql = `UPDATE ${table} SET ${updateSet} WHERE ${whereClause}`;
+		const updateResult = await executor.query(updateSql, [...values, ...whereValues]);
+		if ((updateResult.rowCount ?? 0) > 0) return {
+			operation: "upsert",
+			affected: updateResult.rowCount ?? 0
+		};
+		const insertSql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`;
+		return {
+			operation: "upsert",
+			affected: (await executor.query(insertSql, values)).rowCount ?? 0
+		};
+	};
+	const executeNullAwarePostgresUpsertInTransaction = async (table, conflictColumns, serializedData) => {
+		const txClient = await client.connect();
+		try {
+			await txClient.query("BEGIN");
+			const result = await executeNullAwarePostgresUpsert(txClient, table, conflictColumns, serializedData);
+			await txClient.query("COMMIT");
+			return result;
+		} catch (error) {
+			await txClient.query("ROLLBACK");
+			throw error;
+		} finally {
+			txClient.release();
+		}
+	};
+	const executePostgresUpsert = async (executor, table, conflictColumns, data, options, acquireTransaction) => {
+		const serializedData = serializeRecord(data);
+		validateUpsertConflictColumns(table, conflictColumns, serializedData);
+		if (options?.nullsDistinct || !hasNullConflictValue(conflictColumns, serializedData)) return executeStandardPostgresUpsert(executor, table, conflictColumns, serializedData);
+		if (await hasNativeNullsNotDistinctIndex(table, conflictColumns)) return executeStandardPostgresUpsert(executor, table, conflictColumns, serializedData);
+		if (!acquireTransaction) return executeNullAwarePostgresUpsert(executor, table, conflictColumns, serializedData);
+		return executeNullAwarePostgresUpsertInTransaction(table, conflictColumns, serializedData);
+	};
+	/**
+	* 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
+	*
+	* @example Single record insert:
+	* ```typescript
+	* await db.insert('users', {
+	*   name: 'John Doe',
+	*   email: 'john@example.com'
+	* });
+	* ```
+	*
+	* @example Multiple record insert:
+	* ```typescript
+	* await db.insert('users', [
+	*   { name: 'John', email: 'john@example.com' },
+	*   { name: 'Jane', email: 'jane@example.com' }
+	* ]);
+	* ```
+	*/
+	const insert = async (table, data) => {
+		if (Array.isArray(data)) {
+			const serializedRecords = data.map((record) => serializeRecord(record));
+			const keys = Object.keys(serializedRecords[0]);
+			const placeholders = serializedRecords.map((_, i) => `(${keys.map((_, j) => `$${i * keys.length + j + 1}`).join(", ")})`).join(", ");
+			const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES ${placeholders}`;
+			const values = serializedRecords.reduce((acc, row) => acc.concat(Object.values(row)), []);
+			return {
+				operation: "insert",
+				affected: (await client.query(query, values)).rowCount ?? 0
+			};
+		}
+		const serializedData = serializeRecord(data);
+		const keys = Object.keys(serializedData);
+		const values = Object.values(serializedData);
+		const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
+		const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`;
+		return {
+			operation: "insert",
+			affected: (await client.query(query, values)).rowCount ?? 0
+		};
+	};
+	/**
+	* Retrieves a single record matching the where criteria
+	*
+	* @param table - Table name
+	* @param where - Criteria to match records
+	* @returns Promise resolving to query result
+	*/
+	const get = async (table, where) => {
+		const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+		if (!whereClause) throw new DatabaseError("GET requires at least one WHERE condition to prevent returning an arbitrary record", { table });
+		const query = `SELECT * FROM ${table} ${whereClause}`;
+		try {
+			return (await client.query(query, values)).rows[0] || null;
+		} catch (e) {
+			throw new DatabaseError("Failed to retrieve record from table", {
+				table,
+				sql: query,
+				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 records
+	*/
+	const list = async (table, where) => {
+		const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+		const query = `SELECT * FROM ${table} ${whereClause}`;
+		try {
+			return (await client.query(query, values)).rows;
+		} catch (e) {
+			throw new DatabaseError("Failed to list records from table", {
+				table,
+				sql: query,
+				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
+	*/
+	const update = async (table, where, data) => {
+		const serializedData = serializeRecord(data);
+		const keys = Object.keys(serializedData);
+		const values = Object.values(serializedData);
+		const setClause = keys.map((key, i) => `${key} = $${i + 1}`).join(", ");
+		const { sql: whereClause, values: whereValues } = buildWhere(where, values.length + 1, "postgres");
+		if (!whereClause) throw new DatabaseError("UPDATE requires at least one WHERE condition to prevent accidental update of all records", { table });
+		const sql = `UPDATE ${table} SET ${setClause} ${whereClause}`;
+		try {
+			return {
+				operation: "update",
+				affected: (await client.query(sql, [...values, ...whereValues])).rowCount ?? 0
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to update records in table", {
+				table,
+				sql,
+				values: [...values, ...whereValues],
+				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) => {
+		try {
+			return await executePostgresUpsert(client, table, conflictColumns, data, options, true);
+		} catch (e) {
+			if (e instanceof DatabaseError && e.message === "Conflict columns missing from data") throw e;
+			throw new DatabaseError("Failed to upsert record into table", {
+				table,
+				values: data,
+				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
+	* @returns Promise resolving to the query result or insert result
+	*/
+	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$1(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, "postgres");
+		try {
+			return {
+				operation: "delete",
+				affected: (await client.query(`DELETE FROM ${table} ${whereClause}`, values)).rowCount ?? 0
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to delete records from table", {
+				table,
+				where,
+				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$1(table);
+		try {
+			if (!where || Object.keys(where).length === 0) {
+				const result = await client.query(`SELECT COUNT(*) as count FROM ${table}`);
+				return Number(result.rows[0]?.count) || 0;
+			}
+			const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+			const result = await client.query(`SELECT COUNT(*) as count FROM ${table} ${whereClause}`, values);
+			return Number(result.rows[0]?.count) || 0;
+		} catch (e) {
+			throw new DatabaseError("Failed to count records in table", {
+				table,
+				where,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Creates a table-specific interface for simplified table operations
+	*
+	* @param tableName - Table name
+	* @returns TableMethods interface for the specified table
+	*/
+	const table = (tableName) => {
+		return {
+			insert: (data) => insert(tableName, data),
+			get: (data) => get(tableName, data),
+			list: (data) => list(tableName, data)
+		};
+	};
+	/**
+	* 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 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)
+	*/
+	const pluck = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			const firstRow = (await client.query(sql, values)).rows[0];
+			if (!firstRow) return null;
+			return Object.values(firstRow)[0];
+		} catch (e) {
+			throw new DatabaseError("Failed to execute pluck 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
+	*/
+	const single = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			return (await client.query(sql, values)).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 multiple rows
+	*
+	* @param strings - Template strings
+	* @param vars - Variables to interpolate into the query
+	* @returns Promise resolving to array of result records
+	*/
+	const many = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			return (await client.query(sql, values)).rows;
+		} catch (e) {
+			throw new DatabaseError("Failed to execute many 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
+	*/
+	const execute = async (strings, ...vars) => {
+		const { sql, values } = parseTemplate(strings, ...vars);
+		try {
+			await client.query(sql, values);
+		} catch (e) {
+			throw new DatabaseError("Failed to execute query", {
+				sql,
+				values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Executes a raw SQL query with parameterized values
+	*
+	* Uses PostgreSQL-native placeholders ($1, $2, ...). Legacy ? placeholders
+	* are converted only when the placeholder count matches the supplied values,
+	* so Postgres operators such as JSONB ? remain intact.
+	*
+	* @param sql - SQL query string
+	* @param values - Variables to use as parameters
+	* @returns Promise resolving to query result with rows and count
+	*/
+	const query = async (sql, ...values) => {
+		const query = normalizePostgresRawQuery(sql, values);
+		try {
+			const result = await client.query(query.sql, query.values);
+			return {
+				rows: result.rows,
+				rowCount: result.rowCount ?? 0
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to execute raw query", {
+				sql: query.sql,
+				values: query.values,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	/**
+	* Acquire a pinned connection from the pool for session-scoped state such as
+	* `pg_advisory_lock`. Every query on the returned handle runs on the same
+	* client until {@link SessionHandle.release} drops the connection (which
+	* frees any session locks it held). The connection is held for the handle's
+	* lifetime, so hold one session per process, not per operation.
+	*/
+	const acquireSession = async () => {
+		const sessionClient = await pool.connect();
+		let released = false;
+		let lost = false;
+		sessionClient.on("error", () => {
+			lost = true;
+		});
+		return {
+			query: async (sql, ...values) => {
+				if (released) throw new DatabaseError("Session has been released", {});
+				if (lost) throw new DatabaseError("Session connection was lost", {});
+				const normalized = normalizePostgresRawQuery(sql, values);
+				try {
+					const result = await sessionClient.query(normalized.sql, normalized.values);
+					return {
+						rows: result.rows,
+						rowCount: result.rowCount ?? 0
+					};
+				} catch (e) {
+					throw new DatabaseError("Failed to execute session query", {
+						sql: normalized.sql,
+						values: normalized.values,
+						originalError: formatDbError(e)
+					});
+				}
+			},
+			isActive: () => !released && !lost,
+			release: async () => {
+				if (released) return;
+				released = true;
+				if (!lost) {
+					try {
+						await sessionClient.query("ROLLBACK");
+					} catch {}
+					try {
+						await sessionClient.query("SELECT pg_advisory_unlock_all()");
+					} catch {}
+				}
+				sessionClient.release(true);
+			}
+		};
+	};
+	/**
+	* 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) => {
+		return (await client.query(`SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1 AND table_schema = 'public')`, [tableName])).rows[0].exists;
+	};
+	/**
+	* Synchronizes database schema with provided SQL DDL
+	* Creates tables if they don't exist and adds missing columns
+	* Also executes CREATE INDEX statements
+	*
+	* @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 commands = schema.trim().split(";").filter((command) => command.trim() !== "");
+		const createIndexRegex = /CREATE (UNIQUE )?INDEX (IF NOT EXISTS )?"?(\w+)"? ON "?(\w+)"?\s*\(([^)]+)\)/i;
+		const indexNames = [];
+		for (const command of commands) {
+			const indexMatch = command.trim().match(createIndexRegex);
+			if (indexMatch) indexNames.push(indexMatch[3]);
+		}
+		const existingIndexes = /* @__PURE__ */ new Set();
+		if (indexNames.length > 0) {
+			const result = await client.query(`SELECT indexname FROM pg_indexes
+         WHERE schemaname = 'public' AND indexname = ANY($1::text[])`, [indexNames]);
+			for (const row of result.rows) existingIndexes.add(row.indexname);
+		}
+		for (const command of commands) {
+			const trimmedCommand = command.trim();
+			const tableMatch = trimmedCommand.match(/CREATE TABLE (IF NOT EXISTS )?"?(\w+)"? \(([\s\S]+)\)/i);
+			if (tableMatch) {
+				const tableName = tableMatch[2];
+				const columns = tableMatch[3].trim().split(",\n");
+				if (!await tableExists(tableName)) await client.query(trimmedCommand);
+				else for (const column of columns) {
+					const columnDef = column.trim();
+					const columnMatch = columnDef.match(/"?(\w+)"?\s+(\w+[^,]*)/);
+					if (columnMatch) {
+						const columnName = columnMatch[1];
+						if (columnName.toUpperCase() === "PRIMARY" || columnName.toUpperCase() === "FOREIGN" || columnName.toUpperCase() === "UNIQUE" || columnName.toUpperCase() === "CHECK" || columnName.toUpperCase() === "CONSTRAINT") continue;
+						try {
+							if (!(await client.query(`SELECT EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = $1
+                    AND column_name = $2
+                    AND table_schema = 'public'
+                  )`, [tableName, columnName])).rows[0].exists) {
+								const alterCommand = `ALTER TABLE "${tableName}" ADD COLUMN ${columnDef}`;
+								await client.query(alterCommand);
+							}
+						} catch (error) {
+							console.error(`Error adding column ${columnName} to ${tableName}:`, error);
+						}
+					}
+				}
+				continue;
+			}
+			const indexMatch = trimmedCommand.match(createIndexRegex);
+			if (indexMatch) {
+				const indexName = indexMatch[3];
+				const indexTableName = indexMatch[4];
+				if (!existingIndexes.has(indexName)) try {
+					await client.query(trimmedCommand);
+					existingIndexes.add(indexName);
+				} catch (error) {
+					console.warn(`Warning: Failed to create index ${indexName} on ${indexTableName}:`, error instanceof Error ? error.message : String(error));
+				}
+				continue;
+			}
+			if (trimmedCommand.toUpperCase().startsWith("CREATE ") && !trimmedCommand.toUpperCase().includes("CREATE TABLE")) try {
+				await client.query(trimmedCommand);
+			} catch (error) {
+				console.warn(`Warning: DDL statement may have failed:`, error instanceof Error ? error.message : String(error));
+			}
+		}
+	};
+	/**
+	* 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) => {
+		const txClient = await client.connect();
+		try {
+			await txClient.query("BEGIN");
+			const txDb = {
+				url,
+				client: txClient,
+				insert: async (table, data) => {
+					if (Array.isArray(data)) {
+						const keys = Object.keys(data[0]);
+						const placeholders = data.map((_, i) => `(${keys.map((_, j) => `$${i * keys.length + j + 1}`).join(", ")})`).join(", ");
+						const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES ${placeholders}`;
+						const values = data.reduce((acc, row) => acc.concat(Object.values(row)), []);
+						return {
+							operation: "insert",
+							affected: (await txClient.query(query, values)).rowCount ?? 0
+						};
+					}
+					const keys = Object.keys(data);
+					const values = Object.values(data);
+					const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
+					const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`;
+					return {
+						operation: "insert",
+						affected: (await txClient.query(query, values)).rowCount ?? 0
+					};
+				},
+				get: async (table, where) => {
+					const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+					if (!whereClause) throw new DatabaseError("GET requires at least one WHERE condition to prevent returning an arbitrary record", { table });
+					const query = `SELECT * FROM ${table} ${whereClause}`;
+					return (await txClient.query(query, values)).rows[0] || null;
+				},
+				list: async (table, where) => {
+					const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+					const query = `SELECT * FROM ${table} ${whereClause}`;
+					return (await txClient.query(query, values)).rows;
+				},
+				update: async (table, where, data) => {
+					const keys = Object.keys(data);
+					const values = Object.values(data);
+					const setClause = keys.map((key, i) => `${key} = $${i + 1}`).join(", ");
+					const { sql: whereClause, values: whereValues } = buildWhere(where, values.length + 1, "postgres");
+					if (!whereClause) throw new DatabaseError("UPDATE requires at least one WHERE condition to prevent accidental update of all records", { table });
+					const sql = `UPDATE ${table} SET ${setClause} ${whereClause}`;
+					return {
+						operation: "update",
+						affected: (await txClient.query(sql, [...values, ...whereValues])).rowCount ?? 0
+					};
+				},
+				upsert: async (table, conflictColumns, data, options) => executePostgresUpsert(txClient, table, conflictColumns, data, options, false),
+				getOrInsert: async (table, where, data) => {
+					const result = await txDb.get(table, where);
+					if (result) return result;
+					await txDb.insert(table, data);
+					const inserted = await txDb.get(table, where);
+					if (!inserted) throw new DatabaseError("Failed to insert and retrieve record", {
+						table,
+						where,
+						data
+					});
+					return inserted;
+				},
+				delete: async (table, where) => {
+					validateTableName$1(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, "postgres");
+					return {
+						operation: "delete",
+						affected: (await txClient.query(`DELETE FROM ${table} ${whereClause}`, values)).rowCount ?? 0
+					};
+				},
+				count: async (table, where) => {
+					validateTableName$1(table);
+					if (!where || Object.keys(where).length === 0) {
+						const result = await txClient.query(`SELECT COUNT(*) as count FROM ${table}`);
+						return Number(result.rows[0]?.count) || 0;
+					}
+					const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+					const result = await txClient.query(`SELECT COUNT(*) as count FROM ${table} ${whereClause}`, values);
+					return Number(result.rows[0]?.count) || 0;
+				},
+				table: (tableName) => ({
+					insert: (data) => txDb.insert(tableName, data),
+					get: (data) => txDb.get(tableName, data),
+					list: (data) => txDb.list(tableName, data)
+				}),
+				many: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					return (await txClient.query(sql, values)).rows;
+				},
+				single: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					return (await txClient.query(sql, values)).rows[0] || null;
+				},
+				pluck: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					const firstRow = (await txClient.query(sql, values)).rows[0];
+					if (!firstRow) return null;
+					return Object.values(firstRow)[0];
+				},
+				execute: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					await txClient.query(sql, values);
+				},
+				query: async (sql, ...values) => {
+					const query = normalizePostgresRawQuery(sql, values);
+					const result = await txClient.query(query.sql, query.values);
+					return {
+						rows: result.rows,
+						rowCount: result.rowCount ?? 0
+					};
+				},
+				oo: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					return (await txClient.query(sql, values)).rows;
+				},
+				oO: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					return (await txClient.query(sql, values)).rows[0] || null;
+				},
+				ox: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					const firstRow = (await txClient.query(sql, values)).rows[0];
+					if (!firstRow) return null;
+					return Object.values(firstRow)[0];
+				},
+				xx: async (strings, ...vars) => {
+					const { sql, values } = parseTemplate(strings, ...vars);
+					await txClient.query(sql, values);
+				},
+				tableExists,
+				syncSchema,
+				transaction
+			};
+			const result = await callback(txDb);
+			await txClient.query("COMMIT");
+			return result;
+		} catch (error) {
+			await txClient.query("ROLLBACK");
+			throw error;
+		} finally {
+			txClient.release();
+		}
+	};
+	/**
+	* 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 () => {
+		const txClient = await client.connect();
+		await txClient.query("BEGIN");
+		let active = true;
+		const commit = async () => {
+			if (!active) throw new DatabaseError("Transaction already ended", {});
+			await txClient.query("COMMIT");
+			active = false;
+			txClient.release();
+		};
+		const rollback = async () => {
+			if (!active) throw new DatabaseError("Transaction already ended", {});
+			await txClient.query("ROLLBACK");
+			active = false;
+			txClient.release();
+		};
+		const isActive = () => active;
+		const txHandle = {
+			url,
+			client: txClient,
+			insert: async (table, data) => {
+				if (Array.isArray(data)) {
+					const keys = Object.keys(data[0]);
+					const placeholders = data.map((_, i) => `(${keys.map((_, j) => `$${i * keys.length + j + 1}`).join(", ")})`).join(", ");
+					const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES ${placeholders}`;
+					const values = data.reduce((acc, row) => acc.concat(Object.values(row)), []);
+					return {
+						operation: "insert",
+						affected: (await txClient.query(query, values)).rowCount ?? 0
+					};
+				}
+				const keys = Object.keys(data);
+				const values = Object.values(data);
+				const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
+				const query = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`;
+				return {
+					operation: "insert",
+					affected: (await txClient.query(query, values)).rowCount ?? 0
+				};
+			},
+			get: async (table, where) => {
+				const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+				if (!whereClause) throw new DatabaseError("GET requires at least one WHERE condition to prevent returning an arbitrary record", { table });
+				const query = `SELECT * FROM ${table} ${whereClause}`;
+				return (await txClient.query(query, values)).rows[0] || null;
+			},
+			list: async (table, where) => {
+				const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+				const query = `SELECT * FROM ${table} ${whereClause}`;
+				return (await txClient.query(query, values)).rows;
+			},
+			update: async (table, where, data) => {
+				const keys = Object.keys(data);
+				const values = Object.values(data);
+				const setClause = keys.map((key, i) => `${key} = $${i + 1}`).join(", ");
+				const { sql: whereClause, values: whereValues } = buildWhere(where, values.length + 1, "postgres");
+				if (!whereClause) throw new DatabaseError("UPDATE requires at least one WHERE condition to prevent accidental update of all records", { table });
+				const sql = `UPDATE ${table} SET ${setClause} ${whereClause}`;
+				return {
+					operation: "update",
+					affected: (await txClient.query(sql, [...values, ...whereValues])).rowCount ?? 0
+				};
+			},
+			upsert: async (table, conflictColumns, data, options) => executePostgresUpsert(txClient, table, conflictColumns, data, options, false),
+			getOrInsert: async (table, where, data) => {
+				const result = await txHandle.get(table, where);
+				if (result) return result;
+				await txHandle.insert(table, data);
+				const inserted = await txHandle.get(table, where);
+				if (!inserted) throw new DatabaseError("Failed to insert and retrieve record", {
+					table,
+					where,
+					data
+				});
+				return inserted;
+			},
+			delete: async (table, where) => {
+				validateTableName$1(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, "postgres");
+				return {
+					operation: "delete",
+					affected: (await txClient.query(`DELETE FROM ${table} ${whereClause}`, values)).rowCount ?? 0
+				};
+			},
+			count: async (table, where) => {
+				validateTableName$1(table);
+				if (!where || Object.keys(where).length === 0) {
+					const result = await txClient.query(`SELECT COUNT(*) as count FROM ${table}`);
+					return Number(result.rows[0]?.count) || 0;
+				}
+				const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
+				const result = await txClient.query(`SELECT COUNT(*) as count FROM ${table} ${whereClause}`, values);
+				return Number(result.rows[0]?.count) || 0;
+			},
+			table: (tableName) => ({
+				insert: (data) => txHandle.insert(tableName, data),
+				get: (data) => txHandle.get(tableName, data),
+				list: (data) => txHandle.list(tableName, data)
+			}),
+			many: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				return (await txClient.query(sql, values)).rows;
+			},
+			single: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				return (await txClient.query(sql, values)).rows[0] || null;
+			},
+			pluck: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				const firstRow = (await txClient.query(sql, values)).rows[0];
+				if (!firstRow) return null;
+				return Object.values(firstRow)[0];
+			},
+			execute: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				await txClient.query(sql, values);
+			},
+			query: async (sql, ...values) => {
+				const query = normalizePostgresRawQuery(sql, values);
+				const result = await txClient.query(query.sql, query.values);
+				return {
+					rows: result.rows,
+					rowCount: result.rowCount ?? 0
+				};
+			},
+			oo: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				return (await txClient.query(sql, values)).rows;
+			},
+			oO: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				return (await txClient.query(sql, values)).rows[0] || null;
+			},
+			ox: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				const firstRow = (await txClient.query(sql, values)).rows[0];
+				if (!firstRow) return null;
+				return Object.values(firstRow)[0];
+			},
+			xx: async (strings, ...vars) => {
+				const { sql, values } = parseTemplate(strings, ...vars);
+				await txClient.query(sql, values);
+			},
+			tableExists,
+			syncSchema,
+			transaction,
+			commit,
+			rollback,
+			isActive
+		};
+		return txHandle;
+	};
+	const oo = many;
+	const oO = single;
+	const ox = pluck;
+	const xx = execute;
+	/**
+	* 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,
+			insert,
+			update,
+			upsert,
+			get,
+			getOrInsert,
+			delete: deleteRecords,
+			count,
+			list,
+			table,
+			many,
+			single,
+			pluck,
+			execute,
+			query,
+			oo,
+			oO,
+			ox,
+			xx,
+			tableExists,
+			syncSchema,
+			transaction
+		};
+		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$1(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}
+          AND table_schema = 'public'
+        ORDER BY ordinal_position
+      `;
+			const pkRows = await many`
+        SELECT kcu.column_name
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name
+          AND tc.table_schema = kcu.table_schema
+        WHERE tc.table_name = ${table}
+          AND tc.table_schema = 'public'
+          AND tc.constraint_type = 'PRIMARY KEY'
+      `;
+			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
+          indexname,
+          indexdef
+        FROM pg_indexes
+        WHERE tablename = ${table}
+          AND schemaname = 'public'
+          AND indexname NOT LIKE '%_pkey'
+      `;
+			const indexes = [];
+			for (const row of indexRows) {
+				const indexName = row.indexname;
+				const indexDef = row.indexdef;
+				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
+          kcu.column_name,
+          ccu.table_name AS foreign_table_name,
+          ccu.column_name AS foreign_column_name,
+          rc.delete_rule,
+          rc.update_rule
+        FROM information_schema.table_constraints AS tc
+        JOIN information_schema.key_column_usage AS kcu
+          ON tc.constraint_name = kcu.constraint_name
+          AND tc.table_schema = kcu.table_schema
+        JOIN information_schema.constraint_column_usage AS ccu
+          ON ccu.constraint_name = tc.constraint_name
+          AND ccu.table_schema = tc.table_schema
+        JOIN information_schema.referential_constraints AS rc
+          ON rc.constraint_name = tc.constraint_name
+          AND rc.constraint_schema = tc.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_name = ${table}
+          AND tc.table_schema = 'public'
+      `;
+			const foreignKeys = [];
+			for (const fkRow of fkRows) foreignKeys.push({
+				column: fkRow.column_name,
+				referencesTable: fkRow.foreign_table_name,
+				referencesColumn: fkRow.foreign_column_name,
+				onDelete: fkRow.delete_rule,
+				onUpdate: fkRow.update_rule
+			});
+			return {
+				tableName: table,
+				columns,
+				indexes,
+				foreignKeys
+			};
+		} catch (e) {
+			throw new DatabaseError("Failed to retrieve table schema", {
+				table,
+				originalError: formatDbError(e)
+			});
+		}
+	};
+	const db = {
+		url,
+		client,
+		insert,
+		update,
+		upsert,
+		get,
+		getOrInsert,
+		delete: deleteRecords,
+		count,
+		list,
+		table,
+		many,
+		single,
+		pluck,
+		execute,
+		query,
+		oo,
+		oO,
+		ox,
+		xx,
+		tableExists,
+		syncSchema,
+		initializeSchemas,
+		transaction,
+		beginTransaction,
+		acquireSession,
+		getTableSchema,
+		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$1(table);
+				validateColumnName$1(column.name);
+				try {
+					const sql = generateAddColumnStatement(table, column, "postgres");
+					await client.query(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$1(table);
+				validateIndexName(index.name);
+				for (const col of index.columns) validateColumnName$1(col);
+				try {
+					const sql = generateCreateIndexStatement(table, index);
+					await client.query(sql);
+				} catch (e) {
+					throw new DatabaseError("Failed to create index on table", {
+						table,
+						index: index.name,
+						originalError: formatDbError(e)
+					});
+				}
+			}
+		},
+		vector: createVectorCapabilities(pool)
+	};
+	const finalCacheKey = cacheKey || url;
+	connectionCache.set(finalCacheKey, db);
+	return db;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Checks if the provided value is a database instance rather than configuration options
+*
+* @param value - Value to check
+* @returns True if the value appears to be a DatabaseInterface instance
+*/
+function isDatabaseInstance(value) {
+	return value && typeof value === "object" && typeof value.client !== "undefined" && typeof value.insert === "function" && typeof value.get === "function" && typeof value.query === "function";
+}
+/**
+* Creates a database connection based on the provided options, or returns an existing database instance
+*
+* Loads configuration from environment variables using the HAVE_SQL_* pattern:
+* - HAVE_SQL_TYPE → type ('sqlite' | 'postgres' | 'duckdb' | 'json')
+* - HAVE_SQL_URL → url (connection string)
+* - HAVE_SQL_HOST → host (database server hostname)
+* - HAVE_SQL_PORT → port (database server port number)
+* - HAVE_SQL_DATABASE → database (database name)
+* - HAVE_SQL_USER → user (authentication username)
+* - HAVE_SQL_PASSWORD → password (authentication password)
+*
+* User-provided options always take precedence over environment variables.
+*
+* ## Lazy schemas
+*
+* The `schemas` option accepts either an eagerly-built record or a lazy
+* function (`() => Record<string, SchemaProvider>`).  Adapters that manage
+* tables via migrations (Postgres, SQLite) never resolve the function, so
+* there is zero cost for callers that pass schemas uniformly regardless of
+* adapter type.  Only JSON and DuckDB adapters call the function.
+*
+* ```typescript
+* // Caller doesn't need to know the adapter type:
+* await getDatabase({
+*   ...config,
+*   schemas: () => ObjectRegistry.getAllSchemas(),
+* });
+* ```
+*
+* @param options - Configuration options for the database connection or an existing database instance
+* @returns Promise resolving to a DatabaseInterface implementation
+* @throws Error if the database type is invalid
+*/
+async function getDatabase(options = {}) {
+	if (isDatabaseInstance(options)) return options;
+	Object.assign(options, loadEnvConfig(options, {
+		packageName: "sql",
+		schema: {
+			type: "string",
+			url: "string",
+			host: "string",
+			port: "number",
+			database: "string",
+			user: "string",
+			password: "string"
+		}
+	}));
+	if (!options.type && (options.url?.startsWith("file:") || options.url === ":memory:")) options.type = "sqlite";
+	if (options.type === "postgres") return (await Promise.resolve().then(() => postgres_exports)).getDatabase(options);
+	if (options.type === "sqlite") return (await import("./chunks/sqlite-YgU9LCVy.js")).getDatabase(options);
+	if (options.type === "duckdb") return (await import("./chunks/duckdb-DykBBzd6.js")).getDatabase(options);
+	if (options.type === "json") return (await Promise.resolve().then(() => json_exports)).getDatabase(options);
+	throw new Error("Invalid database type");
+}
+/**
+* Synchronizes a SQL schema definition with a database
+* Creates tables if they don't exist and adds missing columns to existing tables
+*
+* @param options - Object containing database and schema
+* @param options.db - Database interface to use
+* @param options.schema - SQL schema definition
+* @throws Error if db or schema are missing or if the database doesn't support syncSchema
+*/
+async function syncSchema(options) {
+	const { db, schema } = options;
+	if (!db || !schema) throw new Error("db and schema are required");
+	if (db.syncSchema) await db.syncSchema(schema);
+	else throw new Error("Database adapter does not support schema synchronization");
+}
+/**
+* Checks if a table exists in the database
+*
+* @param db - Database interface to use
+* @param tableName - Name of the table to check
+* @returns Promise resolving to boolean indicating if the table exists
+*/
+async function tableExists(db, tableName) {
+	return db.tableExists(tableName);
+}
+/**
+* Escapes and formats a value for use in SQL queries
+*
+* @param value - Value to escape
+* @returns String representation of the value safe for SQL use
+*/
+function escapeSqlValue(value) {
+	if (value === null) return "NULL";
+	if (value instanceof Date) return `'${value.toISOString()}'`;
+	if (typeof value === "number") return value.toString();
+	if (typeof value === "boolean") return value ? "1" : "0";
+	return `'${String(value).replace(/'/g, "''")}'`;
+}
+/**
+* Validates a column name for use in SQL queries
+*
+* @param column - Column name to validate
+* @returns The validated column name
+* @throws Error if the column name contains invalid characters
+*/
+function validateColumnName(column) {
+	if (!/^[a-zA-Z0-9_.]+$/.test(column)) throw new Error(`Invalid column name: ${column}`);
+	return column;
+}
+var src_default = {
+	getDatabase,
+	syncSchema,
+	tableExists,
+	buildWhere
+};
+/** @internal */
+var PACKAGE_VERSION_INITIALIZED = true;
+//#endregion
+export { DatabaseSchemaManager, PACKAGE_VERSION_INITIALIZED, assertCanExportDatabase, assertCanImportDatabase, bucketExpr, buildAggregate, buildWhere, checkExpectedTables, checkRelationship, checkUniqueColumn, clearConnectionCache, clearPostgresConnectionCache, convertUniqueIndexesToInlineConstraints, createPostgresDatabase, databaseNameFromUrl, src_default as default, dropPostgresDatabase, dumpPostgresDatabase, escapeSqlValue, formatDbError, getDatabase, isLocalDatabaseUrl, postgresEnvFromUrl, redactDatabaseUrl, resolveSchemas, restorePostgresDatabase, runDoctor, syncSchema, tableExists, validateColumnName };
+
+//# sourceMappingURL=index.js.map