@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/versioned/op.js

@@ -0,0 +1,153 @@
+/**
+ * The approval: a versioned apply runs as a chant Op, behind a gate bound to
+ * the plan digest, the same machinery #6's declarative apply runs through.
+ *
+ * The project declares one Op per environment:
+ *
+ *   Plan     shell("yodel apply <env> --digest", { id: "plan" })
+ *            prints the digest of the pending migrations and the live schema
+ *   Approve  gate(..., { plan: stepOutput(plan, "stdout") })
+ *            a resolution counts only for that digest (`chant approve <op> <gate> --plan <digest>`)
+ *   Apply    shell("yodel apply <env> --execute", { env: { YODEL_APPROVED_PLAN: stepOutput(plan, "stdout") } })
+ *            takes the lock, computes the digest again, refuses if it moved, applies
+ *
+ * `yodel apply <env>` runs it with `chant run <op>`, as #6 runs an ApplyOp.
+ * The gate ledger is chant's (the `chant/lifecycle` branch); yodel keeps no
+ * approval store of its own. The digest is checked twice: by the gate, on
+ * every run, against the approval; and by the Apply step, under the lock,
+ * against the digest the gate passed, so a change between the two (another
+ * runner applying, a table altered out of band) refuses too.
+ *
+ * `chant run <op>` run directly (in CI) needs `yodel` on PATH, e.g.
+ * `PATH="$PWD/node_modules/.bin:$PATH"`. When `yodel apply` runs it, yodel
+ * puts a `yodel` that runs itself first on the child's PATH.
+ */
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { YodelError } from "../project.js";
+import { chantInstall, runChant } from "../chant/process.js";
+import { GATED, readApplyRun } from "../chant/apply.js";
+/** The env var the Apply step reads the approved digest from. */
+export const APPROVED_PLAN_ENV = "YODEL_APPROVED_PLAN";
+/** Passes `--allow-out-of-order` through `chant run` to the Op's steps. */
+export const ALLOW_OUT_OF_ORDER_ENV = "YODEL_ALLOW_OUT_OF_ORDER";
+const command = (verb) => new RegExp(`^(?:npx\\s+)?yodel\\s+apply\\s+(\\S+)\\s+${verb}(?:\\s|$)`);
+const DIGEST = command("--digest");
+const EXECUTE = command("--execute");
+const steps = (config) => config.phases.flatMap((p) => p.steps);
+function shellCmd(step) {
+    if (step.kind !== "activity" || step.fn !== "shellCmd")
+        return undefined;
+    const cmd = step.args?.cmd;
+    return typeof cmd === "string" ? { cmd: cmd.trim(), ...(step.id ? { id: step.id } : {}) } : undefined;
+}
+/** The parts of a migrations Op for `env`, when `config` is one. */
+export function migrateOpParts(config, env) {
+    const all = steps(config);
+    const plan = all.map(shellCmd).find((s) => s && DIGEST.exec(s.cmd)?.[1] === env);
+    const execute = all.map(shellCmd).find((s) => s && EXECUTE.exec(s.cmd)?.[1] === env);
+    if (!plan || !execute)
+        return undefined;
+    const gate = all.find((s) => {
+        if (s.kind !== "gate" || s.plan === undefined || typeof s.plan === "string")
+            return false;
+        return s.plan.step === plan.id;
+    });
+    return gate?.kind === "gate" ? { gate: gate.gate, quorum: gate.approval !== undefined } : { gate: undefined, quorum: false };
+}
+/** How to declare the Op `yodel apply` looks for. */
+export function migrateOpExample(env) {
+    return [
+        `// ops/migrate-${env}.op.ts`,
+        `import { Op, phase, gate, shell, stepOutput } from "@intentius/chant/op";`,
+        ``,
+        `const plan = shell("yodel apply ${env} --digest", { id: "plan" });`,
+        `const digest = stepOutput(plan, "stdout");`,
+        ``,
+        `export const op = Op({`,
+        `  name: "migrate-${env}",`,
+        `  overview: "Apply the pending migrations to ${env}, behind an approval bound to their plan digest",`,
+        `  phases: [`,
+        `    phase("Plan", [plan]),`,
+        `    phase("Approve", [gate("approve-migrate-${env}", { plan: digest })]),`,
+        `    phase("Apply", [shell("yodel apply ${env} --execute", { env: { ${APPROVED_PLAN_ENV}: digest }, timeout: "2h" })]),`,
+        `  ],`,
+        `});`,
+    ].join("\n");
+}
+/** Picks the migrations Op for `env` from discovered Ops. Pure. */
+export function selectMigrateOp(ops, project, env, name) {
+    const found = [...ops.values()].flatMap((o) => {
+        const parts = migrateOpParts(o.config, env.name);
+        return parts ? [{ ...o, parts }] : [];
+    });
+    const chosen = name ? found.filter((o) => o.config.name === name) : found;
+    if (chosen.length === 0) {
+        if (name && ops.has(name))
+            throw new YodelError(`Op "${name}" is not a migrations Op for environment ${env.name} (a Plan step running "yodel apply ${env.name} --digest", a gate bound to it, an Apply step running "yodel apply ${env.name} --execute")`);
+        throw new YodelError(name
+            ? `no Op named "${name}" in ${project.dir}`
+            : `no Op applies the migrations to environment ${env.name} in ${project.dir}; declare one, for example:\n\n${migrateOpExample(env.name)}`);
+    }
+    if (chosen.length > 1)
+        throw new YodelError(`${String(chosen.length)} Ops apply the migrations to ${env.name} (${chosen.map((o) => o.config.name).join(", ")}); pick one with --op <name>`);
+    const [op] = chosen;
+    if (!op.parts.gate) {
+        throw new YodelError(`Op "${op.config.name}" (${op.filePath}) has no approval gate bound to its Plan step's digest, and yodel only applies behind one; give it gate(..., { plan: stepOutput(plan, "stdout") })`);
+    }
+    return { name: op.config.name, filePath: op.filePath, gate: op.parts.gate, quorum: op.parts.quorum };
+}
+export async function findMigrateOp(project, env, name) {
+    const { discoverOps } = await import("@intentius/chant/op/discover");
+    let found;
+    try {
+        found = await discoverOps({ cwd: project.dir });
+    }
+    catch (e) {
+        throw new YodelError(`could not discover Ops in ${project.dir}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (found.errors.length > 0 && found.ops.size === 0)
+        throw new YodelError(`could not discover Ops in ${project.dir}:\n${found.errors.join("\n")}`);
+    return selectMigrateOp(found.ops, project, env, name);
+}
+/** This yodel's own entry point: `bin.js` when built, `bin.ts` from source. */
+function selfEntry() {
+    const here = fileURLToPath(import.meta.url);
+    return fileURLToPath(new URL(`../bin${extname(here)}`, import.meta.url));
+}
+/** A directory holding a `yodel` that runs this yodel, for a child's PATH. */
+export function yodelShim() {
+    const dir = mkdtempSync(join(tmpdir(), "yodel-shim-"));
+    const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    const script = `#!/bin/sh\nexec ${q(process.execPath)} --import ${q(chantInstall().loader)} ${q(selfEntry())} "$@"\n`;
+    const path = join(dir, "yodel");
+    writeFileSync(path, script);
+    chmodSync(path, 0o755);
+    return { dir, dispose: () => { rmSync(dir, { recursive: true, force: true }); } };
+}
+/** Runs the migrations Op with `chant run`, with this yodel on PATH and `--allow-out-of-order` passed through. */
+export async function runMigrateOp(project, op, options) {
+    const shim = yodelShim();
+    try {
+        const base = options.env ?? process.env;
+        // The approved digest only ever comes from the gate, never from the caller's environment.
+        const rest = Object.fromEntries(Object.entries(base).filter(([k]) => k !== APPROVED_PLAN_ENV && k !== ALLOW_OUT_OF_ORDER_ENV));
+        const env = {
+            ...rest,
+            PATH: [shim.dir, base.PATH ?? ""].filter(Boolean).join(delimiter),
+            ...(options.allowOutOfOrder ? { [ALLOW_OUT_OF_ORDER_ENV]: "1" } : {}),
+        };
+        const result = await runChant(["run", op.name, "--gated-exit", String(GATED)], {
+            cwd: project.dir,
+            env,
+            ...(options.onOutput ? { onStdout: options.onOutput, onStderr: options.onOutput } : {}),
+        });
+        return readApplyRun(result.code, `${result.stdout}\n${result.stderr}`);
+    }
+    finally {
+        shim.dispose();
+    }
+}
+//# sourceMappingURL=op.js.map

package/dist/versioned/op.js.map

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

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

@@ -0,0 +1,33 @@
+/**
+ * The live-schema fingerprint a Postgres plan digest covers: every object
+ * chant's catalog reader sees in the environment's schemas
+ * (`sql.profiles.<env>.schemas`; every schema but the server's own when it
+ * names none), by its type, schema, name, the statements that create it as
+ * the server prints them, and its comment. The history schema is left out,
+ * so recording a run does not move the digest, and so are chant's own
+ * working objects (a migration's new column, its receipts), which the reader
+ * skips.
+ *
+ * It is the same reader `chant sql plan` and the applier diff against, so a
+ * change the plan would see (a column added out of band, an index dropped, a
+ * default changed) is a new fingerprint, and an approval given before it
+ * does not carry over.
+ */
+import type { PgClient } from "../../history/postgres/index.js";
+export interface PgLiveScope {
+    /** The schemas in scope; every schema but the server's own when undefined. */
+    schemas: string[] | undefined;
+    /** Left out of the fingerprint. */
+    historySchema: string;
+}
+export interface PgCatalogEntry {
+    type: string;
+    schema: string;
+    name: string;
+    statement: string;
+    comment: string;
+}
+/** Reads what the fingerprint covers, in a stable order. */
+export declare function readPgCatalog(client: PgClient, scope: PgLiveScope): Promise<PgCatalogEntry[]>;
+/** `sha256:<hex>` over the catalog's canonical JSON. */
+export declare function pgCatalogFingerprint(entries: readonly PgCatalogEntry[]): string;

package/dist/versioned/postgres/catalog.js

@@ -0,0 +1,34 @@
+/**
+ * The live-schema fingerprint a Postgres plan digest covers: every object
+ * chant's catalog reader sees in the environment's schemas
+ * (`sql.profiles.<env>.schemas`; every schema but the server's own when it
+ * names none), by its type, schema, name, the statements that create it as
+ * the server prints them, and its comment. The history schema is left out,
+ * so recording a run does not move the digest, and so are chant's own
+ * working objects (a migration's new column, its receipts), which the reader
+ * skips.
+ *
+ * It is the same reader `chant sql plan` and the applier diff against, so a
+ * change the plan would see (a column added out of band, an index dropped, a
+ * default changed) is a new fingerprint, and an approval given before it
+ * does not carry over.
+ */
+import { createHash } from "node:crypto";
+/** Byte order, so the order never depends on the machine's locale. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Reads what the fingerprint covers, in a stable order. */
+export async function readPgCatalog(client, scope) {
+    const { readLiveSchema } = await import("@intentius/chant-lexicon-sql/postgres/live/catalog");
+    const schemas = scope.schemas?.filter((s) => s !== scope.historySchema);
+    const objects = await readLiveSchema(client, schemas ? { schemas } : {});
+    return objects
+        .filter((o) => o.schema !== scope.historySchema && !(o.type === "Postgres::Schema" && o.name === scope.historySchema))
+        .map((o) => ({ type: o.type, schema: o.schema ?? "", name: o.name, statement: o.statement, comment: o.comment ?? "" }))
+        .sort((a, b) => cmp(a.type, b.type) || cmp(a.schema, b.schema) || cmp(a.name, b.name));
+}
+/** `sha256:<hex>` over the catalog's canonical JSON. */
+export function pgCatalogFingerprint(entries) {
+    const canonical = entries.map((e) => [e.type, e.schema, e.name, e.statement, e.comment]);
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex")}`;
+}
+//# sourceMappingURL=catalog.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../src/versioned/postgres/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBzC,sEAAsE;AACtE,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3E,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAgB,EAAE,KAAkB;IACtE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,oDAAoD,CAAC,CAAC;IAC9F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAA8C,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjH,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,kBAAkB,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC;SACrH,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC;SACtH,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,oBAAoB,CAAC,OAAkC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACzF,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAClG,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * 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 (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 type { PostgresEndpoint } from "@intentius/chant-lexicon-sql/postgres/live/client";
+import { type Environment, type Project } from "../../project.js";
+import { PostgresHistoryStore, type PgLockConnection } from "../../history/postgres/index.js";
+import type { VersionedDriver } from "../driver.js";
+import { type PgTimeouts } from "./executor.js";
+/** Opens a connection to the server: chant's `connectPostgres`, or a fake in the tests. */
+export type PgConnect = (endpoint: PostgresEndpoint, applicationName: string) => Promise<PgLockConnection>;
+export interface PgSettings {
+    historySchema: string;
+    timeouts: PgTimeouts;
+    lockRetries: number;
+}
+export declare function pgSettings(target: {
+    timeouts?: Partial<PgTimeouts>;
+}, env?: NodeJS.ProcessEnv, historySchema?: string): PgSettings;
+/** A connection opened on its first query, so a verb that reads nothing opens none. */
+export declare class LazyConnection implements PgLockConnection {
+    private readonly open;
+    private conn;
+    constructor(open: () => Promise<PgLockConnection>);
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    end(): Promise<void>;
+}
+/** Everything the versioned verbs need about one Postgres environment. */
+export interface PostgresEnv {
+    endpoint: PostgresEndpoint;
+    /** `sql.profiles.<env>.schemas`. */
+    schemas: string[] | undefined;
+    defaultSchema: string;
+    settings: PgSettings;
+    client: LazyConnection;
+    store: PostgresHistoryStore;
+    driver: VersionedDriver;
+}
+/** Binds `env`'s Postgres server (`sql.profiles.<env>`) and its history. Connects on first use. */
+export declare function openPostgres(project: Project, env: Environment, processEnv?: NodeJS.ProcessEnv, historySchema?: string, connect?: PgConnect): Promise<PostgresEnv>;
+export interface PostgresDriverInput {
+    client: LazyConnection;
+    /** Opens the lock's own connection. */
+    connect: () => Promise<PgLockConnection>;
+    settings: PgSettings;
+    schemas: string[] | undefined;
+    store: PostgresHistoryStore;
+    sleep?: (ms: number) => Promise<void>;
+    retryBaseMs?: number;
+}
+export declare function postgresDriver(input: PostgresDriverInput): VersionedDriver;

package/dist/versioned/postgres/driver.js

@@ -0,0 +1,113 @@
+/**
+ * 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 (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, PostgresHistoryStore } from "../../history/postgres/index.js";
+import { pgCatalogFingerprint, readPgCatalog } from "./catalog.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() {
+            return pgCatalogFingerprint(await readPgCatalog(client, { schemas: input.schemas, historySchema: settings.historySchema }));
+        },
+        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>;