@rebasepro/server-postgres 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/ensure-collection-tables-BhsU6qUE.js

@@ -0,0 +1,532 @@
+import { createRequire as __createRequire } from "module";
+__createRequire(import.meta.url);
+import { r as __exportAll } from "./__vite-browser-external-BnuHet1e.js";
+import { K as extractCauseMessage } from "./cli-errors-CaI4ntyD.js";
+import { n as extractPgError } from "./pg-error-utils-vJezlXdI.js";
+import { s as vectorExtensionHint } from "./vector-index-CMJKb3C9.js";
+import { n as planSchema, r as quoteSqlLiteral } from "./plan-schema-B1YF_tYq.js";
+import { c as planJunctionTables } from "./generate-postgres-ddl-logic-B64O2oZF.js";
+import { r as quoteRelation } from "./introspect-db-queries-D6kAqReI.js";
+import { a as assertSafeIdentifier, c as helperFunctionKey, i as HELPER_FUNCTIONS, l as columnTypeDriftMessage, n as buildDeferredIndexes, o as describeHelperFunction, s as diffPlanAgainstCatalogue } from "./deferred-index-build-DP1_SNFo.js";
+import { a as isLockTimeout, l as sleep, o as isMultiStatementRefusal, r as atomicBatch, s as joinStatements } from "./boot-ddl-DVpsFN6r.js";
+import { isConcurrentDdlRace, isDuplicateObjectRace, logger } from "@rebasepro/server";
+import { REBASE_SCHEMA, declaredDatabaseExtensions } from "@rebasepro/types";
+import { getTableName, relationalCollections } from "@rebasepro/common";
+//#region src/schema/ensure-collection-tables.ts
+/**
+* Applying a schema plan to a database that is already running.
+*
+* ## What this module is
+*
+* A managed runtime boots someone else's compiled project against a database it
+* has never seen. Auth tables are ensured at boot already, but collection tables
+* were not created by anything: the platform ran the app and every `/api/data/*`
+* request answered 500 on a missing relation. `rebase db push` cannot help — it
+* is an Atlas-driven CLI command, and the runtime image ships no CLI.
+*
+* Two halves, and only one of them is here. *What the collections ask for* is
+* `schema/plan/plan-schema.ts`, shared with `db push` and the generated Drizzle
+* file; *what the database already has, and which of those statements are safe
+* to run against it* is `schema/plan/diff-plan.ts`. This module reads the
+* catalogue, runs the statements, and reports what happened.
+*
+* ## Why additive-only, forever
+*
+* This runs unattended, against a database with customers' data in it, with no
+* human reading a diff. So it may only ever do things that cannot lose data.
+* See `diff-plan.ts` for the whole of that argument.
+*/
+var ensure_collection_tables_exports = /* @__PURE__ */ __exportAll({
+	describeDriverError: () => describeDriverError,
+	ensureCollectionTables: () => ensureCollectionTables,
+	planCollectionSchemaEnsure: () => planCollectionSchemaEnsure,
+	readExistingSchema: () => readExistingSchema,
+	readSchemaFactsFor: () => readSchemaFactsFor
+});
+/**
+* Most statements in one new-table transaction. Bounds how many locks one
+* transaction holds — each new table is several relations (the heap, its TOAST
+* table, its key index) — well inside the default `max_locks_per_transaction`.
+*/
+var NEW_TABLE_BATCH = 100;
+/** The schema a collection lives in, validated before it reaches any DDL. */
+function schemaOf(collection) {
+	return assertSafeIdentifier(collection.schema || "public", "schema name");
+}
+/**
+* Decide what to add. Pure — the caller supplies what exists and runs the
+* result.
+*
+* A plan and a diff: the collections are read once, by `planSchema`, into the
+* same {@link SchemaPlan} `db push` renders `schema.sql` from, and the diff
+* subtracts what the database already has. Before that split this function had
+* its own reading of every `Property`, and the audit found twelve places where
+* it disagreed with the two generators — a required `author_id` that was
+* NOT NULL after a push and nullable after a boot among them, on the one path
+* with no developer in the loop.
+*/
+function planCollectionSchemaEnsure(allCollections, existing, options = {}) {
+	return diffPlanAgainstCatalogue(planSchema(allCollections, { databaseExtensions: options.databaseExtensions }), existing, { constraints: options.constraints });
+}
+/** Read what the database has, for the schemas the collections live in. */
+async function readExistingSchema(client, schemas, options = {}) {
+	const tables = /* @__PURE__ */ new Map();
+	const enums = /* @__PURE__ */ new Set();
+	if (schemas.length === 0) return {
+		tables,
+		enums
+	};
+	const inList = schemas.map((schema) => `'${assertSafeIdentifier(schema, "schema name")}'`).join(", ");
+	const notNullColumns = /* @__PURE__ */ new Set();
+	const columnTypes = /* @__PURE__ */ new Map();
+	const columnDefaults = /* @__PURE__ */ new Set();
+	const { rows: columns } = await client.query(`SELECT table_schema, table_name, column_name, is_nullable, udt_name, column_default,
+                numeric_precision, numeric_scale
+         FROM information_schema.columns
+         WHERE table_schema IN (${inList})`);
+	for (const row of columns) {
+		const key = `${row.table_schema}.${row.table_name}`;
+		if (!tables.has(key)) tables.set(key, /* @__PURE__ */ new Set());
+		tables.get(key).add(row.column_name);
+		if (row.is_nullable === "NO") notNullColumns.add(`${key}.${row.column_name}`);
+		if (row.udt_name) {
+			const modifier = row.udt_name === "numeric" && row.numeric_precision !== null ? `(${row.numeric_precision},${row.numeric_scale ?? 0})` : "";
+			columnTypes.set(`${key}.${row.column_name}`, `${row.udt_name}${modifier}`);
+		}
+		if (row.column_default !== null) columnDefaults.add(`${key}.${row.column_name}`);
+	}
+	const triggers = /* @__PURE__ */ new Set();
+	const { rows: triggerRows } = await client.query(`SELECT n.nspname AS schema, c.relname AS table, t.tgname AS name
+         FROM pg_trigger t
+         JOIN pg_class c ON t.tgrelid = c.oid
+         JOIN pg_namespace n ON c.relnamespace = n.oid
+         WHERE NOT t.tgisinternal AND n.nspname IN (${inList})`);
+	for (const row of triggerRows) triggers.add(`${row.schema}.${row.table}.${row.name}`);
+	const populatedTables = /* @__PURE__ */ new Set();
+	const indexes = /* @__PURE__ */ new Set();
+	const { rows: relations } = await client.query(`SELECT n.nspname AS schema, c.relname AS name, c.relkind::text AS kind
+         FROM pg_class c
+         JOIN pg_namespace n ON c.relnamespace = n.oid
+         WHERE c.relkind IN ('r', 'p', 'i', 'I') AND n.nspname IN (${inList})`);
+	const allRealTables = relations.filter((row) => row.kind === "r" || row.kind === "p");
+	for (const row of relations) if (row.kind === "i" || row.kind === "I") indexes.add(`${row.schema}.${row.name}`);
+	const wanted = options.probeTables ? new Set(options.probeTables(tables)) : void 0;
+	const realTables = wanted ? allRealTables.filter((row) => wanted.has(`${row.schema}.${row.name}`)) : allRealTables;
+	if (wanted) for (const row of allRealTables) {
+		const key = `${row.schema}.${row.name}`;
+		if (!wanted.has(key)) populatedTables.add(key);
+	}
+	if (realTables.length > 0) {
+		const probes = realTables.map((row) => `SELECT ${quoteSqlLiteral(`${row.schema}.${row.name}`)} AS key, EXISTS(SELECT 1 FROM ${quoteRelation(row.schema, row.name)} LIMIT 1) AS populated`);
+		const { rows: populationRows } = await client.query(probes.join(" UNION ALL "));
+		for (const row of populationRows) if (row.populated) populatedTables.add(row.key);
+	}
+	const enumValues = /* @__PURE__ */ new Map();
+	const { rows: enumValueRows } = await client.query(`SELECT n.nspname AS schema, t.typname AS name, e.enumlabel AS value
+         FROM pg_enum e
+         JOIN pg_type t ON e.enumtypid = t.oid
+         JOIN pg_namespace n ON t.typnamespace = n.oid
+         WHERE n.nspname IN (${inList})
+         ORDER BY t.typname, e.enumsortorder`);
+	for (const row of enumValueRows) {
+		const key = `${row.schema}.${row.name}`;
+		if (!enumValues.has(key)) enumValues.set(key, []);
+		enumValues.get(key).push(row.value);
+	}
+	const { rows: enumRows } = await client.query(`SELECT n.nspname AS schema, t.typname AS name
+         FROM pg_type t
+         JOIN pg_namespace n ON t.typnamespace = n.oid
+         WHERE t.typtype = 'e' AND n.nspname IN (${inList})`);
+	for (const row of enumRows) enums.add(`${row.schema}.${row.name}`);
+	const constraints = /* @__PURE__ */ new Set();
+	const { rows: constraintRows } = await client.query(`SELECT n.nspname AS schema, c.relname AS table, con.conname AS name
+         FROM pg_constraint con
+         JOIN pg_class c ON con.conrelid = c.oid
+         JOIN pg_namespace n ON c.relnamespace = n.oid
+         WHERE n.nspname IN (${inList})`);
+	for (const row of constraintRows) constraints.add(`${row.schema}.${row.table}.${row.name}`);
+	const invalidIndexes = /* @__PURE__ */ new Set();
+	const { rows: invalidRows } = await client.query(`SELECT n.nspname AS schema, c.relname AS name
+         FROM pg_index i
+         JOIN pg_class c ON c.oid = i.indexrelid
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         WHERE NOT i.indisvalid AND n.nspname IN (${inList})`);
+	for (const row of invalidRows) invalidIndexes.add(`${row.schema}.${row.name}`);
+	const columnComments = /* @__PURE__ */ new Map();
+	const { rows: commentRows } = await client.query(`SELECT n.nspname AS schema, c.relname AS table, a.attname AS column, d.description AS comment
+         FROM pg_description d
+         JOIN pg_class c ON d.objoid = c.oid
+         JOIN pg_namespace n ON c.relnamespace = n.oid
+         JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = d.objsubid
+         WHERE d.objsubid > 0 AND n.nspname IN (${inList})`);
+	for (const row of commentRows) {
+		if (row.comment == null) continue;
+		columnComments.set(`${row.schema}.${row.table}.${row.column}`, row.comment);
+	}
+	const functions = /* @__PURE__ */ new Map();
+	const helperNames = HELPER_FUNCTIONS.map((qualified) => qualified.split(".")).map(([schema, name]) => `(${quoteSqlLiteral(schema)}, ${quoteSqlLiteral(name)})`).join(", ");
+	const { rows: functionRows } = await client.query(`SELECT n.nspname AS schema, p.proname AS name, pg_get_function_identity_arguments(p.oid) AS args,
+                format_type(p.prorettype, NULL) AS returns, l.lanname AS language,
+                p.provolatile::text AS volatility, p.proisstrict AS strict, p.proparallel::text AS parallel,
+                p.prosecdef AS security_definer, p.proleakproof AS leakproof, p.procost AS cost,
+                p.proconfig IS NOT NULL AS has_config, p.prosrc AS body
+         FROM pg_proc p
+         JOIN pg_namespace n ON p.pronamespace = n.oid
+         JOIN pg_language l ON p.prolang = l.oid
+         WHERE (n.nspname, p.proname) IN (${helperNames})`);
+	for (const row of functionRows) functions.set(helperFunctionKey(row.schema, row.name, row.args), describeHelperFunction({
+		returns: row.returns,
+		language: row.language,
+		volatility: row.volatility,
+		strict: row.strict,
+		parallel: row.parallel,
+		securityDefiner: row.security_definer,
+		leakproof: row.leakproof,
+		cost: Number(row.cost),
+		hasConfig: row.has_config,
+		body: row.body
+	}));
+	const extensions = /* @__PURE__ */ new Set();
+	const { rows: extensionRows } = await client.query("SELECT extname AS name FROM pg_extension");
+	for (const row of extensionRows) extensions.add(row.name);
+	return {
+		tables,
+		enums,
+		constraints,
+		columnComments,
+		enumValues,
+		notNullColumns,
+		populatedTables,
+		columnTypes,
+		columnDefaults,
+		triggers,
+		indexes,
+		invalidIndexes,
+		extensions,
+		functions
+	};
+}
+/**
+* The planned tables that exist and lack at least one planned column — the
+* only ones whose emptiness the diff consults (a NOT NULL or UNIQUE arriving
+* with a new column). A superset, never a subset: a column the plan renames
+* from a legacy name reads as missing here too.
+*/
+function tablesGainingColumns(plan, catalogue) {
+	const gaining = [];
+	for (const table of plan.tables) {
+		const columns = catalogue.get(table.qualified);
+		if (columns && table.columns.some((column) => !columns.has(column.column))) gaining.push(table.qualified);
+	}
+	return gaining;
+}
+/**
+* What to tell an operator whose `search` block no longer matches its column.
+*
+* Every line here is doing work: naming the collection is not enough, because
+* the symptom (a search that finds nothing) points at the data, not the schema;
+* and the remediation has to be exact, because it is a table rewrite the
+* operator is being asked to schedule rather than discover.
+*/
+function searchDriftMessage(drift) {
+	return "The `search` block changed after its generated column was created, and Postgres cannot alter a generated expression in place.\nRebase will not rebuild it for you: dropping and re-adding a STORED generated column rewrites the whole table under an ACCESS EXCLUSIVE lock and rebuilds its GIN index, which is an outage this unattended path may not schedule on your behalf.\nUntil it is rebuilt the column keeps indexing the previous fields, weights and language — searches for anything added since return nothing, which reads from outside as \"no such row\".\nRun these (or revert the block to what the column was built from), then boot again:\n" + drift.map((d) => `  "${d.table}"."${d.column}" was generated from a different \`search\` block (recorded ${d.found}, current ${d.expected}).\n` + d.rebuild.map((s) => `      ${s}`).join("\n")).join("\n") + "\n  The GIN index is dropped with the column and recreated concurrently on the next boot.";
+}
+/**
+* Read what the database looks like, for the schemas a set of collections
+* lives in.
+*
+* The same read `ensureCollectionTables` does at boot, exposed on its own for
+* the callers that want to *plan* against a real database without changing it —
+* the live schema editor, which has to tell somebody what a change would do
+* before they agree to it.
+*/
+async function readSchemaFactsFor(client, collections) {
+	const relational = relationalCollections(collections);
+	const junctions = planJunctionTables(relational);
+	const schemas = Array.from(/* @__PURE__ */ new Set([...relational.map(schemaOf), ...junctions.map((junction) => junction.schema)]));
+	const declared = [...relational.map((collection) => `${schemaOf(collection)}.${getTableName(collection)}`), ...junctions.map((junction) => `${junction.schema}.${junction.table}`)];
+	return readExistingSchema(client, schemas, { probeTables: () => declared });
+}
+/**
+* Bring the database up to date. Returns what it did.
+*
+* Each statement runs on its own rather than in one transaction: they are all
+* independently safe and idempotent, and a single failure (an enum label that
+* cannot be added, say) should not roll back the tables that were created fine.
+* The error is surfaced with the statement that caused it.
+*/
+async function ensureCollectionTables(client, collections, log, options = {}) {
+	const schema = planSchema(collections, { databaseExtensions: options.databaseExtensions ?? declaredDatabaseExtensions() });
+	const schemas = Array.from(new Set(schema.tables.map((table) => table.schema)));
+	for (const name of schemas) {
+		assertSafeIdentifier(name, "schema name");
+		if (name !== "public") await client.query(`CREATE SCHEMA IF NOT EXISTS "${name}";`);
+	}
+	if (schema.tables.some((table) => table.triggers.length > 0)) await client.query(`CREATE SCHEMA IF NOT EXISTS "${REBASE_SCHEMA}";`);
+	const plan = diffPlanAgainstCatalogue(schema, await readExistingSchema(client, schemas, { probeTables: (catalogue) => tablesGainingColumns(schema, catalogue) }), {
+		constraints: options.constraints,
+		deferLiveIndexes: true
+	});
+	const failures = [];
+	for (const legacy of plan.legacyForeignKeys) {
+		const message = `Renaming "${legacy.table}"."${legacy.legacy}" to "${legacy.expected}". The old name is the one Rebase derived for this relation before it singularized properly; the column keeps its data, indexes and constraints. To keep the old name instead, set \`localKey: "${legacy.legacy}"\` on the relation and this will stop.`;
+		logger.info(`[schema] ${message}`);
+		log?.(message);
+	}
+	if (plan.searchDrift.length > 0) throw new Error(searchDriftMessage(plan.searchDrift));
+	for (const adopted of plan.searchAdopted) {
+		const message = `Adopting the existing generated column "${adopted.table}"."${adopted.column}" and recording what the current \`search\` block would generate. Any later change to that block will be detected and refused; a change made *before* this version was deployed cannot be, so if search has been missing content, rebuild the column once: ALTER TABLE "${adopted.table.split(".").join("\".\"")}" DROP COLUMN "${adopted.column}"; and boot again.`;
+		logger.info(`[schema] ${message}`);
+		log?.(message);
+	}
+	for (const skip of plan.vectorIndexSkipped) {
+		const message = `No ANN index on "${skip.table}"."${skip.column}": ${skip.reason}`;
+		logger.warn(`[schema] ${message}`);
+		log?.(message);
+	}
+	for (const withheld of plan.withheldConstraints) {
+		const message = `No ${withheld.kind === "unique" ? "UNIQUE" : "NOT NULL"} on "${withheld.target}": ${withheld.reason} ${withheld.remedy}`;
+		logger.warn(`[schema] ${message}`);
+		log?.(message);
+	}
+	for (const drift of plan.columnTypeDrift) {
+		const message = columnTypeDriftMessage(drift);
+		logger.warn(`[schema] ${message}`);
+		log?.(message);
+	}
+	for (const orphan of plan.orphanedRequiredColumns) {
+		const [schema, table] = orphan.table.split(".");
+		const message = `"${orphan.table}"."${orphan.column}" is NOT NULL with no default, and the "${orphan.slug}" collection no longer declares it. Every insert will be rejected for a field you cannot set (PG_23502, naming "${orphan.column}"). This is what a renamed property looks like: the new column was added, and the old one cannot be dropped unattended. Fix it with ONE of:
+      ALTER TABLE "${schema}"."${table}" DROP COLUMN "${orphan.column}";               -- the rename is complete\n      ALTER TABLE "${schema}"."${table}" ALTER COLUMN "${orphan.column}" DROP NOT NULL; -- keep the data, stop requiring it\n      ...or declare the property again, if the column is still wanted.`;
+		logger.warn(`[schema] ${message}`);
+		log?.(message);
+	}
+	const builtHere = options.deferIndexBuilds ? plan.deferredIndexes.filter((index) => index.unique === true) : plan.deferredIndexes;
+	const leftToCaller = options.deferIndexBuilds ? plan.deferredIndexes.filter((index) => index.unique !== true) : plan.deferredIndexes;
+	const buildIndexes = async () => {
+		if (builtHere.length === 0) return void 0;
+		const outcome = await buildDeferredIndexes(options.openIndexBuildSession ?? (async () => ({
+			query: (sql) => client.query(sql),
+			dedicated: false,
+			release: () => void 0
+		})), builtHere, {
+			log,
+			lockTimeoutMs: options.lockTimeoutMs
+		});
+		assertUniqueIndexesBuilt(builtHere, outcome);
+		return outcome;
+	};
+	const finish = async () => {
+		const indexBuilds = await buildIndexes();
+		return {
+			...plan,
+			deferredIndexes: leftToCaller,
+			failures,
+			indexBuilds
+		};
+	};
+	if (plan.actions.length === 0) {
+		if (plan.deferredIndexes.length === 0) log?.("Schema is up to date; nothing to create.");
+		return finish();
+	}
+	const lockBudget = options.lockTimeoutMs !== void 0 ? {
+		lockTimeoutMs: options.lockTimeoutMs,
+		atomic: true
+	} : void 0;
+	const multi = lockBudget ?? { atomic: true };
+	const createdTables = new Set(plan.actions.filter((a) => a.kind === "create-table").map((a) => a.target));
+	const batchable = (action) => options.batchNewTables === true && multi.atomic && (action.kind === "create-enum" || createdTables.has(action.target.split(".").slice(0, 2).join("."))) && action.kind !== "add-enum-value" && !CONCURRENTLY_RE.test(action.sql);
+	const applyBatch = async (group) => {
+		const statements = group.map((action) => action.sql);
+		try {
+			await client.query(lockBudget ? atomicBatch(statements, lockBudget.lockTimeoutMs) : joinStatements(statements));
+			return true;
+		} catch (err) {
+			if (isMultiStatementRefusal(err)) multi.atomic = false;
+			else log?.(`${group.length} statement(s) for new tables failed as one transaction (${describeDriverError(err).split("\n")[0]}); applying them one at a time`);
+			return false;
+		}
+	};
+	const applyOne = async (action) => {
+		try {
+			if (await applyAction(client, action, lockBudget)) log?.(`${action.kind}: ${action.target}`);
+			else log?.(`${action.kind}: ${action.target} (already created by a peer)`);
+		} catch (err) {
+			const message = describeDriverError(err);
+			if (action.kind === "add-constraint" || action.kind === "comment-column" || action.kind === "create-index" && !/CREATE\s+UNIQUE\s+INDEX/i.test(action.sql)) {
+				failures.push({
+					kind: action.kind,
+					target: action.target,
+					error: message
+				});
+				return;
+			}
+			const lockHint = isLockTimeout(err) ? "\n  hint: another session held this table's lock for every attempt (a long transaction, a report or a dump). Nothing was changed; boot again once it has finished." : "";
+			throw new Error(`Failed to ${action.kind} ${action.target}: ${message}${vectorExtensionHint(message)}${lockHint}\n  ${action.sql}`);
+		}
+	};
+	for (let i = 0; i < plan.actions.length;) {
+		let end = i;
+		while (end < plan.actions.length && end - i < NEW_TABLE_BATCH && batchable(plan.actions[end])) end++;
+		if (end - i > 1 && await applyBatch(plan.actions.slice(i, end))) {
+			for (const action of plan.actions.slice(i, end)) log?.(`${action.kind}: ${action.target}`);
+			i = end;
+			continue;
+		}
+		const last = Math.max(end, i + 1);
+		for (; i < last; i++) await applyOne(plan.actions[i]);
+	}
+	return finish();
+}
+/**
+* Fail the ensure for a UNIQUE index on a live table that could not be built,
+* exactly as a failed UNIQUE `create-index` action always has (see `applyOne`).
+*
+* "Another index on the table is being built" counts: the table's lock is
+* held by a build that may run for minutes, and serving the collection
+* meanwhile would be serving a promise the database is not keeping. Another
+* instance building *this* index does not: once its build commits the
+* constraint holds, which is also what a peer's `IF NOT EXISTS` race meant.
+*/
+function assertUniqueIndexesBuilt(indexes, outcome) {
+	for (const index of indexes) {
+		if (index.unique !== true) continue;
+		const qualified = `${index.schema}.${index.indexName}`;
+		const reason = outcome.failed.find((failure) => failure.index === qualified)?.error ?? outcome.skipped.find((skip) => skip.index === qualified && skip.reason === "another index on the table is being built")?.reason;
+		if (reason === void 0) continue;
+		throw new Error(`Failed to create-index ${index.schema}.${index.table}: ${qualified}: ${reason}\n  ${index.sql}`);
+	}
+}
+/**
+* What actually went wrong, rather than what the ORM said about it.
+*
+* Drizzle wraps every driver error, and its `message` is literally
+* ``Failed query: ${sql}\nparams: ${params}`` — the statement we already know,
+* and not one word of Postgres's answer. Reporting `err.message` therefore
+* produced a failure that named the statement twice and the *reason* zero
+* times, so four unrelated boot failures — a missing extension, a wrong
+* privilege, a bad index method, a constraint the rows violate — all read
+* identically to whoever had to fix them.
+*
+* Two consequences, both observed in the field before this existed:
+*
+*  1. On a managed deployment the reason never reaches anybody. Boot dies, the
+*     pod never goes ready, and the deploy reports a readiness timeout — so the
+*     one line that says why is the one line that was thrown away here.
+*  2. {@link vectorExtensionHint} matches on the error text. Against the
+*     wrapper it matched nothing, so the hint written specifically to explain a
+*     missing pgvector never fired on the path that raises it.
+*
+* `detail` and `hint` come along because they are the fields Postgres uses to
+* say which object it meant and what to do about it — `CREATE EXTENSION` names
+* the missing library there, and a rejected constraint names the row. This
+* writes into the tenant's own boot log, about the tenant's own database.
+*/
+function describeDriverError(err) {
+	const pg = extractPgError(err);
+	if (pg) {
+		const parts = [pg.code ? `${pg.message} [${pg.code}]` : pg.message];
+		if (pg.detail) parts.push(`  detail: ${pg.detail}`);
+		if (pg.hint) parts.push(`  hint: ${pg.hint}`);
+		return parts.join("\n");
+	}
+	const cause = extractCauseMessage(err);
+	if (cause) return cause;
+	return err instanceof Error ? err.message : String(err);
+}
+/** ` CONCURRENTLY ` as it appears in a rendered `CREATE [UNIQUE] INDEX`. */
+var CONCURRENTLY_RE = /\sCONCURRENTLY\s/i;
+/**
+* `25001 active_sql_transaction` — "cannot run inside a transaction block".
+*
+* Only ever raised here by `CREATE INDEX CONCURRENTLY`, and only when the
+* connection we were handed is inside a transaction. Deliberately narrow: it
+* decides to retry a *different* statement, so it must not fire on anything it
+* has not been reasoned about.
+*/
+function isTransactionBlockRefusal(err) {
+	return extractPgError(err)?.code === "25001";
+}
+/** Attempts per action, including the first. Matches the server's bootstraps. */
+var DDL_ATTEMPTS = 4;
+/**
+* Attempts at an action whose table lock is held, including the first.
+*
+* Unlike a policy, a schema change cannot be deferred — the collection's code
+* expects the column — so a lock that never frees still fails the boot, as a
+* statement timeout did. Ten one-second attempts with backoff between them wait
+* about as long as the old 30 s statement timeout did, but a live query on that
+* table now waits at most one second at a time instead of thirty.
+*/
+var LOCK_ATTEMPTS = 10;
+/**
+* Whether an action may be sent as `SET LOCAL lock_timeout; <statement>` — one
+* implicit transaction. Not `CREATE INDEX CONCURRENTLY`, which Postgres refuses
+* inside any transaction block (and which waits on no lock a reader holds), and
+* not `ALTER TYPE … ADD VALUE`, which Postgres before 12 refuses there too and
+* which locks a type, not a table.
+*/
+var takesLockBudget = (action, sql) => action.kind !== "add-enum-value" && !CONCURRENTLY_RE.test(sql);
+/**
+* Run one planned statement, surviving a simultaneous boot.
+*
+* Every statement in a plan is written to be idempotent, and that is not the
+* same as being safe to run concurrently: `CREATE … IF NOT EXISTS` reads the
+* catalog and then writes to it as two steps, so peers starting together both
+* see "absent" and the loser gets a duplicate key on a *catalog* index. Measured
+* against Postgres 18: five instances, 8 of 10 calls lost. `CREATE TYPE` is
+* worse, because Postgres has no `IF NOT EXISTS` for it at all.
+*
+* What made that fatal here rather than merely noisy is the loop this sits in.
+* A losing statement threw, and the throw abandoned **every remaining action in
+* the plan** — so a replica that lost one race came up missing tables it never
+* attempted, and the boot log blamed the one statement that failed.
+*
+* @returns `true` if this process applied the statement, `false` if a peer had
+*   already created the object. The distinction is only for the log; both mean
+*   the object is now there.
+* @throws the original error for anything that is not a race — a syntax error, a
+*   permission failure, a unique constraint the customer's own rows violate.
+*/
+async function applyAction(client, action, lockBudget) {
+	let sqlText = action.sql;
+	let lockAttempts = 0;
+	for (let attempt = 1;; attempt++) {
+		const budgeted = lockBudget?.atomic === true && takesLockBudget(action, sqlText);
+		try {
+			await client.query(budgeted ? atomicBatch([sqlText], lockBudget.lockTimeoutMs) : sqlText);
+			return true;
+		} catch (err) {
+			if (budgeted && isMultiStatementRefusal(err)) {
+				lockBudget.atomic = false;
+				attempt--;
+				continue;
+			}
+			if (budgeted && isLockTimeout(err) && ++lockAttempts < LOCK_ATTEMPTS) {
+				logger.debug(`[schema] ${action.kind} ${action.target}: the table's lock is held by another session (attempt ${lockAttempts}/${LOCK_ATTEMPTS}) — retrying`);
+				attempt--;
+				await sleep(Math.min(500 * lockAttempts, 2e3) * (1 + Math.random()));
+				continue;
+			}
+			if (isTransactionBlockRefusal(err) && CONCURRENTLY_RE.test(sqlText)) {
+				sqlText = sqlText.replace(CONCURRENTLY_RE, " ");
+				logger.warn(`[schema] ${action.kind} ${action.target}: this connection is inside a transaction, so the index is being built with a write lock rather than concurrently. Writes to this table block until it finishes.`);
+				continue;
+			}
+			if (isDuplicateObjectRace(err)) {
+				logger.debug(`[schema] ${action.kind} ${action.target}: already created by another instance`);
+				return false;
+			}
+			if (isConcurrentDdlRace(err) && attempt < DDL_ATTEMPTS) {
+				logger.debug(`[schema] ${action.kind} ${action.target}: lost a race with another instance (attempt ${attempt}/${DDL_ATTEMPTS}) — retrying`);
+				await new Promise((resolve) => setTimeout(resolve, 40 * attempt * (1 + Math.random())));
+				continue;
+			}
+			throw err;
+		}
+	}
+}
+//#endregion
+export { readSchemaFactsFor as a, readExistingSchema as i, ensure_collection_tables_exports as n, planCollectionSchemaEnsure as r, describeDriverError as t };
+
+//# sourceMappingURL=ensure-collection-tables-BhsU6qUE.js.map