@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/versioned/postgres/driver.js

@@ -0,0 +1,140 @@
+/**
+ * The versioned apply on Postgres (#13): binding an environment's server,
+ * its history, its lock and its statements.
+ *
+ * Settings:
+ *
+ *   the environment's history database (`yodel.config.ts`
+ *   `environments.<env>.history.database`, else YODEL_HISTORY_DATABASE,
+ *   default `yodeler`) is the history's schema: `<schema>.history`, and the lock's key
+ *   YODEL_LOCK_RETRIES      how many more times a statement that hit the lock timeout is tried (default 5)
+ *
+ * and from `sql.profiles.<env>`, as chant's applier reads them:
+ *
+ *   lockTimeoutMs       lock_timeout for every statement, and for the live-schema read (default 5000)
+ *   statementTimeoutMs  statement_timeout for a catalog change (default 60000)
+ *   scanTimeoutMs       statement_timeout for a statement that reads or rewrites rows (default none)
+ *   schemas             the schemas the plan digest's fingerprint covers (default every schema but the server's own)
+ *
+ * Two connections: the work connection, opened on first use, on which the
+ * history is read and written and the statements run; and the lock's,
+ * opened when the lock is taken and closed when it is released.
+ */
+import { YodelError } from "../../project.js";
+import { DEFAULT_HISTORY_DATABASE } from "../../history/index.js";
+import { acquireAdvisoryLock, pgIdent, PostgresHistoryStore } from "../../history/postgres/index.js";
+import { pgCatalogFingerprint, readPgCatalog } from "./catalog.js";
+import { readUnderLockTimeout } from "./waits.js";
+import { DEFAULT_LOCK_RETRIES, DEFAULT_PG_TIMEOUTS, PgStatementError, runPgStatement } from "./executor.js";
+export function pgSettings(target, env = process.env, historySchema = env.YODEL_HISTORY_DATABASE || DEFAULT_HISTORY_DATABASE) {
+    const retries = env.YODEL_LOCK_RETRIES ? Number(env.YODEL_LOCK_RETRIES) : DEFAULT_LOCK_RETRIES;
+    if (!(Number.isInteger(retries) && retries >= 0))
+        throw new YodelError(`YODEL_LOCK_RETRIES must be a whole number of retries, got ${JSON.stringify(env.YODEL_LOCK_RETRIES)}`);
+    const t = target.timeouts ?? {};
+    return {
+        historySchema,
+        timeouts: {
+            lockTimeoutMs: t.lockTimeoutMs ?? DEFAULT_PG_TIMEOUTS.lockTimeoutMs,
+            statementTimeoutMs: t.statementTimeoutMs ?? DEFAULT_PG_TIMEOUTS.statementTimeoutMs,
+            scanTimeoutMs: t.scanTimeoutMs ?? DEFAULT_PG_TIMEOUTS.scanTimeoutMs,
+        },
+        lockRetries: retries,
+    };
+}
+const chantConnect = async (endpoint, applicationName) => {
+    const { connectPostgres } = await import("@intentius/chant-lexicon-sql/postgres/live/client");
+    return connectPostgres(endpoint, { applicationName });
+};
+/** A connection opened on its first query, so a verb that reads nothing opens none. */
+export class LazyConnection {
+    open;
+    conn;
+    constructor(open) {
+        this.open = open;
+    }
+    async query(sql, params) {
+        this.conn ??= this.open();
+        return (await this.conn).query(sql, params);
+    }
+    async end() {
+        const c = this.conn;
+        this.conn = undefined;
+        if (c)
+            await (await c.catch(() => undefined))?.end();
+    }
+}
+/** Binds `env`'s Postgres server (`sql.profiles.<env>`) and its history. Connects on first use. */
+export async function openPostgres(project, env, processEnv = process.env, historySchema, connect = chantConnect) {
+    const { resolvePostgresTarget, isUnresolvedTarget } = await import("@intentius/chant-lexicon-sql/postgres/live/bind");
+    const target = resolvePostgresTarget({ environment: env.name, config: project.config, env: processEnv });
+    if (isUnresolvedTarget(target))
+        throw new YodelError(target.detail);
+    const settings = pgSettings(target, processEnv, historySchema);
+    const client = new LazyConnection(() => connect(target.endpoint, "yodel"));
+    const store = new PostgresHistoryStore(client, { schema: settings.historySchema });
+    const schemas = target.schemas;
+    const driver = postgresDriver({ client, connect: () => connect(target.endpoint, "yodel lock"), settings, schemas, store });
+    return { endpoint: target.endpoint, schemas, defaultSchema: target.defaultSchema, settings, client, store, driver };
+}
+export function postgresDriver(input) {
+    const { client, settings } = input;
+    return {
+        dialect: "postgres",
+        async acquireLock(holder) {
+            return acquireAdvisoryLock(await input.connect(), { schema: settings.historySchema, holder });
+        },
+        async liveFingerprint() {
+            const read = () => readPgCatalog(client, { schemas: input.schemas, historySchema: settings.historySchema });
+            const entries = await readUnderLockTimeout(client, read, {
+                lockTimeoutMs: settings.timeouts.lockTimeoutMs,
+                retries: settings.lockRetries,
+                schemas: input.schemas,
+                what: "the live schema",
+                log: input.log ?? ((line) => process.stderr.write(`yodel: ${line}\n`)),
+                ...(input.sleep ? { sleep: input.sleep } : {}),
+                ...(input.retryBaseMs !== undefined ? { retryBaseMs: input.retryBaseMs } : {}),
+            });
+            return pgCatalogFingerprint(entries);
+        },
+        async readCheck(sql, where) {
+            await client.query("BEGIN READ ONLY");
+            try {
+                if (where.defaultSchema)
+                    await client.query(`SELECT pg_catalog.set_config('search_path', $1, true)`, [pgIdent(where.defaultSchema)]);
+                // A check reads rows: the scan timeout (default none), and the lock timeout every statement gets.
+                await client.query(`SELECT pg_catalog.set_config('statement_timeout', $1, true), pg_catalog.set_config('lock_timeout', $2, true)`, [
+                    String(settings.timeouts.scanTimeoutMs),
+                    String(settings.timeouts.lockTimeoutMs),
+                ]);
+                return await client.query(sql);
+            }
+            finally {
+                await client.query("ROLLBACK").catch(() => undefined);
+            }
+        },
+        async runStatement(step, run) {
+            try {
+                await runPgStatement(client, step, {
+                    timeouts: settings.timeouts,
+                    retries: settings.lockRetries,
+                    succeeded: async (note) => {
+                        await run.succeeded(note);
+                    },
+                    log: run.log,
+                    ...(input.sleep ? { sleep: input.sleep } : {}),
+                    ...(input.retryBaseMs !== undefined ? { retryBaseMs: input.retryBaseMs } : {}),
+                });
+            }
+            catch (e) {
+                if (e instanceof PgStatementError)
+                    throw new Error(e.error, { cause: e });
+                throw e;
+            }
+        },
+        stepContext() {
+            return { lockTimeoutMs: settings.timeouts.lockTimeoutMs, postgres: { client, timeouts: settings.timeouts, receiptsSchema: settings.historySchema } };
+        },
+        close: () => client.end(),
+    };
+}
+//# sourceMappingURL=driver.js.map

package/dist/versioned/postgres/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../src/versioned/postgres/driver.ts"],"names":[],"mappings":"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"}

package/dist/versioned/postgres/executor.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Sending one migration statement to Postgres, the way chant's applier does
+ * (`postgres/apply/apply.ts`), with the history row that says it succeeded.
+ *
+ * ## Timeouts and retries
+ *
+ * Every statement runs with its own `lock_timeout` (default 5 s, the
+ * profile's `lockTimeoutMs`) and `statement_timeout` (the profile's
+ * `statementTimeoutMs`, default 60 s, for a catalog change; `scanTimeoutMs`,
+ * default none, for one that reads or rewrites rows). A statement blocked
+ * behind another session's lock gives up when the lock timeout passes
+ * (SQLSTATE 55P03) instead of queueing every later query on the table
+ * behind it, and is tried again after a pause that doubles each time (250
+ * ms, 500 ms, ...), up to `retries` more times (default 5). Any other error
+ * fails it at once.
+ *
+ * ## Transactions
+ *
+ * A statement chant marks `transactional` runs in a transaction of its own:
+ *
+ *     BEGIN; SET LOCAL lock_timeout ...; SET LOCAL statement_timeout ...;
+ *     <statement>; INSERT INTO <history> (... 'succeeded' ...); COMMIT
+ *
+ * so the statement and its `succeeded` row commit together or not at all.
+ * A runner killed anywhere in it leaves either both or neither: a statement
+ * whose latest row is `started` did not commit, and is sent again safely.
+ *
+ * A statement that may not run in a transaction block (`CREATE INDEX
+ * CONCURRENTLY`, `DROP INDEX CONCURRENTLY`) or that chant keeps out of one
+ * (`ALTER TYPE ... ADD VALUE`, whose label cannot be used in the transaction
+ * that adds it) runs alone, with `SET` for the session first; its
+ * `succeeded` row is written right after it, in a transaction of its own.
+ * A runner killed between the two leaves the statement run and its latest
+ * row `started`, and the next run sends it again.
+ *
+ * ## A failed CONCURRENTLY build
+ *
+ * `CREATE INDEX CONCURRENTLY` that fails (a lock timeout, a duplicate on a
+ * unique index, a cancel) leaves the index behind, INVALID: it is in the
+ * catalog, is maintained on every write, and is never used, and the next
+ * `CREATE INDEX` of that name fails because it exists. So before every
+ * attempt, the first, a retry, or a resume in a later run, and after every
+ * failure, an INVALID index of that name is dropped (`DROP INDEX
+ * CONCURRENTLY IF EXISTS`), and only an INVALID one: a valid index of that
+ * name is never touched.
+ */
+import { YodelError } from "../../project.js";
+import type { PgClient } from "../../history/postgres/index.js";
+/** SQLSTATE lock_not_available: the lock timeout passed. */
+export declare const LOCK_NOT_AVAILABLE = "55P03";
+export interface PgTimeouts {
+    lockTimeoutMs: number;
+    /** For a statement that changes only the catalog. 0 is no limit. */
+    statementTimeoutMs: number;
+    /** For a statement that reads or rewrites rows. 0 is no limit. */
+    scanTimeoutMs: number;
+}
+export declare const DEFAULT_PG_TIMEOUTS: PgTimeouts;
+export declare const DEFAULT_LOCK_RETRIES = 5;
+export declare const DEFAULT_RETRY_BASE_MS = 250;
+/** The parts of a migration's statement step the executor reads. */
+export interface PgStatement {
+    sql: string;
+    /** chant's class: `rewrite`, `validate` and `concurrently` read or rewrite rows. */
+    class: string;
+    /** False: outside any transaction. */
+    transactional: boolean;
+}
+export interface PgStatementOptions {
+    timeouts: PgTimeouts;
+    /** How many more times a statement that hit the lock timeout is tried. */
+    retries: number;
+    /** The first pause before a retry, in ms; it doubles each time. */
+    retryBaseMs?: number;
+    /**
+     * Writes the `succeeded` row on the client, given the note it carries
+     * (the retries it took, the INVALID index it dropped). Called inside the
+     * statement's transaction when it has one.
+     */
+    succeeded: (note: string) => Promise<void>;
+    log: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface PgStatementResult {
+    attempts: number;
+    /** INVALID indexes dropped before or between attempts. */
+    droppedInvalid: string[];
+    note: string;
+}
+/** A statement failed; `error` is the server's message. */
+export declare class PgStatementError extends YodelError {
+    readonly error: string;
+    readonly code: string | undefined;
+    readonly attempts: number;
+    constructor(error: string, code: string | undefined, attempts: number);
+}
+/** Whether a statement of `cls` reads or rewrites rows (chant's `scansRows`), so it runs with the scan timeout. */
+export declare const scansRows: (cls: string) => boolean;
+/** The index a `CREATE INDEX CONCURRENTLY` builds, `schema.name` quoted, when the statement names its table's schema. */
+export declare function concurrentIndex(sql: string): string | undefined;
+/** Drops `index` when it is there and INVALID. Returns whether it dropped it. */
+export declare function dropInvalidIndex(client: PgClient, index: string, timeouts: PgTimeouts, log: (line: string) => void): Promise<boolean>;
+/** Runs one statement to success or failure; see the module comment. */
+export declare function runPgStatement(client: PgClient, step: PgStatement, options: PgStatementOptions): Promise<PgStatementResult>;

package/dist/versioned/postgres/executor.js

@@ -0,0 +1,172 @@
+/**
+ * Sending one migration statement to Postgres, the way chant's applier does
+ * (`postgres/apply/apply.ts`), with the history row that says it succeeded.
+ *
+ * ## Timeouts and retries
+ *
+ * Every statement runs with its own `lock_timeout` (default 5 s, the
+ * profile's `lockTimeoutMs`) and `statement_timeout` (the profile's
+ * `statementTimeoutMs`, default 60 s, for a catalog change; `scanTimeoutMs`,
+ * default none, for one that reads or rewrites rows). A statement blocked
+ * behind another session's lock gives up when the lock timeout passes
+ * (SQLSTATE 55P03) instead of queueing every later query on the table
+ * behind it, and is tried again after a pause that doubles each time (250
+ * ms, 500 ms, ...), up to `retries` more times (default 5). Any other error
+ * fails it at once.
+ *
+ * ## Transactions
+ *
+ * A statement chant marks `transactional` runs in a transaction of its own:
+ *
+ *     BEGIN; SET LOCAL lock_timeout ...; SET LOCAL statement_timeout ...;
+ *     <statement>; INSERT INTO <history> (... 'succeeded' ...); COMMIT
+ *
+ * so the statement and its `succeeded` row commit together or not at all.
+ * A runner killed anywhere in it leaves either both or neither: a statement
+ * whose latest row is `started` did not commit, and is sent again safely.
+ *
+ * A statement that may not run in a transaction block (`CREATE INDEX
+ * CONCURRENTLY`, `DROP INDEX CONCURRENTLY`) or that chant keeps out of one
+ * (`ALTER TYPE ... ADD VALUE`, whose label cannot be used in the transaction
+ * that adds it) runs alone, with `SET` for the session first; its
+ * `succeeded` row is written right after it, in a transaction of its own.
+ * A runner killed between the two leaves the statement run and its latest
+ * row `started`, and the next run sends it again.
+ *
+ * ## A failed CONCURRENTLY build
+ *
+ * `CREATE INDEX CONCURRENTLY` that fails (a lock timeout, a duplicate on a
+ * unique index, a cancel) leaves the index behind, INVALID: it is in the
+ * catalog, is maintained on every write, and is never used, and the next
+ * `CREATE INDEX` of that name fails because it exists. So before every
+ * attempt, the first, a retry, or a resume in a later run, and after every
+ * failure, an INVALID index of that name is dropped (`DROP INDEX
+ * CONCURRENTLY IF EXISTS`), and only an INVALID one: a valid index of that
+ * name is never touched.
+ */
+import { YodelError } from "../../project.js";
+import { pgIdent } from "../../history/postgres/index.js";
+/** SQLSTATE lock_not_available: the lock timeout passed. */
+export const LOCK_NOT_AVAILABLE = "55P03";
+export const DEFAULT_PG_TIMEOUTS = { lockTimeoutMs: 5_000, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
+export const DEFAULT_LOCK_RETRIES = 5;
+export const DEFAULT_RETRY_BASE_MS = 250;
+/** A statement failed; `error` is the server's message. */
+export class PgStatementError extends YodelError {
+    error;
+    code;
+    attempts;
+    constructor(error, code, attempts) {
+        super(error, 1);
+        this.error = error;
+        this.code = code;
+        this.attempts = attempts;
+        this.name = "PgStatementError";
+    }
+}
+const sqlstate = (e) => e && typeof e === "object" && "code" in e && typeof e.code === "string" ? e.code : undefined;
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+const ms = (n) => `'${String(Math.max(0, Math.floor(n)))}ms'`;
+/** Whether a statement of `cls` reads or rewrites rows (chant's `scansRows`), so it runs with the scan timeout. */
+export const scansRows = (cls) => cls === "rewrite" || cls === "validate" || cls === "concurrently";
+const IDENT = String.raw `(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+const CONCURRENT_INDEX = new RegExp(String.raw `^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+CONCURRENTLY\s+(?:IF\s+NOT\s+EXISTS\s+)?(${IDENT})\s+ON\s+(?:ONLY\s+)?(?:(${IDENT})\s*\.\s*)?${IDENT}`, "i");
+const unquote = (id) => (id.startsWith('"') ? id.slice(1, -1).replace(/""/g, '"') : id.toLowerCase());
+/** The index a `CREATE INDEX CONCURRENTLY` builds, `schema.name` quoted, when the statement names its table's schema. */
+export function concurrentIndex(sql) {
+    const m = CONCURRENT_INDEX.exec(sql);
+    if (!m?.[1] || !m[2])
+        return undefined;
+    return `${pgIdent(unquote(m[2]))}.${pgIdent(unquote(m[1]))}`;
+}
+/** Drops `index` when it is there and INVALID. Returns whether it dropped it. */
+export async function dropInvalidIndex(client, index, timeouts, log) {
+    const [row] = await client.query("SELECT NOT i.indisvalid AS invalid FROM pg_catalog.pg_index i WHERE i.indexrelid = pg_catalog.to_regclass($1)", [index]);
+    if (row?.invalid !== true)
+        return false;
+    log(`  ${index} is INVALID, left by a CONCURRENTLY build that failed; dropping it before the build`);
+    await client.query(`SET lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+    await client.query(`DROP INDEX CONCURRENTLY IF EXISTS ${index}`);
+    return true;
+}
+const defaultSleep = (n) => new Promise((r) => setTimeout(r, n));
+/** Runs one statement to success or failure; see the module comment. */
+export async function runPgStatement(client, step, options) {
+    const { timeouts, log } = options;
+    const sleep = options.sleep ?? defaultSleep;
+    const base = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+    const statementTimeout = scansRows(step.class) ? timeouts.scanTimeoutMs : timeouts.statementTimeoutMs;
+    const index = step.transactional ? undefined : concurrentIndex(step.sql);
+    const droppedInvalid = [];
+    const lockWaits = [];
+    const note = () => {
+        const parts = [];
+        if (lockWaits.length > 0)
+            parts.push(`lock_timeout ${String(timeouts.lockTimeoutMs)}ms hit ${String(lockWaits.length)} time(s); succeeded on attempt ${String(lockWaits.length + 1)}`);
+        if (droppedInvalid.length > 0)
+            parts.push(`dropped INVALID index ${droppedInvalid.join(", ")} before building it again`);
+        return parts.join("; ");
+    };
+    const cleanIndex = async () => {
+        if (index === undefined)
+            return;
+        try {
+            if (await dropInvalidIndex(client, index, timeouts, log))
+                droppedInvalid.push(index);
+        }
+        catch (e) {
+            log(`  could not drop the INVALID index ${index}: ${messageOf(e)}; the next run tries again`);
+        }
+    };
+    for (let attempt = 1;; attempt++) {
+        try {
+            if (step.transactional) {
+                await client.query("BEGIN");
+                try {
+                    await client.query(`SET LOCAL lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+                    await client.query(`SET LOCAL statement_timeout = ${ms(statementTimeout)}`);
+                    await client.query(step.sql);
+                    await options.succeeded(note());
+                    await client.query("COMMIT");
+                }
+                catch (e) {
+                    await client.query("ROLLBACK").catch(() => undefined);
+                    throw e;
+                }
+            }
+            else {
+                await cleanIndex();
+                try {
+                    await client.query(`SET lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+                    await client.query(`SET statement_timeout = ${ms(statementTimeout)}`);
+                    await client.query(step.sql);
+                }
+                catch (e) {
+                    await cleanIndex();
+                    throw e;
+                }
+                finally {
+                    await client.query("SET lock_timeout TO DEFAULT").catch(() => undefined);
+                    await client.query("SET statement_timeout TO DEFAULT").catch(() => undefined);
+                }
+                await options.succeeded(note());
+            }
+            return { attempts: attempt, droppedInvalid, note: note() };
+        }
+        catch (e) {
+            const code = sqlstate(e);
+            if (code === LOCK_NOT_AVAILABLE && attempt <= options.retries) {
+                lockWaits.push(attempt);
+                const wait = base * 2 ** (attempt - 1);
+                log(`  lock_timeout ${String(timeouts.lockTimeoutMs)}ms: another session holds a lock this statement needs; trying again in ${String(wait)}ms (${String(attempt)}/${String(options.retries)})`);
+                await sleep(wait);
+                continue;
+            }
+            const message = messageOf(e);
+            throw new PgStatementError(code === LOCK_NOT_AVAILABLE
+                ? `${message} (lock_timeout ${String(timeouts.lockTimeoutMs)}ms, tried ${String(attempt)} times: another session kept a lock this statement needs; SQLSTATE 55P03)`
+                : message, code, attempt);
+        }
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/versioned/postgres/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/versioned/postgres/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAE1D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAU1C,MAAM,CAAC,MAAM,mBAAmB,GAAe,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;AACtH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAkCzC,2DAA2D;AAC3D,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAEnC;IACA;IACA;IAHX,YACW,KAAa,EACb,IAAwB,EACxB,QAAgB;QAEzB,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAJP,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAoB;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAGzB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAsB,EAAE,CAClD,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAE/F,MAAM,SAAS,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvF,MAAM,EAAE,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAE9E,mHAAmH;AACnH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,cAAc,CAAC;AAErH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAA,4CAA4C,CAAC;AACrE,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,+EAA+E,KAAK,4BAA4B,KAAK,cAAc,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC;AAE/L,MAAM,OAAO,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAEtH,yHAAyH;AACzH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAgB,EAAE,KAAa,EAAE,QAAoB,EAAE,GAA2B;IACvH,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAuB,+GAA+G,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACjL,IAAI,GAAG,EAAE,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxC,GAAG,CAAC,KAAK,KAAK,qFAAqF,CAAC,CAAC;IACrG,MAAM,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACvE,MAAM,MAAM,CAAC,KAAK,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAgB,EAAE,IAAiB,EAAE,OAA2B;IACnG,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,qBAAqB,CAAC;IAC1D,MAAM,gBAAgB,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACtG,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,MAAM,IAAI,GAAG,GAAW,EAAE;QACxB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,UAAU,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,kCAAkC,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACvL,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,yBAAyB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QACzH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE;QAC5B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAChC,IAAI,CAAC;YACH,IAAI,MAAM,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC;gBAAE,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,sCAAsC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC;QAChG,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;oBAC7E,MAAM,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;oBAC5E,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBAC7B,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;oBAChC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC/B,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACtD,MAAM,CAAC,CAAC;gBACV,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,UAAU,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;oBACvE,MAAM,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;oBACtE,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC/B,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,MAAM,UAAU,EAAE,CAAC;oBACnB,MAAM,CAAC,CAAC;gBACV,CAAC;wBAAS,CAAC;oBACT,MAAM,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACzE,MAAM,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBAChF,CAAC;gBACD,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACzB,IAAI,IAAI,KAAK,kBAAkB,IAAI,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBAC9D,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBACvC,GAAG,CAAC,kBAAkB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,0EAA0E,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAChM,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;gBAClB,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,IAAI,gBAAgB,CACxB,IAAI,KAAK,kBAAkB;gBACzB,CAAC,CAAC,GAAG,OAAO,kBAAkB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,aAAa,MAAM,CAAC,OAAO,CAAC,2EAA2E;gBACnK,CAAC,CAAC,OAAO,EACX,IAAI,EACJ,OAAO,CACR,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/versioned/postgres/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The versioned path on Postgres (#13): the driver the engine runs, and its
+ * parts.
+ *
+ *   openPostgres(project, env)   the server, the history store, the driver
+ *   runPgStatement(client, step) one statement under lock_timeout, retried, with its row
+ *   readPgCatalog / pgCatalogFingerprint  the live schema the plan digest covers
+ */
+export * from "./catalog.js";
+export * from "./driver.js";
+export * from "./executor.js";

package/dist/versioned/postgres/index.js

@@ -0,0 +1,12 @@
+/**
+ * The versioned path on Postgres (#13): the driver the engine runs, and its
+ * parts.
+ *
+ *   openPostgres(project, env)   the server, the history store, the driver
+ *   runPgStatement(client, step) one statement under lock_timeout, retried, with its row
+ *   readPgCatalog / pgCatalogFingerprint  the live schema the plan digest covers
+ */
+export * from "./catalog.js";
+export * from "./driver.js";
+export * from "./executor.js";
+//# sourceMappingURL=index.js.map

package/dist/versioned/postgres/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/versioned/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/versioned/postgres/waits.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reads of the live schema that another session's lock can block (#18): the
+ * fingerprint the plan digest covers, read before every apply and plan.
+ * chant's catalog reader calls `pg_get_viewdef()` and friends, which wait
+ * for a table's ACCESS SHARE lock, so a session holding ACCESS EXCLUSIVE on
+ * a declared table (a long `ALTER TABLE`, a `LOCK TABLE`) would hold the read
+ * up for as long as it holds the lock, with nothing printed.
+ *
+ * So the read runs under the profile's `lockTimeoutMs`, and when that passes
+ * (SQLSTATE 55P03) yodel says which lock it waited on and who holds it, and
+ * tries again with the same pauses and count as a statement (250 ms, then
+ * doubling, YODEL_LOCK_RETRIES more times). When the lock is still held after
+ * the last try, the read fails with the same description.
+ */
+import type { PgClient } from "../../history/postgres/index.js";
+/** A session's ACCESS EXCLUSIVE lock on a relation, held or queued for. */
+export interface LockHolder {
+    schema: string;
+    name: string;
+    pid: number;
+    granted: boolean;
+    application: string;
+}
+/** The ACCESS EXCLUSIVE locks other sessions hold (or wait for) on relations in `schemas` (every schema but the server's own when undefined). */
+export declare function lockHolders(client: PgClient, schemas: readonly string[] | undefined): Promise<LockHolder[]>;
+/** `a lock on shop.orders (held by pid 123, psql)`, or `a lock held by another session` when none could be named. */
+export declare function describeHolders(holders: readonly LockHolder[]): string;
+export interface LockedReadOptions {
+    lockTimeoutMs: number;
+    retries: number;
+    /** The schemas to look for the lock in. */
+    schemas: readonly string[] | undefined;
+    /** What is being read, for the messages: `the live schema`. */
+    what: string;
+    log: (line: string) => void;
+    retryBaseMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+declare const seconds: (ms: number) => string;
+/** Runs `read` on `client` with `lock_timeout` set, retrying (and saying why) when another session's lock holds it up. */
+export declare function readUnderLockTimeout<T>(client: PgClient, read: () => Promise<T>, o: LockedReadOptions): Promise<T>;
+/** The `PGOPTIONS` a chant child reads Postgres under, so a read blocked by a lock gives up after `lockTimeoutMs` (node-postgres passes it to the server). */
+export declare function lockTimeoutOptions(lockTimeoutMs: number, existing: string | undefined): string;
+/** Whether a read failed because the lock timeout passed. */
+export declare const isLockTimeout: (text: string | undefined) => boolean;
+export { seconds as describeMs };

package/dist/versioned/postgres/waits.js

@@ -0,0 +1,78 @@
+/**
+ * Reads of the live schema that another session's lock can block (#18): the
+ * fingerprint the plan digest covers, read before every apply and plan.
+ * chant's catalog reader calls `pg_get_viewdef()` and friends, which wait
+ * for a table's ACCESS SHARE lock, so a session holding ACCESS EXCLUSIVE on
+ * a declared table (a long `ALTER TABLE`, a `LOCK TABLE`) would hold the read
+ * up for as long as it holds the lock, with nothing printed.
+ *
+ * So the read runs under the profile's `lockTimeoutMs`, and when that passes
+ * (SQLSTATE 55P03) yodel says which lock it waited on and who holds it, and
+ * tries again with the same pauses and count as a statement (250 ms, then
+ * doubling, YODEL_LOCK_RETRIES more times). When the lock is still held after
+ * the last try, the read fails with the same description.
+ */
+import { YodelError } from "../../project.js";
+import { DEFAULT_RETRY_BASE_MS, LOCK_NOT_AVAILABLE } from "./executor.js";
+const sqlstate = (e) => e && typeof e === "object" && "code" in e && typeof e.code === "string" ? e.code : undefined;
+/** The ACCESS EXCLUSIVE locks other sessions hold (or wait for) on relations in `schemas` (every schema but the server's own when undefined). */
+export async function lockHolders(client, schemas) {
+    const rows = await client.query(`SELECT n.nspname AS schema, c.relname AS name, l.pid, l.granted, a.application_name AS application
+       FROM pg_catalog.pg_locks l
+       JOIN pg_catalog.pg_class c ON c.oid = l.relation
+       JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+       LEFT JOIN pg_catalog.pg_stat_activity a ON a.pid = l.pid
+      WHERE l.locktype = 'relation' AND l.mode = 'AccessExclusiveLock' AND l.pid <> pg_catalog.pg_backend_pid()
+        AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_toast%'
+        AND ($1::text[] IS NULL OR n.nspname = ANY ($1::text[]))
+      ORDER BY l.granted DESC, n.nspname, c.relname, l.pid
+      LIMIT 5`, [schemas ? [...schemas] : null]);
+    return rows.map((r) => ({ schema: r.schema, name: r.name, pid: Number(r.pid), granted: r.granted, application: r.application ?? "" }));
+}
+/** `a lock on shop.orders (held by pid 123, psql)`, or `a lock held by another session` when none could be named. */
+export function describeHolders(holders) {
+    if (holders.length === 0)
+        return "a lock another session holds on an object in scope";
+    const one = (h) => `${h.schema}.${h.name} (${h.granted ? "held" : "queued for"} by pid ${String(h.pid)}${h.application ? `, ${h.application}` : ""})`;
+    return `a lock on ${holders.map(one).join(", ")}`;
+}
+const sleeper = (ms) => new Promise((r) => setTimeout(r, ms));
+const seconds = (ms) => (ms < 1000 ? `${String(ms)}ms` : `${String(Math.round(ms / 100) / 10)}s`);
+/** Runs `read` on `client` with `lock_timeout` set, retrying (and saying why) when another session's lock holds it up. */
+export async function readUnderLockTimeout(client, read, o) {
+    const sleep = o.sleep ?? sleeper;
+    const base = o.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+    const [prev] = await client.query("SELECT pg_catalog.current_setting('lock_timeout') AS lock_timeout");
+    await client.query("SELECT pg_catalog.set_config('lock_timeout', $1, false)", [`${String(Math.max(0, Math.floor(o.lockTimeoutMs)))}ms`]);
+    try {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await read();
+            }
+            catch (e) {
+                if (sqlstate(e) !== LOCK_NOT_AVAILABLE)
+                    throw e;
+                const holders = await lockHolders(client, o.schemas).catch(() => []);
+                const waited = `reading ${o.what} waited ${seconds(o.lockTimeoutMs)} for ${describeHolders(holders)}`;
+                if (attempt >= o.retries) {
+                    const pid = holders.find((h) => h.granted)?.pid;
+                    throw new YodelError(`${waited}, ${String(attempt + 1)} time(s); nothing was changed. Try again once it is released${pid !== undefined ? `, or end that session with: SELECT pg_terminate_backend(${String(pid)})` : ""}`);
+                }
+                const pause = base * 2 ** attempt;
+                o.log(`${waited}; trying again in ${seconds(pause)} (${String(attempt + 1)} of ${String(o.retries)})`);
+                await sleep(pause);
+            }
+        }
+    }
+    finally {
+        await client.query("SELECT pg_catalog.set_config('lock_timeout', $1, false)", [prev?.lock_timeout ?? "0"]).catch(() => undefined);
+    }
+}
+/** The `PGOPTIONS` a chant child reads Postgres under, so a read blocked by a lock gives up after `lockTimeoutMs` (node-postgres passes it to the server). */
+export function lockTimeoutOptions(lockTimeoutMs, existing) {
+    return [existing?.trim(), `-c lock_timeout=${String(Math.max(0, Math.floor(lockTimeoutMs)))}`].filter(Boolean).join(" ");
+}
+/** Whether a read failed because the lock timeout passed. */
+export const isLockTimeout = (text) => text !== undefined && /lock timeout/i.test(text);
+export { seconds as describeMs };
+//# sourceMappingURL=waits.js.map

package/dist/versioned/postgres/waits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waits.js","sourceRoot":"","sources":["../../../src/versioned/postgres/waits.ts"],"names":[],"mappings":"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"}

package/dist/versioned/report.d.ts

@@ -0,0 +1,25 @@
+/** The versioned status as text and as JSON, for `yodel status` and `yodel apply --plan`. */
+import type { SqlDialect } from "../project.js";
+import { type HistoryLocation } from "../history/index.js";
+import { type ServerInfo } from "../server.js";
+import { type VersionedStatus } from "./state.js";
+export interface StatusReport {
+    environment: string;
+    /** The server the history was read from (#11). */
+    server?: ServerInfo | undefined;
+    /** Postgres has no topology: its report leaves it out. Default ClickHouse. */
+    dialect?: SqlDialect | undefined;
+    location: HistoryLocation;
+    /** The topology statements are rendered for, and where it came from: `cluster:main (yodel.config.ts)`. Default: the history's. */
+    topology?: string | undefined;
+    status: VersionedStatus;
+    /** The digest `yodel apply` would ask approval for, when it would not refuse. */
+    digest?: string | undefined;
+    /** Why `yodel apply` would refuse, with its exit code. */
+    refusal?: {
+        exitCode: number;
+        message: string;
+    } | undefined;
+}
+export declare function statusJson(r: StatusReport): Record<string, unknown>;
+export declare function renderStatus(r: StatusReport): string;