@happyvertical/sql 0.102.2 → 0.102.4

package/dist/index.js

@@ -1,8 +1,7 @@
-import { _ as raw, a as escapeStringLiteral, b as wrapDatabaseError, c as quotePostgresColumnName, d as validateIndexName, f as validateTableName$1, g as parseConditionKey, h as formatDbError, i as escapeQuotedIdentifier, l as validateColumnName$1, m as buildWhere, n as enableCachedValidation, o as generateAddColumnStatement, p as DatabaseSchemaManager, r as validateDatabaseCacheOptions, s as generateCreateIndexStatement, t as ConnectionCache, u as validateColumnNames, v as resolveInsertColumns, y as unwrapRawKey } from "./chunks/connection-cache-Da5UcY5u.js";
+import { C as parseConditionKey, D as wrapDatabaseError, E as unwrapRawKey, S as formatDbError, T as resolveInsertColumns, _ as validateColumnNames, a as createVectorCapabilities, b as DatabaseSchemaManager, c as createTransactionLock, d as validateDatabaseCacheOptions, f as escapeQuotedIdentifier, i as createTransactionErrorTracker, l as ConnectionCache, n as createGetTableSchema, o as normalizePostgresRawQuery, p as escapeStringLiteral, r as createPostgresDialect, t as createAlterTable, u as enableCachedValidation, w as raw, x as buildWhere } from "./chunks/postgres-dialect-Bfswr4Vs.js";
 import { n as throwWithDuckDBCleanup, r as convertUniqueIndexesToInlineConstraints, t as createDuckDBResourceCloser } from "./chunks/duckdb-resources-Cci6Lo6H.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 { t as redactDatabaseUrl$1 } from "./chunks/redact-database-url-CfMDvSdy.js";
-import { i as createTransactionLock, n as resolveSchemas, t as NestedTransactionError } from "./chunks/types-CwWJ-yju.js";
 import { DatabaseError, loadEnvConfig } from "@happyvertical/utils";
 import { mkdir, readdir, stat } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
@@ -299,6 +298,48 @@ function countValueFromRow(value) {
 	return "0";
 }
 //#endregion
+//#region src/shared/types.ts
+/**
+* Error thrown when `transaction()` is called on a transaction-scoped interface
+* belonging to an adapter whose engine has no savepoints.
+*
+* DuckDB — and therefore the JSON adapter built on it — does not implement
+* `SAVEPOINT`, so there is no way to re-enter the current transaction. Adapters
+* that can re-enter (PostgreSQL, SQLite) do so under a savepoint and never
+* throw this.
+*
+* The alternative would be to open a second, independent transaction, which is
+* what these adapters used to do; on a shared connection that silently
+* destroyed the enclosing transaction's uncommitted work.
+*
+* @example Ensuring a helper works on every adapter
+* ```typescript
+* // Take the transaction as a parameter rather than opening a nested one.
+* async function recordClick(db: DatabaseInterface, id: string) {
+*   await db.update('links', { id }, { clicks: 1 });
+* }
+* await db.transaction(async (tx) => recordClick(tx, id));
+* ```
+*/
+var NestedTransactionError = class extends DatabaseError {
+	constructor(message, context) {
+		super(message, context);
+		this.name = "NestedTransactionError";
+	}
+};
+/**
+* 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,
@@ -1960,309 +2001,6 @@ async function derivePostgresConnectionCacheKey(options, effective) {
 	return `pg:hmac-sha256:v1:${Buffer.from(signature).toString("hex")}`;
 }
 /**
-* 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
-*/
-/**
-* `type` is interpolated into `USING <type>`, which cannot be parameterized and
-* is not an identifier the quoting helpers cover. `VectorIndexOptions.type`
-* constrains it at compile time only, so anything reaching this at runtime —
-* a JavaScript caller, or a `filter as VectorIndexOptions` on parsed JSON — has
-* to be checked against the values pgvector actually offers.
-*/
-var VECTOR_INDEX_TYPES = /* @__PURE__ */ new Set(["hnsw", "ivfflat"]);
-/**
-* `metric` needs the same treatment as `type`, for a less obvious reason.
-*
-* It never reaches SQL directly — `vectorOpsClass`/`vectorOperator` map it
-* through a closed switch with a safe default, so an unknown metric produces a
-* valid operator class. But it is also concatenated into the *generated index
-* name*, which is then interpolated into a quoted identifier, so a metric
-* carrying a `"` still ends that identifier. The safe-default mapping is what
-* makes this easy to miss: the part of the metric that looks dangerous is
-* handled, and the part that is actually dangerous is somewhere else.
-*/
-var VECTOR_METRICS = /* @__PURE__ */ new Set([
-	"cosine",
-	"l2",
-	"ip"
-]);
-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 });
-			validateTableName$1(table);
-			validateColumnName$1(column);
-			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) {
-			validateTableName$1(table);
-			validateColumnName$1(column);
-			const metric = options?.metric || "cosine";
-			const indexType = options?.type || "hnsw";
-			if (!VECTOR_INDEX_TYPES.has(indexType)) throw new DatabaseError("Unsupported vector index type", {
-				table,
-				column,
-				type: indexType,
-				supported: [...VECTOR_INDEX_TYPES]
-			});
-			if (!VECTOR_METRICS.has(metric)) throw new DatabaseError("Unsupported vector metric", {
-				table,
-				column,
-				metric,
-				supported: [...VECTOR_METRICS]
-			});
-			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) {
-			validateTableName$1(table);
-			validateColumnName$1(column);
-			const keys = Object.keys(where);
-			validateColumnNames(keys);
-			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) {
-			validateTableName$1(table);
-			validateColumnName$1(column);
-			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:
@@ -2329,110 +2067,6 @@ async function createDatabase(config) {
 	};
 	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 (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) return value;
-		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);
-		const columns = keys.map(quotePostgresColumnName);
-		return {
-			columns,
-			values: Object.values(serializedData),
-			placeholders: keys.map((_, i) => `$${i + 1}`).join(", "),
-			updateSet: columns.map((column, i) => `${column} = $${i + 1}`).join(", "),
-			conflict: conflictColumns.map(quotePostgresColumnName).join(", ")
-		};
-	};
-	const executeStandardPostgresUpsert = async (executor, table, conflictColumns, serializedData) => {
-		const { columns, values, placeholders, updateSet, conflict } = buildPostgresUpsertParts(conflictColumns, serializedData);
-		const sql = `INSERT INTO ${table} (${columns.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 { columns, values, placeholders, updateSet } = 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 whereStart = values.length + 1;
-		const whereClause = conflictColumns.map((col, i) => `${quotePostgresColumnName(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} (${columns.join(", ")}) VALUES (${placeholders})`;
-		return {
-			operation: "upsert",
-			affected: (await executor.query(insertSql, values)).rowCount ?? 0
-		};
-	};
-	/**
 	* Absorbs 'error' events for the clients currently checked out for a
 	* transaction, keyed by client so the listener can be removed on release.
 	*/
@@ -2508,48 +2142,8 @@ async function createDatabase(config) {
 	* implicit rollback look successful.
 	*/
 	const createTransactionExecutor = (txClient) => {
-		let firstError;
-		let firstUnconfirmedError;
-		const pending = /* @__PURE__ */ new Set();
-		const isRollbackToSavepoint = (query) => {
-			const sql = typeof query === "string" ? query : typeof query === "object" && query !== null && "text" in query && typeof query.text === "string" ? query.text : void 0;
-			if (sql === void 0) return false;
-			let statement = sql.trimStart();
-			while (statement.startsWith("--") || statement.startsWith("/*")) {
-				if (statement.startsWith("--")) {
-					const newline = statement.search(/[\r\n]/);
-					if (newline === -1) return false;
-					statement = statement.slice(newline + 1).trimStart();
-					continue;
-				}
-				const commentEnd = statement.indexOf("*/", 2);
-				if (commentEnd === -1) return false;
-				statement = statement.slice(commentEnd + 2).trimStart();
-			}
-			return /^ROLLBACK\s+TO(?:\s+SAVEPOINT)?\s+/i.test(statement);
-		};
-		const errorCode = (error) => {
-			if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") return error.code;
-		};
-		const preserveFirstError = (error) => {
-			if (errorCode(error) === "25P02" && firstError !== void 0) return firstError;
-			if (errorCode(error) === "25P02" && firstUnconfirmedError !== void 0) return firstUnconfirmedError;
-			if (error instanceof DatabaseError$1) firstError ??= error;
-			else firstUnconfirmedError ??= error;
-			return error;
-		};
-		const track = (operation, query) => {
-			const tracked = operation.then((result) => {
-				if (isRollbackToSavepoint(query)) firstError = void 0;
-				firstUnconfirmedError = void 0;
-				return result;
-			}).catch((error) => {
-				throw preserveFirstError(error);
-			});
-			pending.add(tracked);
-			tracked.finally(() => pending.delete(tracked)).catch(() => {});
-			return tracked;
-		};
+		const tracker = createTransactionErrorTracker((error) => error instanceof DatabaseError$1);
+		const { pending, preserve: preserveFirstError } = tracker;
 		return {
 			client: new Proxy(txClient, { get(target, property) {
 				if (property === "query") return (...args) => {
@@ -2584,8 +2178,7 @@ async function createDatabase(config) {
 						query.handleReadyForQuery = function(...handlerArgs) {
 							try {
 								const result = Reflect.apply(handleReadyForQuery, this, handlerArgs);
-								if (isRollbackToSavepoint(query)) firstError = void 0;
-								firstUnconfirmedError = void 0;
+								tracker.confirm(query);
 								return result;
 							} finally {
 								finish();
@@ -2607,10 +2200,7 @@ async function createDatabase(config) {
 						pending.add(completion);
 						args[callbackIndex] = (error, result) => {
 							const callbackError = error === null || error === void 0 ? error : preserveFirstError(error);
-							if (callbackError === null || callbackError === void 0) {
-								if (isRollbackToSavepoint(query)) firstError = void 0;
-								firstUnconfirmedError = void 0;
-							}
+							if (callbackError === null || callbackError === void 0) tracker.confirm(query);
 							pending.delete(completion);
 							complete();
 							callback(callbackError, result);
@@ -2624,7 +2214,7 @@ async function createDatabase(config) {
 						}
 					}
 					const result = Reflect.apply(target.query, target, args);
-					if (typeof result === "object" && result !== null && "then" in result && typeof result.then === "function") return track(Promise.resolve(result), query);
+					if (typeof result === "object" && result !== null && "then" in result && typeof result.then === "function") return tracker.track(Promise.resolve(result), query);
 					if (typeof result === "object" && result !== null && "once" in result && typeof result.once === "function") {
 						let complete;
 						const completion = new Promise((resolve) => {
@@ -2640,8 +2230,7 @@ async function createDatabase(config) {
 							finish();
 						});
 						result.once("end", () => {
-							if (isRollbackToSavepoint(query)) firstError = void 0;
-							firstUnconfirmedError = void 0;
+							tracker.confirm(query);
 							finish();
 						});
 						result.once("close", finish);
@@ -2650,15 +2239,11 @@ async function createDatabase(config) {
 				};
 				return Reflect.get(target, property, target);
 			} }),
-			executor: { query: (sql, values) => track(txClient.query(sql, values), sql) },
-			clearError: () => {
-				firstError = void 0;
-			},
-			drain: async () => {
-				while (pending.size > 0) await Promise.allSettled([...pending]);
-			},
-			getError: () => firstError,
-			getUnconfirmedError: () => firstUnconfirmedError
+			executor: { query: (sql, values) => tracker.track(txClient.query(sql, values), sql) },
+			clearError: tracker.clearError,
+			drain: tracker.drain,
+			getError: tracker.getError,
+			getUnconfirmedError: tracker.getUnconfirmedError
 		};
 	};
 	const assertCommitted = (result, transactionState) => {
@@ -2667,733 +2252,124 @@ async function createDatabase(config) {
 		if (queryError !== void 0) throw queryError;
 		throw new DatabaseError("PostgreSQL rolled back the transaction at commit", { command: result.command });
 	};
-	const executeNullAwarePostgresUpsertInTransaction = async (table, conflictColumns, serializedData) => {
+	const { serializeRecord, createClientMethods, createNestedTransaction } = createPostgresDialect({
+		client,
+		probeExecutor: () => client,
+		runInTransaction: async (work) => {
+			const txClient = await acquireTxClient();
+			try {
+				await txClient.query("BEGIN");
+				const result = await work(txClient);
+				const commitResult = await txClient.query("COMMIT");
+				assertCommitted(commitResult);
+				releaseTxClient(txClient);
+				return result;
+			} catch (error) {
+				const rollbackError = await discardTxClient(txClient);
+				if (rollbackError !== void 0 && error instanceof Error) error.cause ??= rollbackError;
+				throw error;
+			}
+		}
+	});
+	const { insert, get, list, update, upsert, getOrInsert, delete: deleteRecords, count, table, many, single, pluck, execute, query, oo, oO, ox, xx, tableExists, syncSchema } = createClientMethods(client, false, serializeRecord);
+	const getTableSchema = createGetTableSchema({
+		many,
+		tableExists
+	});
+	const alterTable = createAlterTable(client);
+	/**
+	* 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 wrapDatabaseError("Failed to execute session query", e, {
+						sql: normalized.sql,
+						values: normalized.values
+					});
+				}
+			},
+			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);
+			}
+		};
+	};
+	/**
+	* 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 acquireTxClient();
+		let nestedTransaction;
+		const transactionState = createTransactionExecutor(txClient);
 		try {
 			await txClient.query("BEGIN");
-			const result = await executeNullAwarePostgresUpsert(txClient, table, conflictColumns, serializedData);
+			let txDb;
+			nestedTransaction = createNestedTransaction(transactionState.executor, () => txDb, transactionState.clearError, new AsyncLocalStorage());
+			txDb = {
+				url,
+				client: transactionState.client,
+				...createClientMethods(transactionState.executor, true, serializeRecord, transactionState.clearError),
+				transaction: nestedTransaction
+			};
+			const result = await callback(txDb);
+			await nestedTransaction.drain();
+			await transactionState.drain();
+			const statementError = transactionState.getError();
+			if (statementError !== void 0) throw statementError;
 			const commitResult = await txClient.query("COMMIT");
-			assertCommitted(commitResult);
+			assertCommitted(commitResult, transactionState);
 			releaseTxClient(txClient);
 			return result;
 		} catch (error) {
+			await nestedTransaction?.drain();
+			await transactionState.drain();
 			const rollbackError = await discardTxClient(txClient);
 			if (rollbackError !== void 0 && error instanceof Error) error.cause ??= rollbackError;
 			throw error;
 		}
 	};
-	const executePostgresUpsert = async (executor, table, conflictColumns, serializedData, options, acquireTransaction) => {
-		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);
-	};
-	/**
-	* 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
-		};
-	};
 	/**
-	* Builds the complete set of query methods bound to one PostgreSQL client.
-	*
-	* The pool-backed interface and every transaction-scoped interface are
-	* instantiated from this one factory, so there is exactly one implementation
-	* of each method. The transaction interfaces used to be hand-maintained
-	* copies of these bodies, and both had drifted:
-	*
-	* - they called the client bare, so a failure inside a transaction threw the
-	*   raw `pg` error rather than `DatabaseError`, and `instanceof` answered
-	*   differently depending on whether the call was in a transaction. `pg`
-	*   exports its own class also named `DatabaseError`, so nothing a developer
-	*   would check by eye showed the difference (#1115);
-	* - they re-exposed `tableExists` and `syncSchema` from the enclosing scope,
-	*   which close over the *pool*. Both therefore ran on a different connection
-	*   than the transaction, so `tx.tableExists()` could not see a table created
-	*   in the same transaction and `tx.syncSchema()` committed its DDL
-	*   immediately, surviving a rollback (#1111).
+	* Begins a new transaction and returns a handle for manual control
 	*
-	* Binding a client is the only difference between the two, so it is the only
-	* thing this factory parameterizes.
+	* Unlike transaction(), this gives you explicit control over commit/rollback.
+	* Ideal for test isolation where you want to rollback after each test.
 	*
-	* @param executor - Pool or checked-out client every statement runs on
-	* @param inTransaction - Whether `executor` is already inside a transaction
-	* @param serialize - Applied to each record before `insert`/`update` builds
-	*   its SQL
-	* @param clearTransactionError - Clears a statement error after a savepoint
-	*   has successfully restored the transaction to a usable state
-	*/
-	const createClientMethods = (executor, inTransaction, serialize, clearTransactionError = () => {}) => {
-		/**
-		* 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) => {
-			validateTableName$1(table);
-			if (Array.isArray(data)) {
-				if (data.length === 0) return {
-					operation: "insert",
-					affected: 0
-				};
-				const serializedRecords = data.map((record) => serialize(record));
-				const keys = resolveInsertColumns(table, serializedRecords);
-				validateColumnNames(keys);
-				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.flatMap((row) => keys.map((key) => row[key]));
-				return {
-					operation: "insert",
-					affected: (await executor.query(query, values)).rowCount ?? 0
-				};
-			}
-			const serializedData = serialize(data);
-			const keys = Object.keys(serializedData);
-			validateColumnNames(keys);
-			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 executor.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) => {
-			validateTableName$1(table);
-			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 executor.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) => {
-			validateTableName$1(table);
-			const { sql: whereClause, values } = buildWhere(where, 1, "postgres");
-			const query = `SELECT * FROM ${table} ${whereClause}`;
-			try {
-				return (await executor.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) => {
-			validateTableName$1(table);
-			const serializedData = serialize(data);
-			const keys = Object.keys(serializedData);
-			validateColumnNames(keys);
-			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 executor.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) => {
-			validateTableName$1(table);
-			const serializedData = serializeRecord(data);
-			const conflictCols = [...conflictColumns];
-			validateColumnNames([...conflictCols, ...Object.keys(serializedData)]);
-			try {
-				return await executePostgresUpsert(executor, table, conflictCols, serializedData, options, !inTransaction);
-			} 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) => {
-			validateTableName$1(table);
-			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 executor.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 executor.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 executor.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)
-			};
-		};
-		/**
-		* 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 executor.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 executor.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 executor.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 executor.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 executor.query(query.sql, query.values);
-				return {
-					rows: result.rows,
-					rowCount: result.rowCount ?? 0
-				};
-			} catch (e) {
-				throw wrapDatabaseError("Failed to execute raw query", e, {
-					sql: query.sql,
-					values: query.values
-				});
-			}
-		};
-		/**
-		* 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 executor.query(`SELECT EXISTS (
-          SELECT 1
-          FROM information_schema.tables
-          WHERE table_name = $1
-            AND table_schema = (
-              SELECT namespace.nspname
-              FROM pg_catalog.pg_class AS relation
-              JOIN pg_catalog.pg_namespace AS namespace
-                ON namespace.oid = relation.relnamespace
-              WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident($1))
-            )
-        )`, [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
-		*/
-		/**
-		* Runs a step whose failure `syncSchema` deliberately tolerates.
-		*
-		* Logging and continuing is self-contained on the pool. Inside a
-		* transaction it is not: a failed statement puts PostgreSQL in the aborted
-		* state, and `COMMIT` on an aborted transaction *succeeds* — it reports a
-		* ROLLBACK command tag and no error. The caller is told the transaction
-		* committed while every write in it was discarded, which is the silent
-		* data loss this whole epic is about, re-entering through the schema path.
-		*
-		* A savepoint scopes the failure to the step, which is what "log it and
-		* continue" was always supposed to mean.
-		*/
-		const runTolerated = async (work) => {
-			if (!inTransaction) return work();
-			savepointSequence += 1;
-			const name = `hv_sync_${savepointSequence}`;
-			await executor.query(`SAVEPOINT ${name}`);
-			try {
-				const result = await work();
-				await executor.query(`RELEASE SAVEPOINT ${name}`);
-				return result;
-			} catch (error) {
-				await executor.query(`ROLLBACK TO SAVEPOINT ${name}`);
-				clearTransactionError();
-				await executor.query(`RELEASE SAVEPOINT ${name}`);
-				throw error;
-			}
-		};
-		const syncSchema = async (schema) => {
-			const commands = schema.trim().split(";").filter((command) => command.trim() !== "");
-			const createIndexRegex = /CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?"?(?<indexName>\w+)"?\s+ON\s+"?(?<tableName>\w+)"?\s*(?:USING\s+"?\w+"?\s*)?\([^)]+\)/i;
-			const parseCreateIndex = (command) => {
-				const { indexName, tableName } = command.match(createIndexRegex)?.groups ?? {};
-				return indexName && tableName ? {
-					indexName,
-					tableName
-				} : null;
-			};
-			const indexTargets = [];
-			for (const command of commands) {
-				const indexMatch = parseCreateIndex(command.trim());
-				if (indexMatch) indexTargets.push(indexMatch);
-			}
-			const existingIndexes = /* @__PURE__ */ new Set();
-			if (indexTargets.length > 0) {
-				const result = await executor.query(`SELECT target.table_name, target.index_name
-           FROM unnest($1::text[], $2::text[])
-             AS target(table_name, index_name)
-           JOIN pg_catalog.pg_class AS relation
-             ON relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(target.table_name))
-           JOIN pg_catalog.pg_namespace AS namespace
-             ON namespace.oid = relation.relnamespace
-           JOIN pg_catalog.pg_indexes AS existing
-             ON existing.schemaname = namespace.nspname
-             AND existing.tablename = target.table_name
-             AND existing.indexname = target.index_name`, [indexTargets.map((target) => target.tableName), indexTargets.map((target) => target.indexName)]);
-				for (const row of result.rows) existingIndexes.add(`${row.table_name}\u0000${row.index_name}`);
-			}
-			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 executor.query(trimmedCommand);
-					else for (const column of columns) {
-						const columnDef = column.trim();
-						if (/^(?:CONSTRAINT\s+(?:"(?:[^"]|"")*"|\w+)\s+)?(?:(?:PRIMARY\s+KEY|FOREIGN\s+KEY|UNIQUE|CHECK)\b|EXCLUDE(?=\s+(?:USING\b|\()))/i.test(columnDef)) continue;
-						const columnMatch = columnDef.match(/^("(?:[^"]|"")*"|\w+)\s+\w+[^,]*/);
-						if (columnMatch) {
-							const identifier = columnMatch[1];
-							const columnName = identifier.startsWith("\"") ? identifier.slice(1, -1).replace(/""/g, "\"") : identifier;
-							if (columnName.toUpperCase() === "PRIMARY" || columnName.toUpperCase() === "FOREIGN" || columnName.toUpperCase() === "UNIQUE" || columnName.toUpperCase() === "CHECK" || columnName.toUpperCase() === "CONSTRAINT") continue;
-							try {
-								await runTolerated(async () => {
-									if (!(await executor.query(`SELECT EXISTS (
-                        SELECT 1 FROM information_schema.columns
-                        WHERE table_name = $1
-                        AND column_name = $2
-                        AND table_schema = (
-                          SELECT namespace.nspname
-                          FROM pg_catalog.pg_class AS relation
-                          JOIN pg_catalog.pg_namespace AS namespace
-                            ON namespace.oid = relation.relnamespace
-                          WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident($1))
-                        )
-                      )`, [tableName, columnName])).rows[0].exists) {
-										const alterCommand = `ALTER TABLE "${tableName}" ADD COLUMN ${columnDef}`;
-										await executor.query(alterCommand);
-									}
-								});
-							} catch (error) {
-								console.error(`Error adding column ${columnName} to ${tableName}:`, error);
-							}
-						}
-					}
-					continue;
-				}
-				const indexMatch = parseCreateIndex(trimmedCommand);
-				if (indexMatch) {
-					const { indexName, tableName: indexTableName } = indexMatch;
-					const indexKey = `${indexTableName}\u0000${indexName}`;
-					if (!existingIndexes.has(indexKey)) try {
-						await runTolerated(() => executor.query(trimmedCommand));
-						existingIndexes.add(indexKey);
-					} 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 runTolerated(() => executor.query(trimmedCommand));
-				} catch (error) {
-					console.warn(`Warning: DDL statement may have failed:`, error instanceof Error ? error.message : String(error));
-				}
-			}
-		};
-		return {
-			insert,
-			get,
-			list,
-			update,
-			upsert,
-			getOrInsert,
-			delete: deleteRecords,
-			count,
-			table,
-			many,
-			single,
-			pluck,
-			execute,
-			query,
-			oo: many,
-			oO: single,
-			ox: pluck,
-			xx: execute,
-			tableExists,
-			syncSchema
-		};
-	};
-	const { insert, get, list, update, upsert, getOrInsert, delete: deleteRecords, count, table, many, single, pluck, execute, query, oo, oO, ox, xx, tableExists, syncSchema } = createClientMethods(client, false, serializeRecord);
-	/**
-	* 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 wrapDatabaseError("Failed to execute session query", e, {
-						sql: normalized.sql,
-						values: normalized.values
-					});
-				}
-			},
-			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);
-			}
-		};
-	};
-	let savepointSequence = 0;
-	/**
-	* Builds the `transaction` exposed on a transaction-scoped interface.
-	*
-	* Re-entering runs the callback under a SAVEPOINT on the *same* connection,
-	* which is what callers assume nesting already did. Re-exposing the top-level
-	* `transaction` here (the previous behaviour) checked out a second pooled
-	* connection and began an independent transaction, so the nested work could
-	* not see the enclosing transaction's uncommitted rows, and if the enclosing
-	* transaction held a lock the nested one needed, the two deadlocked in a way
-	* PostgreSQL cannot detect: the outer connection is blocked on a promise
-	* rather than on a lock, so `deadlock_timeout` never fires and the process
-	* hangs until some unrelated timeout.
-	*
-	* @param executor - Error-preserving executor bound to the enclosing client
-	* @param scopeFor - Builds the interface handed to the nested callback
-	*/
-	const createNestedTransaction = (executor, scopeFor, clearTransactionError) => {
-		const nestedScope = new AsyncLocalStorage();
-		const rootScope = { tail: Promise.resolve() };
-		const runScope = async (scope, callback) => {
-			savepointSequence += 1;
-			const name = `hv_sp_${savepointSequence}`;
-			await executor.query(`SAVEPOINT ${name}`);
-			try {
-				const result = await callback(scopeFor());
-				await scope.tail;
-				await executor.query(`RELEASE SAVEPOINT ${name}`);
-				return result;
-			} catch (error) {
-				await scope.tail;
-				try {
-					await executor.query(`ROLLBACK TO SAVEPOINT ${name}`);
-					clearTransactionError();
-					await executor.query(`RELEASE SAVEPOINT ${name}`);
-				} catch {}
-				throw error;
-			}
-		};
-		const transaction = async (callback) => {
-			const parentScope = nestedScope.getStore() ?? rootScope;
-			const scope = { tail: Promise.resolve() };
-			const current = parentScope.tail.then(() => nestedScope.run(scope, () => runScope(scope, callback)));
-			parentScope.tail = current.then(() => void 0, () => void 0);
-			return current;
-		};
-		transaction.drain = () => rootScope.tail;
-		return transaction;
-	};
-	/**
-	* 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 acquireTxClient();
-		let nestedTransaction;
-		const transactionState = createTransactionExecutor(txClient);
-		try {
-			await txClient.query("BEGIN");
-			let txDb;
-			nestedTransaction = createNestedTransaction(transactionState.executor, () => txDb, transactionState.clearError);
-			txDb = {
-				url,
-				client: transactionState.client,
-				...createClientMethods(transactionState.executor, true, serializeRecord, transactionState.clearError),
-				transaction: nestedTransaction
-			};
-			const result = await callback(txDb);
-			await nestedTransaction.drain();
-			await transactionState.drain();
-			const statementError = transactionState.getError();
-			if (statementError !== void 0) throw statementError;
-			const commitResult = await txClient.query("COMMIT");
-			assertCommitted(commitResult, transactionState);
-			releaseTxClient(txClient);
-			return result;
-		} catch (error) {
-			await nestedTransaction?.drain();
-			await transactionState.drain();
-			const rollbackError = await discardTxClient(txClient);
-			if (rollbackError !== void 0 && error instanceof Error) error.cause ??= rollbackError;
-			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
+	* @returns Promise resolving to a TransactionHandle
 	*/
 	const beginTransaction = async () => {
 		const txClient = await acquireTxClient();
@@ -3428,7 +2404,7 @@ async function createDatabase(config) {
 		const rollback = () => end("ROLLBACK");
 		const isActive = () => active;
 		let txHandle;
-		nestedTransaction = createNestedTransaction(transactionState.executor, () => txHandle, transactionState.clearError);
+		nestedTransaction = createNestedTransaction(transactionState.executor, () => txHandle, transactionState.clearError, new AsyncLocalStorage());
 		txHandle = {
 			url,
 			client: transactionState.client,
@@ -3476,137 +2452,6 @@ async function createDatabase(config) {
 		};
 		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 = (
-            SELECT namespace.nspname
-            FROM pg_catalog.pg_class AS relation
-            JOIN pg_catalog.pg_namespace AS namespace
-              ON namespace.oid = relation.relnamespace
-            WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(${table}))
-          )
-        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 = (
-            SELECT namespace.nspname
-            FROM pg_catalog.pg_class AS relation
-            JOIN pg_catalog.pg_namespace AS namespace
-              ON namespace.oid = relation.relnamespace
-            WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(${table}))
-          )
-          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 = (
-            SELECT namespace.nspname
-            FROM pg_catalog.pg_class AS relation
-            JOIN pg_catalog.pg_namespace AS namespace
-              ON namespace.oid = relation.relnamespace
-            WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(${table}))
-          )
-          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 = (
-            SELECT namespace.nspname
-            FROM pg_catalog.pg_class AS relation
-            JOIN pg_catalog.pg_namespace AS namespace
-              ON namespace.oid = relation.relnamespace
-            WHERE relation.oid = pg_catalog.to_regclass(pg_catalog.quote_ident(${table}))
-          )
-      `;
-			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)
-			});
-		}
-	};
 	db = {
 		url,
 		client,
@@ -3635,55 +2480,7 @@ async function createDatabase(config) {
 		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);
-				let sql;
-				try {
-					sql = generateAddColumnStatement(table, column, "postgres");
-					await client.query(sql);
-				} catch (e) {
-					throw wrapDatabaseError("Failed to add column to table", e, {
-						table,
-						column: column.name,
-						...sql ? { sql } : {}
-					});
-				}
-			},
-			/**
-			* 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);
-				let sql;
-				try {
-					sql = generateCreateIndexStatement(table, index);
-					await client.query(sql);
-				} catch (e) {
-					throw wrapDatabaseError("Failed to create index on table", e, {
-						table,
-						index: index.name,
-						...sql ? { sql } : {}
-					});
-				}
-			}
-		},
+		alterTable,
 		vector: createVectorCapabilities(pool),
 		close: async () => {
 			await pool.end();
@@ -3706,7 +2503,7 @@ function isDatabaseInstance(value) {
 * 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_TYPE → type ('sqlite' | 'postgres' | 'pglite' | 'duckdb' | 'json')
 * - HAVE_SQL_URL → url (connection string)
 * - HAVE_SQL_HOST → host (database server hostname)
 * - HAVE_SQL_PORT → port (database server port number)
@@ -3752,8 +2549,9 @@ async function getDatabase(options = {}) {
 	}));
 	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-Cz2NMiDs.js")).getDatabase(options);
-	if (options.type === "duckdb") return (await import("./chunks/duckdb-DfikVgov.js")).getDatabase(options);
+	if (options.type === "pglite") return (await import("./pglite.js")).getDatabase(options);
+	if (options.type === "sqlite") return (await import("./chunks/sqlite-0PMv1va2.js")).getDatabase(options);
+	if (options.type === "duckdb") return (await import("./chunks/duckdb-LMyfKZGi.js")).getDatabase(options);
 	if (options.type === "json") return (await Promise.resolve().then(() => json_exports)).getDatabase(options);
 	throw new Error("Invalid database type");
 }