@happyvertical/sql 0.102.2 → 0.102.4

package/dist/chunks/postgres-dialect-Bfswr4Vs.js

@@ -0,0 +1,2728 @@
+import { DatabaseError } from "@happyvertical/utils";
+//#region src/shared/utils.ts
+/**
+* Shared SQL utilities that work in both browser and Node.js environments
+*/
+/**
+* Formats a database error to include its useful non-secret details.
+*
+* Database drivers often include additional properties beyond just `message`:
+* - PostgreSQL: code, detail, hint, severity
+* - DuckDB: may include additional context
+* - SQLite/LibSQL: may include errno, code
+*
+* This function extracts an allowlist of driver properties and redacts
+* credential-shaped text. When parameter values are available, prefer
+* {@link wrapDatabaseError}; it also redacts values echoed by the driver.
+*
+* @param error - The caught error object
+* @returns Formatted error string with all available error details
+*/
+function formatDbError(error) {
+	return formatDbErrorWithSecrets(error, []);
+}
+var DRIVER_ERROR_FIELDS = [
+	"code",
+	"detail",
+	"hint",
+	"severity",
+	"errno"
+];
+var SENSITIVE_CONTEXT_KEY = /^(?:args?|parameters?|params?|queries|query|sql|values?)$/i;
+var CREDENTIAL_KEY_PART = /^(?:credential|credentials|passphrase|password|pwd|secret|token)$/i;
+var CREDENTIAL_KEY_QUALIFIER = /^(?:access|api|auth|client|private|refresh|service|signing)$/i;
+var DATABASE_USER_KEY = /^(?:user(?:name)?|(?:database|db|pg|postgres|postgresql)[._-]?user(?:name)?)$/i;
+var DATABASE_URL_USERINFO = /\b((?:https?|libsql|postgres|postgresql):\/\/)[^\s/@]+@/giu;
+var DATABASE_URL = /\b(?:https?|libsql|postgres|postgresql):\/\/[^\s"'`<>()]+/giu;
+var CREDENTIAL_ASSIGNMENT = /(?<![\p{L}\p{N}_-])(["']?)([\p{L}\p{N}_.-]+(?: key)?)\1(\s*[:=]\s*)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s,;}\]]+)/giu;
+var BEARER_CREDENTIAL = /\bbearer\s+[^\s,;]+/giu;
+var SQL_NUMERIC_LITERAL = /(?<![\p{L}\p{N}_$])[-+]?(?:\d(?:_?\d)*(?:\.(?:\d(?:_?\d)*)?)?|\.\d(?:_?\d)*)(?:e[-+]?\d(?:_?\d)*)?(?![\p{L}\p{N}_$])/giu;
+var POSTGRES_KEY_VALUE = /(\bKey\s*\([^\r\n)]*\)\s*=\s*\()([\s\S]*?)(\)\s*(?:already exists|is duplicated)\b)/giu;
+var POSTGRES_FAILING_ROW = /(\bFailing row contains\s*\()([\s\S]*)(\)(?:\.|$))/giu;
+var CAST_INPUT_VALUE = /(\bwith value\s+)([\s\S]*?)(\s+(?:can't|cannot)\s+be cast\b)/giu;
+function isCredentialKey(key) {
+	if (DATABASE_USER_KEY.test(key)) return true;
+	const parts = key.replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2").split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+	if (parts.length === 1 && /^(?:auth|credential|key|pass)$/i.test(parts[0])) return true;
+	if (parts.some((part) => CREDENTIAL_KEY_PART.test(part))) return true;
+	return parts.some((part, index) => /^(?:key|auth)$/i.test(part) && index > 0 && CREDENTIAL_KEY_QUALIFIER.test(parts[index - 1]));
+}
+function toDriverError(error) {
+	return error && (typeof error === "object" || typeof error === "function") ? error : {};
+}
+function redactUrl(value) {
+	try {
+		const url = new URL(value);
+		if (url.username) url.username = "[redacted]";
+		if (url.password) url.password = "[redacted]";
+		for (const key of url.searchParams.keys()) if (isCredentialKey(key)) url.searchParams.set(key, "[redacted]");
+		if (url.hash) url.hash = "[redacted]";
+		return url.toString();
+	} catch {
+		return value.replace(/\/\/[^/@\s]+@/u, "//[redacted]@");
+	}
+}
+function redactKnownValue(input, value) {
+	if (!value || !input.includes(value)) return input;
+	if (!/^[\p{L}\p{N}_-]+$/u.test(value)) return input.split(value).join("[redacted]");
+	const identifierCharacter = /^[\p{L}\p{N}_-]$/u;
+	let cursor = 0;
+	let redacted = "";
+	let match = input.indexOf(value);
+	while (match !== -1) {
+		const end = match + value.length;
+		const before = [...input.slice(Math.max(0, match - 2), match)].at(-1);
+		const afterCodePoint = input.codePointAt(end);
+		const after = afterCodePoint === void 0 ? void 0 : String.fromCodePoint(afterCodePoint);
+		const bounded = (!before || !identifierCharacter.test(before)) && (!after || !identifierCharacter.test(after));
+		redacted += input.slice(cursor, match);
+		redacted += bounded ? "[redacted]" : value;
+		cursor = end;
+		match = input.indexOf(value, cursor);
+	}
+	return redacted + input.slice(cursor);
+}
+function redactDatabaseErrorText(value, knownSecrets) {
+	let redacted = value.replace(DATABASE_URL_USERINFO, "$1[redacted]@").replace(DATABASE_URL, redactUrl).replace(CREDENTIAL_ASSIGNMENT, (assignment, quote, key, delimiter) => isCredentialKey(key) ? `${quote}${key}${quote}${delimiter}[redacted]` : assignment).replace(BEARER_CREDENTIAL, "Bearer [redacted]").replace(POSTGRES_KEY_VALUE, (_match, prefix, _value, suffix) => `${prefix}[redacted]${suffix}`).replace(POSTGRES_FAILING_ROW, (_match, prefix, _value, suffix) => `${prefix}[redacted]${suffix}`).replace(CAST_INPUT_VALUE, (_match, prefix, _value, suffix) => `${prefix}[redacted]${suffix}`);
+	for (const secret of [...new Set(knownSecrets)].sort((left, right) => right.length - left.length)) redacted = redactKnownValue(redacted, secret);
+	return redacted;
+}
+function collectSensitiveValues(value, output, seen) {
+	if (typeof value === "string") {
+		if (value) output.add(value);
+		return;
+	}
+	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+		output.add(String(value));
+		return;
+	}
+	if (!value || typeof value !== "object" || seen.has(value)) return;
+	seen.add(value);
+	try {
+		if (value instanceof Date) {
+			output.add(value.toISOString());
+			return;
+		}
+		if (ArrayBuffer.isView(value)) {
+			const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+			if (bytes.length > 0) {
+				const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+				output.add([...bytes].join(","));
+				output.add(hex);
+				output.add(`\\x${hex}`);
+				output.add(`\\x${hex.toUpperCase()}`);
+				output.add(`<Buffer ${[...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join(" ")}>`);
+				if (typeof Buffer !== "undefined") output.add(Buffer.from(bytes).toString("base64"));
+			}
+			return;
+		}
+	} catch {
+		return;
+	}
+	try {
+		const serialized = JSON.stringify(value);
+		if (serialized && serialized !== "{}" && serialized !== "[]") output.add(serialized);
+	} catch {}
+	let descriptors;
+	try {
+		descriptors = Object.getOwnPropertyDescriptors(value);
+	} catch {
+		return;
+	}
+	for (const [key, descriptor] of Object.entries(descriptors)) if (key !== "length" && "value" in descriptor) collectSensitiveValues(descriptor.value, output, seen);
+}
+function collectSqlLiterals(sql, output) {
+	if (sql) output.add(sql);
+	for (const match of sql.matchAll(/'((?:''|[^'])*)'/gu)) {
+		const literal = match[1].replaceAll("''", "'");
+		if (literal) output.add(literal);
+	}
+	for (const match of sql.matchAll(/\$\$([\s\S]*?)\$\$/gu)) if (match[1]) output.add(match[1]);
+	for (const match of sql.matchAll(/\$([A-Za-z_][A-Za-z0-9_]*)\$([\s\S]*?)\$\1\$/gu)) if (match[2]) output.add(match[2]);
+	for (const match of sql.matchAll(SQL_NUMERIC_LITERAL)) {
+		output.add(match[0]);
+		output.add(match[0].replaceAll("_", ""));
+	}
+}
+function contextSecrets(context) {
+	const output = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(context)) if (/^(?:args?|parameters?|params?|values?)$/i.test(key)) collectSensitiveValues(value, output, /* @__PURE__ */ new Set());
+	else if (/^(?:queries|query|sql)$/i.test(key) && typeof value === "string") collectSqlLiterals(value, output);
+	return [...output];
+}
+function sanitizeContextValue(value, knownSecrets, seen) {
+	if (typeof value === "string") return redactDatabaseErrorText(value, knownSecrets);
+	if (!value || typeof value !== "object") return value;
+	if (seen.has(value)) return "[circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((entry) => sanitizeContextValue(entry, knownSecrets, seen));
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, isCredentialKey(key) ? "[redacted]" : sanitizeContextValue(entry, knownSecrets, seen)]));
+}
+function sanitizeDatabaseErrorContext(context, knownSecrets) {
+	return Object.fromEntries(Object.entries(context).map(([key, value]) => [key, SENSITIVE_CONTEXT_KEY.test(key) || isCredentialKey(key) ? "[redacted]" : sanitizeContextValue(value, knownSecrets, /* @__PURE__ */ new WeakSet())]));
+}
+function formatDbErrorWithSecrets(error, knownSecrets) {
+	const dbError = toDriverError(error);
+	const parts = [];
+	if (dbError.message) parts.push(redactDatabaseErrorText(dbError.message, knownSecrets));
+	if (dbError.code) parts.push(`code=${redactDatabaseErrorText(dbError.code, knownSecrets)}`);
+	if (dbError.detail) parts.push(`detail=${redactDatabaseErrorText(dbError.detail, knownSecrets)}`);
+	if (dbError.hint) parts.push(`hint=${redactDatabaseErrorText(dbError.hint, knownSecrets)}`);
+	if (dbError.severity) parts.push(`severity=${redactDatabaseErrorText(dbError.severity, knownSecrets)}`);
+	if (dbError.errno !== void 0) parts.push(`errno=${dbError.errno}`);
+	return parts.length > 0 ? parts.join(", ") : redactDatabaseErrorText(String(error), knownSecrets);
+}
+function safeDatabaseCause(error, knownSecrets) {
+	const dbError = toDriverError(error);
+	const message = dbError.message ? redactDatabaseErrorText(dbError.message, knownSecrets) : formatDbErrorWithSecrets(error, knownSecrets);
+	const cause = new Error(message);
+	cause.name = dbError.name ? redactDatabaseErrorText(dbError.name, knownSecrets) : "DatabaseDriverError";
+	for (const field of DRIVER_ERROR_FIELDS) {
+		const value = dbError[field];
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") Object.defineProperty(cause, field, {
+			configurable: true,
+			enumerable: true,
+			value: typeof value === "string" ? redactDatabaseErrorText(value, knownSecrets) : value,
+			writable: true
+		});
+	}
+	return cause;
+}
+/**
+* Wraps an engine failure in a serializable, secret-safe DatabaseError.
+*
+* Raw SQL and parameter values are replaced in context. The native `cause` is
+* a sanitized driver-error snapshot rather than the original object so normal
+* Error inspection cannot bypass the same redaction applied to messages and
+* JSON serialization.
+*/
+function wrapDatabaseError(message, error, context = {}) {
+	const knownSecrets = contextSecrets(context);
+	const originalError = formatDbErrorWithSecrets(error, knownSecrets);
+	return new DatabaseError(`${message}: ${originalError}`, {
+		...sanitizeDatabaseErrorContext(context, knownSecrets),
+		originalError
+	}, safeDatabaseCause(error, knownSecrets));
+}
+/**
+* Resolves the column list for a multi-row INSERT and rejects batches whose
+* records disagree on it.
+*
+* A batch INSERT emits one column list for the whole statement, so it can only
+* come from the first record. That leaves two ways for a later record to be
+* written wrongly, both of them silent:
+*
+* - Its keys are the same but in a different insertion order. Callers that
+*   bound values with `Object.values(record)` bound them by position, so the
+*   values cross-assigned into each other's columns. Projecting each record
+*   through the returned column list — `keys.map((key) => record[key])` — is
+*   what makes key order irrelevant, and every caller must do it.
+* - Its key set genuinely differs. An extra key has no column to go to and a
+*   missing one has no value, so the record cannot be expressed by this
+*   statement at all. Guessing (dropping the extra, writing NULL for the
+*   missing) is what makes the failure invisible, so this throws instead.
+*
+* A key whose value is `undefined` counts as absent. Adapters that serialize
+* records first drop such keys before this point while the rest pass them
+* through, so comparing raw key lists would make the same batch throw on some
+* adapters and silently write NULL on others. Only the comparison ignores them;
+* the returned column list is untouched, so each adapter keeps its own
+* single-record handling of `undefined`.
+*
+* @param table - Table being inserted into, for error context
+* @param records - Non-empty batch, as the adapter will bind it
+* @returns Column list taken from the first record
+* @throws DatabaseError if any later record's key set differs from the first's
+*/
+function resolveInsertColumns(table, records) {
+	const definedKeys = (record) => new Set(Object.keys(record).filter((key) => record[key] !== void 0));
+	const keys = Object.keys(records[0]);
+	const expected = definedKeys(records[0]);
+	for (let index = 1; index < records.length; index++) {
+		const recordKeys = definedKeys(records[index]);
+		const missing = [...expected].filter((key) => !recordKeys.has(key));
+		const extra = [...recordKeys].filter((key) => !expected.has(key));
+		if (missing.length === 0 && extra.length === 0) continue;
+		const problems = [missing.length > 0 ? `missing ${missing.join(", ")}` : "", extra.length > 0 ? `unexpected ${extra.join(", ")}` : ""].filter(Boolean);
+		throw new DatabaseError(`Batch insert records must all have the same keys; record ${index} has ${problems.join(" and ")} relative to record 0 (${[...expected].join(", ")})`, {
+			table,
+			recordIndex: index,
+			expectedKeys: keys,
+			recordKeys: [...recordKeys],
+			missing,
+			extra,
+			hint: "A batch INSERT writes one column list for every row, taken from the first record, so record 0 defines the columns even when it is the one that looks wrong. A key whose value is undefined counts as absent. Split records with differing keys into separate insert() calls, or fill the gaps explicitly with null."
+		});
+	}
+	return keys;
+}
+/**
+* Map of valid SQL operators for use in WHERE clauses
+*/
+var VALID_OPERATORS = {
+	"=": "=",
+	">": ">",
+	">=": ">=",
+	"<": "<",
+	"<=": "<=",
+	"!=": "!=",
+	like: "LIKE",
+	contains: "CONTAINS",
+	in: "IN",
+	"not in": "NOT IN"
+};
+function isSimpleSqlIdentifier(field) {
+	return /^[a-zA-Z0-9_.]+$/.test(field);
+}
+/**
+* Marks a condition key as caller-authored SQL text.
+*
+* A fixed, non-secret sentinel rather than a random per-process token. A random
+* token has to travel inside the key, which means it reaches every place a key
+* is echoed — error messages, logs, each adapter's `DatabaseError` context — and
+* one disclosure would let a caller mint raw keys for the life of the process.
+* A registry of minted expressions avoids that but is not referentially
+* transparent: it would make `raw('revenue >')` in one query change what the
+* plain key `'revenue >'` means in every other one.
+*
+* The NUL delimiters cannot appear in an identifier or in SQL a developer would
+* write, so the marker never collides with a legitimate key.
+*/
+var RAW_KEY_PREFIX = "\0hv-sql-raw\0";
+/**
+* Marks a WHERE-clause key as SQL expression text rather than an identifier.
+*
+* {@link buildWhere} validates every condition key as a plain identifier. Wrap a
+* key in `raw()` to opt one condition out of that check:
+*
+* ```typescript
+* buildWhere({
+*   status: 'paid',                 // validated as an identifier
+*   [raw('SUM(total) >')]: 100,     // caller-authored SQL, not validated
+* });
+* ```
+*
+* Never build the argument from end-user input. `raw()` is an assertion that
+* the caller, not the request, authored this SQL.
+*
+* The returned key carries a marker, so it is a distinct string from the bare
+* expression: minting `raw('revenue >')` never changes what the plain key
+* `'revenue >'` means anywhere else.
+*
+* The marker is a fixed sentinel, not a secret. It stops an expression key being
+* used by accident — the shape of the key no longer grants raw access, a call to
+* `raw()` does — but a caller that controls a whole key string verbatim,
+* including the NUL-delimited marker, can still reproduce it. Validate at your
+* own trust boundary; do not rely on this as the only barrier against hostile
+* input.
+*
+* Enforcement is at runtime: `WhereClause` keys are plain `string`, so a
+* computed key widens and TypeScript will not reject an unmarked expression key
+* at the call site.
+*
+* A trailing operator is recognised only if it is one of `=`, `!=`, `>`, `>=`,
+* `<`, `<=`, `like`, `contains`, `in`, `not in`. Any other trailing token is
+* treated as part of the expression and `=` is appended, so
+* `raw('name ILIKE')` silently emits `name ILIKE = $1`, which the database then
+* rejects. Fold an unsupported operator into the expression instead:
+* `raw('LOWER(name) like')`.
+*
+* @param expression - SQL field or expression text, optionally ending in a
+*   supported operator (for example `SUM(total) >`)
+* @returns A branded key for use in a {@link WhereClause}
+* @throws If the expression is empty
+*/
+function raw(expression) {
+	const trimmed = unwrapRawKey(expression).key.trim();
+	if (!trimmed) throw new Error("raw() requires a non-empty SQL expression");
+	return `${RAW_KEY_PREFIX}${trimmed}`;
+}
+/**
+* Splits the raw marker off a condition key.
+* @internal
+*/
+function unwrapRawKey(fullKey) {
+	return fullKey.startsWith(RAW_KEY_PREFIX) ? {
+		key: fullKey.slice(12),
+		isRaw: true
+	} : {
+		key: fullKey,
+		isRaw: false
+	};
+}
+function parseConditionKey(fullKey) {
+	const trimmed = fullKey.trim();
+	const lower = trimmed.toLowerCase();
+	for (const operator of [
+		"not in",
+		"contains",
+		"like",
+		"in",
+		"!=",
+		">=",
+		"<=",
+		">",
+		"<",
+		"="
+	]) if (lower.endsWith(` ${operator}`)) return {
+		field: trimmed.slice(0, -(operator.length + 1)).trim(),
+		operator
+	};
+	return {
+		field: trimmed,
+		operator: "="
+	};
+}
+/**
+* Builds a single condition for a WHERE clause
+* @internal
+*/
+var buildCondition = (fullKey, value, currIndex, adapterType) => {
+	const { key, isRaw } = unwrapRawKey(fullKey);
+	const { field, operator } = parseConditionKey(key);
+	if (!isRaw && !isSimpleSqlIdentifier(field)) throw new Error(`Invalid SQL identifier: ${field}. Condition keys must be plain identifiers; wrap developer-authored SQL expressions in raw().`);
+	const sqlOperator = VALID_OPERATORS[operator] || "=";
+	const values = [];
+	let sql;
+	if (sqlOperator === "CONTAINS") {
+		if (!adapterType) throw new Error("CONTAINS requires an adapter type so buildWhere can preserve case-sensitive semantics");
+		if (typeof value !== "string") throw new Error("CONTAINS requires a string value");
+		const placeholder = `$${currIndex.value++}`;
+		sql = `${adapterType === "sqlite" ? "instr" : "strpos"}(${field}, ${placeholder}) > 0`;
+		values.push(value);
+	} else if (value === null) sql = `${field} IS ${sqlOperator === "=" ? "NULL" : "NOT NULL"}`;
+	else if ((sqlOperator === "IN" || sqlOperator === "NOT IN") && Array.isArray(value)) {
+		if (value.length === 0) throw new Error(`${sqlOperator} requires at least one value`);
+		sql = `${field} ${sqlOperator} (${value.map(() => `$${currIndex.value++}`).join(", ")})`;
+		values.push(...value);
+	} else if (value instanceof Date) {
+		if (adapterType === "duckdb" || adapterType === "json") sql = `${field} ${sqlOperator} CAST($${currIndex.value++} AS TIMESTAMP)${sqlOperator === "LIKE" ? " ESCAPE '\\'" : ""}`;
+		else sql = `${field} ${sqlOperator} $${currIndex.value++}${sqlOperator === "LIKE" ? " ESCAPE '\\'" : ""}`;
+		values.push(value.toISOString());
+	} else {
+		sql = `${field} ${sqlOperator} $${currIndex.value++}${sqlOperator === "LIKE" ? " ESCAPE '\\'" : ""}`;
+		values.push(value);
+	}
+	return {
+		sql,
+		values
+	};
+};
+/**
+* Builds a SQL WHERE clause with parameterized values and flexible operators
+*
+* @param where - Conditions as object (AND-only) or 2D array (OR/AND compound)
+* @param startIndex - Starting index for parameter numbering (default: 1)
+* @param adapterType - Database adapter type. Controls Date and `contains`
+*   handling:
+*   - `'duckdb'` / `'json'`: Wraps Date values in `CAST($N AS TIMESTAMP)` to
+*     prevent DuckDB ANY-type inference issues.
+*   - `'sqlite'` / `'postgres'` / `undefined`: Passes ISO strings directly
+*     (these adapters handle ISO timestamp strings natively).
+*   - Required for `contains`, whose case-sensitive literal substring SQL is
+*     emitted with adapter-specific functions.
+*
+* Every condition key is validated as a plain SQL identifier, with or without
+* an operator suffix. To use expression text as a key, wrap it in {@link raw}:
+*
+* ```typescript
+* buildWhere({ [raw('LOWER(status) =')]: 'paid' });
+* ```
+*
+* `raw()` is the only way to reach expression text, so mapping untrusted input
+* into a condition key throws rather than emitting attacker-controlled SQL.
+*
+* @returns Object containing the SQL clause and array of values
+* @throws If a key that is not wrapped in {@link raw} is not a plain identifier
+*
+* @example Basic Usage (Object format - AND-only):
+* ```typescript
+* buildWhere({
+*   'status': 'active',           // equals operator is default
+*   'price >': 100,              // greater than
+*   'stock <=': 5,               // less than or equal
+*   'category in': ['A', 'B'],   // IN clause for arrays
+*   'name like': '%shirt%',      // LIKE pattern; backslash escapes `%` / `_`
+*   'notes contains': '100% off' // literal, case-sensitive substring
+* });
+* ```
+*
+* @example 2D Array Format (OR/AND compound logic):
+* ```typescript
+* // WHERE (status = 'active' AND price > 100) OR (status = 'pending' AND priority = 'high')
+* buildWhere([
+*   [{ status: 'active' }, { 'price >': 100 }],
+*   [{ status: 'pending' }, { priority: 'high' }]
+* ]);
+* ```
+*
+* @example NULL Handling:
+* ```typescript
+* buildWhere({
+*   'deleted_at': null,          // becomes "deleted_at IS NULL"
+*   'updated_at !=': null,       // becomes "updated_at IS NOT NULL"
+*   'status': 'active'           // regular comparison
+* });
+* ```
+*
+* @example Common Patterns:
+* ```typescript
+* // Price range
+* buildWhere({
+*   'price >=': 10,
+*   'price <': 100
+* });
+*
+* // Date filtering
+* buildWhere({
+*   'created_at >': startDate,
+*   'created_at <=': endDate,
+*   'deleted_at': null
+* });
+*
+* // Search with LIKE
+* buildWhere({
+*   'title like': '%search%',
+*   'description like': '%search%',
+*   'status': 'published'
+* });
+*
+* // Multiple values with IN
+* buildWhere({
+*   'role in': ['admin', 'editor'],
+*   'active': true,
+*   'last_login !=': null
+* });
+* ```
+*
+* The function handles:
+* - Standard comparisons (=, >, >=, <, <=, !=)
+* - NULL checks (IS NULL, IS NOT NULL)
+* - IN clauses for arrays
+* - LIKE for pattern matching with an explicit backslash escape character
+* - Case-sensitive literal substring matching with `contains`
+* - Object format: Multiple conditions combined with AND
+* - 2D array format: Inner arrays ANDed, outer array ORed
+*/
+var buildWhere = (where, startIndex = 1, adapterType) => {
+	let sql = "";
+	const values = [];
+	const currIndex = { value: startIndex };
+	if (Array.isArray(where)) {
+		if (where.length === 0) return {
+			sql: "",
+			values: []
+		};
+		const orGroups = [];
+		for (const andGroup of where) {
+			if (!Array.isArray(andGroup) || andGroup.length === 0) continue;
+			const andConditions = [];
+			for (const conditionObj of andGroup) for (const [fullKey, value] of Object.entries(conditionObj)) {
+				const result = buildCondition(fullKey, value, currIndex, adapterType);
+				andConditions.push(result.sql);
+				values.push(...result.values);
+			}
+			if (andConditions.length > 0) orGroups.push(`(${andConditions.join(" AND ")})`);
+		}
+		if (orGroups.length > 0) sql = `WHERE ${orGroups.join(" OR ")}`;
+		return {
+			sql,
+			values
+		};
+	}
+	if (where && Object.keys(where).length > 0) {
+		sql = "WHERE ";
+		for (const [fullKey, value] of Object.entries(where)) {
+			const result = buildCondition(fullKey, value, currIndex, adapterType);
+			if (sql !== "WHERE ") sql += " AND ";
+			sql += result.sql;
+			values.push(...result.values);
+		}
+	}
+	return {
+		sql,
+		values
+	};
+};
+//#endregion
+//#region src/schema-manager.ts
+/**
+* Manages schema initialization from JSON manifests with dependency resolution
+*
+* Handles topological sorting of schema dependencies, table creation,
+* index and trigger setup, and version tracking to avoid redundant re-initialization.
+*/
+var DatabaseSchemaManager = class DatabaseSchemaManager {
+	static initializationLock = /* @__PURE__ */ new Map();
+	initializedSchemas = /* @__PURE__ */ new Set();
+	schemaVersions = /* @__PURE__ */ new Map();
+	/**
+	* Initializes database schemas from a JSON manifest with dependency resolution
+	*
+	* Schemas are topologically sorted by their declared dependencies and
+	* initialized in order. Supports legacy raw-SQL schemas via the `schema` option,
+	* JSON manifests via the `manifest` option, and schema overrides for extending
+	* base schemas.
+	*
+	* @param db - Database interface to execute DDL against
+	* @param options - Schema initialization options (manifest, overrides, force, debug)
+	* @returns Result with lists of initialized/skipped schemas, errors, and execution time
+	*/
+	async initializeSchemas(db, options) {
+		const startTime = Date.now();
+		const result = {
+			initialized: [],
+			skipped: [],
+			errors: [],
+			executionTime: 0
+		};
+		try {
+			let schemas = {};
+			if (options.schema) {
+				console.log("[schema] Legacy SQL schema provided, converting to manifest format");
+				if (db.syncSchema) {
+					await db.syncSchema(options.schema);
+					result.initialized.push("legacy-sql");
+				}
+				result.executionTime = Date.now() - startTime;
+				return result;
+			}
+			if (options.manifest) schemas = { ...options.manifest.schemas };
+			if (options.overrides) schemas = {
+				...schemas,
+				...options.overrides
+			};
+			if (Object.keys(schemas).length === 0) {
+				console.warn("[schema] No schemas provided for initialization");
+				result.executionTime = Date.now() - startTime;
+				return result;
+			}
+			const dependencyGraph = this.buildDependencyGraph(schemas);
+			const initializationOrder = this.resolveDependencies(dependencyGraph);
+			if (options.debug) console.log("[schema] Initialization order:", initializationOrder);
+			for (const schemaName of initializationOrder) {
+				const schema = schemas[schemaName];
+				if (!schema) continue;
+				try {
+					await this.initializeSchema(db, schemaName, schema, {
+						force: options.force,
+						debug: options.debug
+					});
+					result.initialized.push(schemaName);
+				} catch (error) {
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					result.errors.push({
+						schema: schemaName,
+						error: errorMessage
+					});
+					if (options.debug) console.error(`[schema] Failed to initialize ${schemaName}:`, error);
+				}
+			}
+			result.executionTime = Date.now() - startTime;
+			if (options.debug) console.log("[schema] Initialization complete:", result);
+			return result;
+		} catch (error) {
+			result.executionTime = Date.now() - startTime;
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			result.errors.push({
+				schema: "dependency-resolution",
+				error: errorMessage
+			});
+			return result;
+		}
+	}
+	/**
+	* Initialize a single schema
+	*/
+	async initializeSchema(db, schemaName, schema, options) {
+		const { tableName, version } = schema;
+		const lockKey = `${schemaName}:${tableName}`;
+		if (DatabaseSchemaManager.initializationLock.has(lockKey)) {
+			await DatabaseSchemaManager.initializationLock.get(lockKey);
+			return;
+		}
+		if (!options.force && this.isSchemaUpToDate(schemaName, version)) {
+			if (options.debug) console.log(`[schema] Skipping ${schemaName} - already up to date`);
+			return;
+		}
+		const initPromise = this.performSchemaInitialization(db, schemaName, schema, options);
+		DatabaseSchemaManager.initializationLock.set(lockKey, initPromise);
+		try {
+			await initPromise;
+			this.markSchemaInitialized(schemaName, version);
+		} finally {
+			DatabaseSchemaManager.initializationLock.delete(lockKey);
+		}
+	}
+	/**
+	* Perform the actual schema initialization
+	*/
+	async performSchemaInitialization(db, schemaName, schema, options) {
+		const { tableName, columns, indexes, triggers } = schema;
+		if (options.debug) console.log(`[schema] Initializing ${schemaName} (${tableName})`);
+		if (!await db.tableExists(tableName)) {
+			await this.createTable(db, schema);
+			for (const index of indexes) await this.createIndex(db, tableName, index);
+			for (const trigger of triggers) await this.createTrigger(db, trigger);
+		} else if (options.force) {
+			await db.query(`DROP TABLE IF EXISTS ${tableName}`);
+			await this.createTable(db, schema);
+			for (const index of indexes) await this.createIndex(db, tableName, index);
+			for (const trigger of triggers) await this.createTrigger(db, trigger);
+		} else await this.updateSchemaIfNeeded(db, schema);
+	}
+	/**
+	* Create table from schema definition
+	*/
+	async createTable(db, schema) {
+		const { tableName, columns, foreignKeys } = schema;
+		const columnDefinitions = [];
+		for (const [columnName, columnDef] of Object.entries(columns)) {
+			let def = `${columnName} ${columnDef.type}`;
+			if (columnDef.primaryKey) def += " PRIMARY KEY";
+			if (columnDef.unique && !columnDef.primaryKey) def += " UNIQUE";
+			if (columnDef.notNull) def += " NOT NULL";
+			if (columnDef.defaultValue !== void 0) def += ` DEFAULT ${columnDef.defaultValue}`;
+			if (columnDef.check) def += ` CHECK (${columnDef.check})`;
+			columnDefinitions.push(def);
+		}
+		for (const fk of foreignKeys) {
+			let fkDef = `FOREIGN KEY (${fk.column}) REFERENCES ${fk.referencesTable}(${fk.referencesColumn})`;
+			if (fk.onDelete) fkDef += ` ON DELETE ${fk.onDelete}`;
+			if (fk.onUpdate) fkDef += ` ON UPDATE ${fk.onUpdate}`;
+			columnDefinitions.push(fkDef);
+		}
+		const createTableSQL = `CREATE TABLE ${tableName} (\n  ${columnDefinitions.join(",\n  ")}\n)`;
+		await db.query(createTableSQL);
+	}
+	/**
+	* Create index from definition
+	*/
+	async createIndex(db, tableName, index) {
+		const uniqueClause = index.unique ? "UNIQUE " : "";
+		const whereClause = index.where ? ` WHERE ${index.where}` : "";
+		const createIndexSQL = `CREATE ${uniqueClause}INDEX ${index.name} ON ${tableName} (${index.columns.join(", ")})${whereClause}`;
+		await db.query(createIndexSQL);
+	}
+	/**
+	* Create trigger from definition
+	*/
+	async createTrigger(db, trigger) {
+		const conditionClause = trigger.condition ? ` WHEN ${trigger.condition}` : "";
+		const createTriggerSQL = `CREATE TRIGGER ${trigger.name} ${trigger.when} ${trigger.event} ON ${trigger.table}${conditionClause} BEGIN ${trigger.body} END`;
+		await db.query(createTriggerSQL);
+	}
+	/**
+	* Update schema if changes are detected
+	*/
+	async updateSchemaIfNeeded(_db, schema) {
+		console.log(`[schema] Schema update logic not yet implemented for ${schema.tableName}`);
+	}
+	/**
+	* Build dependency graph from schemas
+	*/
+	buildDependencyGraph(schemas) {
+		const graph = /* @__PURE__ */ new Map();
+		for (const [schemaName, schema] of Object.entries(schemas)) {
+			const dependencies = schema.dependencies.filter((dep) => Object.values(schemas).some((s) => s.tableName === dep));
+			graph.set(schemaName, dependencies.map((dep) => Object.entries(schemas).find(([_, s]) => s.tableName === dep)?.[0] || dep));
+		}
+		return graph;
+	}
+	/**
+	* Resolve dependencies using topological sort
+	*/
+	resolveDependencies(graph) {
+		const resolved = [];
+		const visited = /* @__PURE__ */ new Set();
+		const visiting = /* @__PURE__ */ new Set();
+		const visit = (node) => {
+			if (visiting.has(node)) throw new Error(`Circular dependency detected involving ${node}`);
+			if (visited.has(node)) return;
+			visiting.add(node);
+			const dependencies = graph.get(node) || [];
+			for (const dep of dependencies) if (graph.has(dep)) visit(dep);
+			visiting.delete(node);
+			visited.add(node);
+			resolved.push(node);
+		};
+		for (const node of graph.keys()) if (!visited.has(node)) visit(node);
+		return resolved;
+	}
+	/**
+	* Check if schema is up to date
+	*/
+	isSchemaUpToDate(schemaName, version) {
+		return this.initializedSchemas.has(schemaName) && this.schemaVersions.get(schemaName) === version;
+	}
+	/**
+	* Mark schema as initialized
+	*/
+	markSchemaInitialized(schemaName, version) {
+		this.initializedSchemas.add(schemaName);
+		this.schemaVersions.set(schemaName, version);
+	}
+	/**
+	* Reset initialization state (for testing)
+	*/
+	reset() {
+		this.initializedSchemas.clear();
+		this.schemaVersions.clear();
+		DatabaseSchemaManager.initializationLock.clear();
+	}
+};
+//#endregion
+//#region src/shared/alter-utils.ts
+/**
+* Generates an ALTER TABLE ADD COLUMN statement
+*
+* @param table - Table name
+* @param column - Column definition with name
+* @param dialect - Database dialect
+* @returns SQL statement string
+*
+* @example
+* ```typescript
+* const sql = generateAddColumnStatement('users', {
+*   name: 'email',
+*   type: 'TEXT',
+*   unique: true,
+*   notNull: false
+* }, 'sqlite');
+* // Returns: "ALTER TABLE users ADD COLUMN email TEXT UNIQUE"
+* ```
+*/
+function generateAddColumnStatement(table, column, _dialect) {
+	const parts = [column.name, column.type];
+	if (column.primaryKey) parts.push("PRIMARY KEY");
+	if (column.notNull) parts.push("NOT NULL");
+	if (column.unique) parts.push("UNIQUE");
+	if (column.defaultValue !== void 0) {
+		const defaultClause = generateDefaultClause(column.type, column.defaultValue);
+		parts.push(`DEFAULT ${defaultClause}`);
+	}
+	if (column.check) parts.push(`CHECK (${column.check})`);
+	if (column.foreignKey) {
+		const fk = column.foreignKey;
+		const fkParts = [`REFERENCES ${fk.table}(${fk.column})`];
+		if (fk.onDelete) fkParts.push(`ON DELETE ${fk.onDelete}`);
+		if (fk.onUpdate) fkParts.push(`ON UPDATE ${fk.onUpdate}`);
+		parts.push(fkParts.join(" "));
+	}
+	return `ALTER TABLE ${table} ADD COLUMN ${parts.join(" ")}`;
+}
+/**
+* Generates a DEFAULT clause for a column definition
+*
+* Handles proper formatting and escaping of default values based on column type.
+*
+* @param columnType - SQL column type (TEXT, INTEGER, BOOLEAN, etc.)
+* @param defaultValue - Default value to format
+* @returns Formatted default value string
+*
+* @example
+* ```typescript
+* generateDefaultClause('TEXT', 'hello'); // Returns: "'hello'"
+* generateDefaultClause('INTEGER', 42);   // Returns: "42"
+* generateDefaultClause('BOOLEAN', true); // Returns: "true"
+* generateDefaultClause('TEXT', null);    // Returns: "NULL"
+* ```
+*/
+function generateDefaultClause(columnType, defaultValue) {
+	if (defaultValue === null) return "NULL";
+	const typeUpper = columnType.toUpperCase();
+	if (typeUpper.includes("TEXT") || typeUpper.includes("CHAR") || typeUpper.includes("VARCHAR") || typeUpper.includes("STRING")) {
+		if (defaultValue === "") return "''";
+		return `'${String(defaultValue).replace(/'/g, "''")}'`;
+	}
+	if (typeUpper.includes("BOOL")) return defaultValue ? "true" : "false";
+	if (typeUpper.includes("INT") || typeUpper.includes("REAL") || typeUpper.includes("FLOAT") || typeUpper.includes("DOUBLE") || typeUpper.includes("NUMERIC") || typeUpper.includes("DECIMAL")) return String(defaultValue);
+	if (typeUpper.includes("JSON")) {
+		if (typeof defaultValue === "string") return `'${defaultValue.replace(/'/g, "''")}'`;
+		return `'${JSON.stringify(defaultValue).replace(/'/g, "''")}'`;
+	}
+	if (typeUpper.includes("DATE") || typeUpper.includes("TIME") || typeUpper.includes("TIMESTAMP")) {
+		if (defaultValue instanceof Date) return `'${defaultValue.toISOString()}'`;
+		return `'${String(defaultValue).replace(/'/g, "''")}'`;
+	}
+	if (typeof defaultValue === "string") return `'${defaultValue.replace(/'/g, "''")}'`;
+	return String(defaultValue);
+}
+/**
+* Generates a CREATE INDEX statement
+*
+* @param table - Table name
+* @param index - Index definition
+* @returns SQL CREATE INDEX statement
+*
+* @example
+* ```typescript
+* const sql = generateCreateIndexStatement('users', {
+*   name: 'idx_users_email',
+*   columns: ['email'],
+*   unique: true
+* });
+* // Returns: "CREATE UNIQUE INDEX idx_users_email ON users (email)"
+* ```
+*/
+function generateCreateIndexStatement(table, index) {
+	const parts = ["CREATE"];
+	if (index.unique) parts.push("UNIQUE");
+	parts.push("INDEX");
+	parts.push(index.name);
+	parts.push(`ON ${table}`);
+	const columns = index.columns.join(", ");
+	parts.push(`(${columns})`);
+	if (index.where) parts.push(`WHERE ${index.where}`);
+	return parts.join(" ");
+}
+/**
+* Validates a table name to prevent SQL injection
+*
+* The argument must be a primitive string. `RegExp.prototype.test` coerces its
+* argument with `toString`, so an object whose `toString` returns a valid name
+* on the call the validator makes and a different one on the call the caller's
+* `${table}` interpolation makes would pass here and then reach SQL. Rejecting
+* non-strings up front closes that gap: the value validated is the value
+* interpolated, because a primitive string cannot observe how many times it is
+* read.
+*
+* @param tableName - Table name to validate
+* @throws Error if the value is not a string or contains invalid characters
+*/
+function validateTableName(tableName) {
+	if (typeof tableName !== "string" || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) throw new Error(`Invalid table name: ${tableName}. Table names must be a string that starts with a letter or underscore and contains only alphanumeric characters and underscores.`);
+}
+/**
+* Validates a column name to prevent SQL injection
+*
+* Rejects non-strings for the same reason as {@link validateTableName}: a value
+* whose `toString` differs between the validation read and the interpolation
+* read would otherwise slip a different identifier into SQL than the one
+* checked here.
+*
+* @param columnName - Column name to validate
+* @throws Error if the value is not a string or contains invalid characters
+*/
+function validateColumnName(columnName) {
+	if (typeof columnName !== "string" || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(columnName)) throw new Error(`Invalid column name: ${columnName}. Column names must be a string that starts with a letter or underscore and contains only alphanumeric characters and underscores.`);
+}
+/**
+* Validates every identifier in a column list to prevent SQL injection
+*
+* Column names reaching the CRUD methods come from `Object.keys(data)` and the
+* caller's `conflictColumns`, both of which are interpolated into SQL. The
+* accepted shape has no character that can end an identifier. Adapters may
+* render a validated name bare, or quote it under an adapter-specific contract.
+* PostgreSQL upsert uses {@link quotePostgresColumnName}, which canonicalizes
+* the name before quoting so its established unquoted case-folding semantics
+* do not change.
+*
+* @param columnNames - Column names to validate
+* @throws Error if any column name contains invalid characters
+*/
+function validateColumnNames(columnNames) {
+	for (const columnName of columnNames) validateColumnName(columnName);
+}
+/**
+* Quotes a validated column name using PostgreSQL's historic case semantics.
+*
+* PostgreSQL folds every unquoted identifier to lowercase. The CRUD API has
+* always accepted mixed-case inputs while rendering them unquoted, so quoting
+* the caller's spelling directly would silently change which physical column
+* is addressed. Validate the existing plain-identifier contract first, then
+* lowercase before quoting: `mixedCase` still addresses `mixedcase`, while a
+* reserved word such as `end` is no longer parsed as SQL syntax.
+*
+* @param columnName - Plain column name to render for PostgreSQL
+* @returns A lowercase, double-quoted PostgreSQL identifier
+* @throws Error if the column name is outside the CRUD identifier contract
+*/
+function quotePostgresColumnName(columnName) {
+	validateColumnName(columnName);
+	return `"${columnName.toLowerCase()}"`;
+}
+/**
+* Escapes an identifier for interpolation inside double quotes
+*
+* For the positions that already quote the identifier — the DuckDB and JSON
+* upsert statements, which quote to match their schema generator — quoting is
+* what makes the identifier safe, so the only thing that has to be handled is
+* a quote character inside the name. Doubling it is the SQL escape.
+*
+* This is deliberately more permissive than {@link validateColumnName}: those
+* adapters accept column names that are not plain identifiers (`Full Name`,
+* `user-id`, `2024_total`), which matters most for the JSON adapter, whose
+* columns come straight from the keys of whatever JSON it was pointed at.
+* Rejecting them would break working code to fix an injection that quoting
+* already prevents.
+*
+* @param identifier - Identifier to place inside double quotes
+* @returns The identifier with embedded quotes doubled
+* @throws Error if the identifier is empty or contains a NUL byte
+*/
+function escapeQuotedIdentifier(identifier) {
+	const value = String(identifier);
+	if (value.length === 0 || value.includes("\0")) throw new Error(`Invalid column name: ${JSON.stringify(value)}. Column names must be non-empty and must not contain a NUL byte.`);
+	return value.replaceAll("\"", "\"\"");
+}
+/**
+* Escapes a value for interpolation inside a single-quoted SQL string literal
+*
+* The DuckDB-backed adapters read JSON through `read_json_auto('<path>')`, and
+* a file path is not something an identifier validator can check — paths
+* legitimately contain spaces, dots and, on Linux and macOS, quotes. Doubling
+* the quote is the SQL escape, and it is what keeps a file named `x'.json`
+* from ending the literal and starting a statement.
+*
+* @param value - Value to place inside single quotes
+* @returns The value with embedded single quotes doubled
+* @throws Error if the value contains a NUL byte
+*/
+function escapeStringLiteral(value) {
+	const text = String(value);
+	if (text.includes("\0")) throw new Error(`Invalid SQL string literal: ${JSON.stringify(text)}. Values must not contain a NUL byte.`);
+	return text.replaceAll("'", "''");
+}
+/**
+* Validates an index name to prevent SQL injection
+*
+* @param indexName - Index name to validate
+* @throws Error if index name contains invalid characters
+*/
+function validateIndexName(indexName) {
+	if (typeof indexName !== "string" || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(indexName)) throw new Error(`Invalid index name: ${indexName}. Index names must be a string that starts with a letter or underscore and contains only alphanumeric characters and underscores.`);
+}
+//#endregion
+//#region src/shared/connection-cache.ts
+var CACHED_VALIDATION_CAPABILITY = Symbol.for("@happyvertical/sql/connection-cache-cached-validation/v1");
+/** Race-safe async resource cache used by database adapters. */
+var ConnectionCache = class {
+	[CACHED_VALIDATION_CAPABILITY] = true;
+	#connections = /* @__PURE__ */ new Map();
+	#pending = /* @__PURE__ */ new Map();
+	#evictions = /* @__PURE__ */ new Map();
+	#requests = /* @__PURE__ */ new Map();
+	#clearing = /* @__PURE__ */ new Map();
+	#failedClosures = /* @__PURE__ */ new Map();
+	async getOrCreate(key, options, create, close, validateCached) {
+		validateDatabaseCacheOptions(options);
+		const request = key && options.cache !== false ? this.#registerRequest(key) : void 0;
+		try {
+			this.#throwIfCancelled(request);
+			if (key && options.clearCache) {
+				await this.evict(key, close);
+				this.#throwIfCancelled(request);
+			}
+			if (key) this.#throwIfFailedClosure(key);
+			if (!key || options.cache === false) return create();
+			while (true) {
+				if (this.#evictions.has(key)) {
+					await this.#waitForEviction(key);
+					this.#throwIfCancelled(request);
+				}
+				this.#throwIfFailedClosure(key);
+				const cached = this.#connections.get(key);
+				if (cached !== void 0) {
+					if (!validateCached) return cached;
+					const isValid = await validateCached(cached);
+					this.#throwIfCancelled(request);
+					if (isValid && this.#connections.get(key) === cached && !this.#evictions.has(key)) return cached;
+					if (!isValid && this.#connections.get(key) === cached && !this.#evictions.has(key)) {
+						await this.evict(key, close);
+						this.#throwIfCancelled(request);
+					}
+					continue;
+				}
+				let pending = this.#pending.get(key);
+				if (!pending) {
+					this.#throwIfCancelled(request);
+					pending = {
+						invalidated: false,
+						promise: create()
+					};
+					this.#pending.set(key, pending);
+				}
+				let connection;
+				try {
+					connection = await pending.promise;
+				} catch (error) {
+					if (this.#pending.get(key) === pending) this.#pending.delete(key);
+					throw error;
+				}
+				if (pending.invalidated || this.#evictions.has(key)) {
+					if (this.#evictions.has(key)) await this.#waitForEviction(key);
+					this.#throwIfCancelled(request);
+					if (pending.invalidated === "clear") throw this.#clearError();
+					continue;
+				}
+				this.#throwIfCancelled(request);
+				if (this.#pending.get(key) === pending) this.#pending.delete(key);
+				this.#connections.set(key, connection);
+				return connection;
+			}
+		} finally {
+			if (request && key) this.#finishRequest(key, request);
+		}
+	}
+	async evict(key, close, invalidation = "evict") {
+		const previous = this.#evictions.get(key);
+		const state = previous?.state ?? {
+			invalidated: /* @__PURE__ */ new Set(),
+			invalidation
+		};
+		if (invalidation === "clear") {
+			state.invalidation = "clear";
+			for (const pending of state.invalidated) pending.invalidated = "clear";
+		}
+		const eviction = (previous?.promise ?? Promise.resolve()).then(async () => {
+			const resources = new Set(this.#failedClosures.get(key)?.resources ?? []);
+			this.#failedClosures.delete(key);
+			const cached = this.#connections.get(key);
+			this.#connections.delete(key);
+			if (cached) resources.add(cached);
+			const pending = this.#pending.get(key);
+			this.#pending.delete(key);
+			if (pending) {
+				state.invalidated.add(pending);
+				pending.invalidated = state.invalidation;
+				const initialized = await pending.promise.catch(() => void 0);
+				if (initialized !== void 0) resources.add(initialized);
+			}
+			const closeResults = await Promise.allSettled([...resources].map(async (resource) => {
+				await close(resource);
+				return resource;
+			}));
+			const failures = closeResults.filter((result) => result.status === "rejected");
+			if (failures.length) {
+				const resourceList = [...resources];
+				const failedResources = /* @__PURE__ */ new Set();
+				closeResults.forEach((result, index) => {
+					if (result.status === "rejected") failedResources.add(resourceList[index]);
+				});
+				const error = failures.length === 1 ? failures[0].reason : new AggregateError(failures.map((failure) => failure.reason), "Multiple database connections failed to close");
+				this.#failedClosures.set(key, {
+					error,
+					resources: failedResources
+				});
+				throw error;
+			}
+		});
+		const chain = {
+			promise: eviction,
+			state
+		};
+		this.#evictions.set(key, chain);
+		try {
+			await eviction;
+		} finally {
+			if (this.#evictions.get(key) === chain) this.#evictions.delete(key);
+		}
+	}
+	async clear(close) {
+		const keys = /* @__PURE__ */ new Set([
+			...this.#connections.keys(),
+			...this.#pending.keys(),
+			...this.#evictions.keys(),
+			...this.#requests.keys(),
+			...this.#clearing.keys(),
+			...this.#failedClosures.keys()
+		]);
+		const failures = (await Promise.allSettled([...keys].map((key) => this.#clearKey(key, close)))).filter((result) => result.status === "rejected");
+		if (failures.length === 1) throw failures[0].reason;
+		if (failures.length > 1) throw new AggregateError(failures.map((failure) => failure.reason), "Multiple database connection cache entries failed to clear");
+	}
+	forget(connection) {
+		for (const [key, cached] of this.#connections) if (cached === connection) this.#connections.delete(key);
+	}
+	/** @internal Test-only visibility; includes every retained namespace. */
+	get size() {
+		return this.#connections.size + this.#pending.size + this.#evictions.size + this.#requests.size + this.#clearing.size + this.#failedClosures.size;
+	}
+	async #clearKey(key, close) {
+		this.#clearing.set(key, (this.#clearing.get(key) ?? 0) + 1);
+		try {
+			this.#cancelRequests(key);
+			await this.evict(key, close, "clear");
+			while (this.#requests.get(key)?.size) {
+				this.#cancelRequests(key);
+				await Promise.all([...this.#requests.get(key) ?? []].map((request) => request.done));
+			}
+		} finally {
+			const remaining = (this.#clearing.get(key) ?? 1) - 1;
+			if (remaining === 0) this.#clearing.delete(key);
+			else this.#clearing.set(key, remaining);
+		}
+	}
+	#cancelRequests(key) {
+		for (const request of this.#requests.get(key) ?? []) request.cancelled = true;
+	}
+	#clearError() {
+		return /* @__PURE__ */ new Error("Database connection initialization was cancelled by cache clear");
+	}
+	#finishRequest(key, request) {
+		const requests = this.#requests.get(key);
+		requests?.delete(request);
+		if (requests?.size === 0) this.#requests.delete(key);
+		request.finish();
+	}
+	#registerRequest(key) {
+		let finish = () => {};
+		const done = new Promise((resolve) => {
+			finish = resolve;
+		});
+		const request = {
+			cancelled: this.#clearing.has(key),
+			done,
+			finish
+		};
+		const requests = this.#requests.get(key) ?? /* @__PURE__ */ new Set();
+		requests.add(request);
+		this.#requests.set(key, requests);
+		return request;
+	}
+	#throwIfCancelled(request) {
+		if (request?.cancelled) throw this.#clearError();
+	}
+	#throwIfFailedClosure(key) {
+		const failure = this.#failedClosures.get(key);
+		if (failure) throw failure.error;
+	}
+	async #waitForEviction(key) {
+		while (true) {
+			const eviction = this.#evictions.get(key);
+			if (!eviction) return;
+			await eviction.promise;
+		}
+	}
+};
+/**
+* Adds cached-resource validation to a shared cache created by an older module.
+*
+* JSON connection caches live on `globalThis`, so a compatible older SDK copy
+* can create the shared object before this module loads. Mutating that object
+* preserves one cache for both module copies while upgrading its four-argument
+* `getOrCreate` method to the current validation contract.
+*/
+function enableCachedValidation(cache) {
+	if (cache[CACHED_VALIDATION_CAPABILITY]) return cache;
+	const legacyGetOrCreate = cache.getOrCreate.bind(cache);
+	const legacyClear = cache.clear.bind(cache);
+	const locks = /* @__PURE__ */ new Map();
+	let clearGeneration = 0;
+	let activeClear;
+	const runLocked = async (key, work) => {
+		const previous = locks.get(key) ?? Promise.resolve();
+		let release;
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		const chain = previous.then(() => current, () => current);
+		locks.set(key, chain);
+		await previous.catch(() => {});
+		try {
+			return await work();
+		} finally {
+			release();
+			if (locks.get(key) === chain) locks.delete(key);
+		}
+	};
+	Object.defineProperty(cache, "getOrCreate", {
+		configurable: true,
+		value: async (key, options, create, close, validateCached) => {
+			if (!key || options.cache === false) return legacyGetOrCreate(key, options, create, close);
+			const requestGeneration = clearGeneration;
+			const throwIfCleared = () => {
+				if (activeClear || requestGeneration !== clearGeneration) throw new Error("Database connection initialization was cancelled by cache clear");
+			};
+			return runLocked(key, async () => {
+				throwIfCleared();
+				let requestOptions = options;
+				while (true) {
+					throwIfCleared();
+					const candidate = await legacyGetOrCreate(key, requestOptions, create, close);
+					throwIfCleared();
+					if (!validateCached) return candidate;
+					const isValid = await validateCached(candidate);
+					throwIfCleared();
+					if (isValid) {
+						const confirmed = await legacyGetOrCreate(key, {
+							...requestOptions,
+							clearCache: false
+						}, create, close);
+						throwIfCleared();
+						if (confirmed === candidate) return candidate;
+					} else await cache.evict(key, close);
+					requestOptions = {
+						...options,
+						clearCache: false
+					};
+				}
+			});
+		},
+		writable: true
+	});
+	Object.defineProperty(cache, "clear", {
+		configurable: true,
+		value: async (close) => {
+			if (activeClear) return activeClear;
+			clearGeneration += 1;
+			const clearing = (async () => {
+				let clearError;
+				let clearFailed = false;
+				try {
+					await legacyClear(close);
+				} catch (error) {
+					clearFailed = true;
+					clearError = error;
+				}
+				while (locks.size > 0) await Promise.allSettled([...locks.values()]);
+				if (clearFailed) throw clearError;
+			})();
+			activeClear = clearing;
+			try {
+				await clearing;
+			} finally {
+				if (activeClear === clearing) activeClear = void 0;
+			}
+		},
+		writable: true
+	});
+	Object.defineProperty(cache, CACHED_VALIDATION_CAPABILITY, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+	return cache;
+}
+function validateDatabaseCacheOptions(options) {
+	if (options.dbid === "") throw new Error("Database cache dbid must be a non-empty string");
+}
+//#endregion
+//#region src/shared/transaction-lock.ts
+/**
+* How long a queued transaction waits for the connection before giving up.
+*
+* A transaction that legitimately runs longer than this will make the ones
+* behind it fail rather than stall indefinitely. Raise it with the adapter's
+* `transactionQueueTimeout` option if that is the wrong trade for a workload.
+*/
+var DEFAULT_TRANSACTION_QUEUE_TIMEOUT_MS = 3e4;
+/**
+* Creates a lock that serializes transactions on one connection.
+*
+* SQLite, DuckDB and the JSON adapter each drive a single connection, and a
+* connection can only be in one transaction at a time. `transaction()` used to
+* issue `BEGIN` on that shared connection with no serialization and no record
+* of whether one was already open, so two overlapping calls corrupted each
+* other: the second `BEGIN` threw, its `catch` ran `ROLLBACK`, and that
+* rollback landed on the *first* transaction — committing part of its work,
+* discarding the rest, and rejecting its promise. Nesting was not required;
+* two concurrent requests were enough, which made it reachable from any server
+* handling more than one at a time.
+*
+* The lock spans the whole `BEGIN` … `COMMIT`/`ROLLBACK` sequence, so a queued
+* transaction starts only once the previous one has ended. It is a
+* promise-chain mutex, the same shape as the `withNullAwareUpsertLock` the
+* SQLite adapter already used for the narrower upsert case.
+*
+* Re-entrant calls must not come through here. A nested `tx.transaction()`
+* arrives via the transaction-scoped interface, which re-enters under a
+* `SAVEPOINT` (SQLite) or refuses (DuckDB, JSON) without ever reaching the
+* top-level `transaction()`; routing one here instead would make it wait on a
+* lock its own caller is holding.
+*
+* @param adapter - Adapter name, for the timeout error
+* @param timeoutMs - Ceiling on how long to wait for a turn
+*/
+function createTransactionLock(adapter, timeoutMs = DEFAULT_TRANSACTION_QUEUE_TIMEOUT_MS) {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new DatabaseError("transactionQueueTimeout must be a positive, finite number of milliseconds", {
+		adapter,
+		timeoutMs
+	});
+	let tail = Promise.resolve();
+	let held = false;
+	const acquire = async () => {
+		const previous = tail;
+		let release = () => {};
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		tail = previous.then(() => current, () => current);
+		let timer;
+		try {
+			await new Promise((resolve, reject) => {
+				timer = setTimeout(() => {
+					reject(new DatabaseError(`Timed out after ${timeoutMs}ms waiting for the ${adapter} connection's current transaction to finish. This connection runs one transaction at a time. Usually one of: a beginTransaction() handle that was never committed or rolled back; a top-level db.* call that opens its own transaction being made inside a transaction callback, which waits on the connection its own caller holds (use the tx-scoped method instead); or simply more queued transactions than transactionQueueTimeout allows for.`, {
+						adapter,
+						timeoutMs
+					}));
+				}, timeoutMs);
+				previous.then(resolve, resolve);
+			});
+		} catch (error) {
+			release();
+			throw error;
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+		let released = false;
+		held = true;
+		return () => {
+			if (released) return;
+			released = true;
+			held = false;
+			release();
+		};
+	};
+	const run = async (work) => {
+		const release = await acquire();
+		try {
+			return await work();
+		} finally {
+			release();
+		}
+	};
+	return {
+		acquire,
+		get held() {
+			return held;
+		},
+		run
+	};
+}
+//#endregion
+//#region src/shared/postgres-dialect.ts
+/**
+* PostgreSQL dialect logic shared by every adapter that speaks to a Postgres
+* server: the `pg` adapter (`../postgres`) and the PGlite adapter
+* (`../pglite`).
+*
+* Everything here runs on a {@link PostgresQueryExecutor}, so the SQL the two
+* adapters emit is the same code rather than two copies that drift. The module
+* must stay browser-safe: no `node:` built-ins and no import of `pg`, because
+* the PGlite adapter's import graph reaches it.
+*/
+/**
+* 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(table);
+			validateColumnName(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(table);
+			validateColumnName(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(table);
+			validateColumnName(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(table);
+			validateColumnName(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)
+				});
+			}
+		}
+	};
+}
+/**
+* Keeps the first PostgreSQL statement failure attached to a transaction.
+*
+* PostgreSQL reports every later statement in an aborted transaction as
+* 25P02. Replacing the first failure with that generic state error hides the
+* actionable code and diagnostics from callers, so the tracker rethrows the
+* first failure whenever PostgreSQL reports 25P02, and exposes the recorded
+* failure so a swallowed statement error cannot make COMMIT's implicit
+* rollback look successful: PostgreSQL answers COMMIT on an aborted
+* transaction with a ROLLBACK tag and no error.
+*
+* @param isStatementError - Recognizes the driver's server-reported error
+*   class (`pg`'s or PGlite's `DatabaseError`). Anything else is an
+*   unconfirmed failure — it may be the transport, not the statement.
+*/
+function createTransactionErrorTracker(isStatementError) {
+	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;
+	};
+	/** Records a failure and returns the error the caller should see. */
+	const preserve = (error) => {
+		if (errorCode(error) === "25P02" && firstError !== void 0) return firstError;
+		if (errorCode(error) === "25P02" && firstUnconfirmedError !== void 0) return firstUnconfirmedError;
+		if (isStatementError(error)) firstError ??= error;
+		else firstUnconfirmedError ??= error;
+		return error;
+	};
+	/**
+	* Records that a statement succeeded. A successful rollback to a savepoint
+	* restores the transaction to the state at that savepoint, so a recorded
+	* statement failure has been contained.
+	*/
+	const confirm = (query) => {
+		if (isRollbackToSavepoint(query)) firstError = void 0;
+		firstUnconfirmedError = void 0;
+	};
+	const track = (operation, query) => {
+		const tracked = operation.then((result) => {
+			confirm(query);
+			return result;
+		}).catch((error) => {
+			throw preserve(error);
+		});
+		pending.add(tracked);
+		tracked.finally(() => pending.delete(tracked)).catch(() => {});
+		return tracked;
+	};
+	return {
+		pending,
+		preserve,
+		confirm,
+		track,
+		clearError: () => {
+			firstError = void 0;
+		},
+		drain: async () => {
+			while (pending.size > 0) await Promise.allSettled([...pending]);
+		},
+		getError: () => firstError,
+		getUnconfirmedError: () => firstUnconfirmedError
+	};
+}
+/**
+* Creates the dialect: every statement-level method plus nested-transaction
+* and schema-introspection builders, all bound to `host`.
+*/
+function createPostgresDialect(host) {
+	let savepointSequence = 0;
+	/**
+	* 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 (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 (executor) => {
+		serverVersionNumPromise ??= executor.query("SHOW server_version_num").then((result) => Number(result.rows[0]?.server_version_num) || 0).catch((error) => {
+			serverVersionNumPromise = void 0;
+			throw error;
+		});
+		return serverVersionNumPromise;
+	};
+	const hasNativeNullsNotDistinctIndex = async (executor, table, conflictColumns) => {
+		if (await getServerVersionNum(executor) < 15e4) return false;
+		const cacheKey = `${table}:${conflictColumns.join(",")}`;
+		let cached = nullsNotDistinctIndexCache.get(cacheKey);
+		if (!cached) {
+			cached = executor.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(() => {
+				nullsNotDistinctIndexCache.delete(cacheKey);
+				return 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
+		};
+	};
+	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(host.probeExecutor(executor), table, conflictColumns)) return executeStandardPostgresUpsert(executor, table, conflictColumns, serializedData);
+		if (!acquireTransaction) return executeNullAwarePostgresUpsert(executor, table, conflictColumns, serializedData);
+		return host.runInTransaction((transactionExecutor) => executeNullAwarePostgresUpsert(transactionExecutor, 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).
+	*
+	* Binding a client is the only difference between the two, so it is the only
+	* thing this factory parameterizes.
+	*
+	* @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(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(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(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(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(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(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(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(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
+		};
+	};
+	/**
+	* 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, scopes) => {
+		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(scopes ? scopeFor() : scopeFor(bind(scope)));
+				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 bind = (bound) => {
+			const nested = async (callback) => {
+				const parentScope = bound ?? scopes?.getStore() ?? rootScope;
+				const scope = { tail: Promise.resolve() };
+				const current = parentScope.tail.then(() => scopes ? scopes.run(scope, () => runScope(scope, callback)) : runScope(scope, callback));
+				parentScope.tail = current.then(() => void 0, () => void 0);
+				return current;
+			};
+			nested.drain = () => rootScope.tail;
+			return nested;
+		};
+		return bind();
+	};
+	return {
+		serializeRecord,
+		createClientMethods,
+		createNestedTransaction
+	};
+}
+/**
+* Builds `getTableSchema` on top of a dialect's statement methods.
+*/
+function createGetTableSchema(methods) {
+	const { many, tableExists } = methods;
+	/**
+	* Retrieves the schema information for a table
+	*
+	* @param table - Table name
+	* @returns Promise resolving to table schema info or null if table doesn't exist
+	* @throws Error if the query fails
+	*/
+	const getTableSchema = async (table) => {
+		validateTableName(table);
+		try {
+			if (!await tableExists(table)) return null;
+			const columnRows = await many`
+        SELECT
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns
+        WHERE table_name = ${table}
+          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)
+			});
+		}
+	};
+	return getTableSchema;
+}
+/**
+* Builds the `alterTable` operations on top of a statement executor.
+*/
+function createAlterTable(client) {
+	return {
+		/**
+		* Adds a new column to an existing table
+		*
+		* @param table - Table name
+		* @param column - Column definition with name
+		* @returns Promise that resolves when column is added
+		* @throws Error if the alter operation fails
+		*/
+		addColumn: async (table, column) => {
+			validateTableName(table);
+			validateColumnName(column.name);
+			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(table);
+			validateIndexName(index.name);
+			for (const col of index.columns) validateColumnName(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 } : {}
+				});
+			}
+		}
+	};
+}
+//#endregion
+export { parseConditionKey as C, wrapDatabaseError as D, unwrapRawKey as E, formatDbError as S, resolveInsertColumns as T, validateColumnNames as _, createVectorCapabilities as a, DatabaseSchemaManager as b, createTransactionLock as c, validateDatabaseCacheOptions as d, escapeQuotedIdentifier as f, validateColumnName as g, generateCreateIndexStatement as h, createTransactionErrorTracker as i, ConnectionCache as l, generateAddColumnStatement as m, createGetTableSchema as n, normalizePostgresRawQuery as o, escapeStringLiteral as p, createPostgresDialect as r, DEFAULT_TRANSACTION_QUEUE_TIMEOUT_MS as s, createAlterTable as t, enableCachedValidation as u, validateIndexName as v, raw as w, buildWhere as x, validateTableName as y };
+
+//# sourceMappingURL=postgres-dialect-Bfswr4Vs.js.map