@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/history/lock.js

@@ -0,0 +1,224 @@
+/**
+ * One apply at a time per environment.
+ *
+ * ## Keeper: a KeeperMap row
+ *
+ * The lock is a row in `<history database>.lock`, a `KeeperMap` table, so
+ * it lives in Keeper. Inserted with `keeper_map_strict_mode = 1`, an insert
+ * of a key that is there already fails ("Node exists") instead of
+ * overwriting it: create-if-absent, which is a lock. Every runner, on any
+ * host, sees the same row, because every host's `lock` table names the same
+ * Keeper path. It was picked over the other routes ClickHouse SQL offers:
+ *
+ * - an insert into a Replicated table that deduplicates: the losing insert is
+ *   dropped silently, inside a time window, so the loser cannot tell it lost
+ *   without reading back, and a later insert is not refused at all;
+ * - `INSERT INTO system.zookeeper`: no `DELETE`, so a lock could never be
+ *   released or expired from SQL.
+ *
+ * The row names its owner and an expiry. A runner that holds it extends the
+ * expiry while it works (a heartbeat every third of the TTL) and deletes the
+ * row when done. A runner that finds an expired row deletes that row (by its
+ * owner, so it never deletes a newer one) and inserts its own; two runners
+ * racing for an expired lock both delete, and only one insert succeeds. A
+ * heartbeat that finds the row gone or someone else's stops the apply
+ * before its next statement.
+ *
+ * KeeperMap needs Keeper and the server setting `keeper_map_path_prefix`.
+ *
+ * ## No Keeper: a local lock file
+ *
+ * A single node with no Keeper (or no `keeper_map_path_prefix`) gets a lock
+ * file under the system temp directory instead, created exclusively, with
+ * the same owner and expiry. It serializes applies from one machine only, and
+ * the run says so: cross-runner locking needs Keeper. A cluster, a
+ * Replicated database or Cloud never fall back: they refuse without the
+ * KeeperMap lock.
+ *
+ * ## Clearing a lock by hand
+ *
+ * A dead runner's lock expires after its TTL (`YODEL_LOCK_TTL`, seconds,
+ * default 900). To clear it sooner, when you know no apply is running:
+ *
+ *   Keeper: ALTER TABLE <history database>.lock DELETE WHERE name = 'apply'
+ *   local:  rm the lock file the refusal names
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { YodelError } from "../project.js";
+import { serverMessage } from "./client.js";
+import { databaseDdl, ident, literal, LOCK_TABLE, lockTableDdl } from "./ddl.js";
+import { describeTopology } from "./topology.js";
+/** Exit code: another apply holds the lock. */
+export const LOCKED = 5;
+/** The lock row's key: one apply lock per history database. */
+export const LOCK_NAME = "apply";
+/** Default lock TTL. */
+export const DEFAULT_LOCK_TTL_MS = 15 * 60 * 1000;
+export class LockHeldError extends YodelError {
+    holder;
+    expiresAt;
+    where;
+    clear;
+    constructor(holder, expiresAt, where, clear) {
+        super(`another apply holds the lock (${where}): owner ${holder}, until ${expiresAt} UTC. Wait for it, or once you know it is not running, clear it with: ${clear}`, LOCKED);
+        this.holder = holder;
+        this.expiresAt = expiresAt;
+        this.where = where;
+        this.clear = clear;
+        this.name = "LockHeldError";
+    }
+}
+export class LockLostError extends YodelError {
+    constructor(where) {
+        super(`the apply lock (${where}) is no longer held by this run (it expired and another run took it); stopped before the next statement`, LOCKED);
+        this.name = "LockLostError";
+    }
+}
+/** A lock owner: who, plus a random part so two runs by the same user never share one. */
+export const lockOwner = (holder) => `${holder}#${String(process.pid)}-${randomUUID().slice(0, 8)}`;
+const isNodeExists = (e) => /Node exists|already exists/i.test(serverMessage(e));
+const keeperMapUnavailable = (e) => /keeper_map_path_prefix|ZooKeeper|Keeper is not|KEEPER_EXCEPTION.*(not configured|connection)|No such engine|UNKNOWN_STORAGE/i.test(serverMessage(e));
+const STRICT = { keeper_map_strict_mode: "1", async_insert: "0" };
+/** Acquires the environment's apply lock, or throws {@link LockHeldError}. */
+export async function acquireLock(port, options) {
+    const ttlMs = options.ttlMs ?? DEFAULT_LOCK_TTL_MS;
+    await port.query(databaseDdl(options));
+    try {
+        await port.query(lockTableDdl(options));
+    }
+    catch (e) {
+        if (!keeperMapUnavailable(e))
+            throw e;
+        const why = (serverMessage(e).split("\n")[0] ?? "").replace(/^Code: \d+\. DB::Exception: /, "").replace(/\s*\([A-Z_]+\)\s*\(version [^)]*\)\s*$/, "");
+        if (options.topology.kind !== "single") {
+            throw new YodelError(`topology ${describeTopology(options.topology)} needs the Keeper lock (a KeeperMap table), and the server cannot make one: ${why}. ` +
+                `Configure Keeper and keeper_map_path_prefix on the server.`);
+        }
+        return localLock(options, ttlMs, `no KeeperMap on this server (${why}); the lock is a file on this machine, so cross-runner locking needs Keeper (and keeper_map_path_prefix)`);
+    }
+    return keeperLock(port, options, ttlMs);
+}
+async function keeperLock(port, options, ttlMs) {
+    const table = `${ident(options.database)}.${LOCK_TABLE}`;
+    const owner = lockOwner(options.holder);
+    const where = `KeeperMap ${options.database}.${LOCK_TABLE}`;
+    const clear = `ALTER TABLE ${table} DELETE WHERE name = '${LOCK_NAME}'`;
+    const until = `now64(3) + toIntervalMillisecond(${String(ttlMs)})`;
+    const read = async () => (await port.query(
+    // Not aliased as expires_at: an alias shadows the column in ClickHouse, and the comparison would read the string.
+    `SELECT owner, toString(expires_at) AS until, expires_at < now64(3) AS expired FROM ${table} WHERE name = ${literal(LOCK_NAME)}`))[0];
+    for (let attempt = 0;; attempt++) {
+        try {
+            await port.query(`INSERT INTO ${table} (name, owner, acquired_at, expires_at) SELECT ${literal(LOCK_NAME)}, ${literal(owner)}, now64(3), ${until}`, { settings: STRICT });
+            break;
+        }
+        catch (e) {
+            if (!isNodeExists(e))
+                throw e;
+            const held = await read();
+            if (held && Number(held.expired) !== 1)
+                throw new LockHeldError(held.owner, held.until, where, clear);
+            if (attempt >= 3)
+                throw new LockHeldError(held?.owner ?? "(unknown)", held?.until ?? "(unknown)", where, clear);
+            // Expired (or released between the insert and the read): delete that owner's row, never a newer one, and try again.
+            if (held)
+                await port.query(`ALTER TABLE ${table} DELETE WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(held.owner)}`, { settings: STRICT });
+        }
+    }
+    return {
+        kind: "keeper",
+        owner,
+        where,
+        async heartbeat() {
+            await port.query(`ALTER TABLE ${table} UPDATE expires_at = ${until} WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(owner)}`, { settings: STRICT });
+            const held = await read();
+            if (held?.owner !== owner)
+                throw new LockLostError(where);
+        },
+        async release() {
+            await port.query(`ALTER TABLE ${table} DELETE WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(owner)}`, { settings: STRICT });
+        },
+    };
+}
+/** The local lock's file for a server and history database. */
+export function localLockPath(options) {
+    const key = createHash("sha256").update(`${options.serverKey}\n${options.database}`).digest("hex").slice(0, 16);
+    return join(options.localDir ?? join(tmpdir(), "yodel-locks"), `${options.database}-${key}.lock`);
+}
+function readLockFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function localLock(options, ttlMs, notice) {
+    const path = localLockPath(options);
+    mkdirSync(join(path, ".."), { recursive: true });
+    const owner = lockOwner(options.holder);
+    const where = `local lock file ${path}`;
+    const body = () => JSON.stringify({ owner, acquiredAt: new Date().toISOString(), expiresAt: new Date(Date.now() + ttlMs).toISOString() });
+    for (let attempt = 0;; attempt++) {
+        try {
+            writeFileSync(path, body(), { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const held = readLockFile(path);
+            const expired = !held || Date.parse(held.expiresAt) < Date.now();
+            if (!expired || attempt >= 3)
+                throw new LockHeldError(held?.owner ?? "(unreadable)", held?.expiresAt ?? "(unknown)", where, `rm ${path}`);
+            rmSync(path, { force: true });
+        }
+    }
+    return {
+        kind: "local",
+        owner,
+        where,
+        notice,
+        heartbeat() {
+            if (readLockFile(path)?.owner !== owner)
+                return Promise.reject(new LockLostError(where));
+            writeFileSync(path, body());
+            return Promise.resolve();
+        },
+        release() {
+            if (readLockFile(path)?.owner === owner)
+                rmSync(path, { force: true });
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Runs `body` holding the lock: a heartbeat every third of the TTL while it
+ * runs, the lock released after, whatever happens. `beat` lets the body
+ * extend the lock (and learn it was lost) between statements.
+ */
+export async function withLock(lock, ttlMs, body) {
+    let lost;
+    const timer = setInterval(() => {
+        lock.heartbeat().catch((e) => {
+            lost ??= e;
+        });
+    }, Math.max(1000, Math.floor(ttlMs / 3)));
+    timer.unref();
+    const beat = async () => {
+        if (lost !== undefined)
+            throw lost instanceof Error ? lost : new LockLostError(lock.where);
+        await lock.heartbeat();
+    };
+    try {
+        return await body(beat);
+    }
+    finally {
+        clearInterval(timer);
+        await lock.release().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/history/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/history/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAuB,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAwB,MAAM,eAAe,CAAC;AAEvE,+CAA+C;AAC/C,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC;AAExB,+DAA+D;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AAEjC,wBAAwB;AACxB,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAgBlD,MAAM,OAAO,aAAc,SAAQ,UAAU;IAEhC;IACA;IACA;IACA;IAJX,YACW,MAAc,EACd,SAAiB,EACjB,KAAa,EACb,KAAa;QAEtB,KAAK,CAAC,iCAAiC,KAAK,YAAY,MAAM,WAAW,SAAS,yEAAyE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;QALnK,WAAM,GAAN,MAAM,CAAQ;QACd,cAAS,GAAT,SAAS,CAAQ;QACjB,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAAQ;QAGtB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,UAAU;IAC3C,YAAY,KAAa;QACvB,KAAK,CAAC,mBAAmB,KAAK,yGAAyG,EAAE,MAAM,CAAC,CAAC;QACjJ,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAcD,0FAA0F;AAC1F,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AAEpH,MAAM,YAAY,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1F,MAAM,oBAAoB,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,8HAA8H,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnM,MAAM,MAAM,GAAG,EAAE,sBAAsB,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC;AAElE,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAoB,EAAE,OAAoB;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IACnD,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAAE,MAAM,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,wCAAwC,EAAE,EAAE,CAAC,CAAC;QACtJ,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,UAAU,CAClB,YAAY,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,+EAA+E,GAAG,IAAI;gBAClI,4DAA4D,CAC/D,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,gCAAgC,GAAG,0GAA0G,CAAC,CAAC;IAClL,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAoB,EAAE,OAAoB,EAAE,KAAa;IACjF,MAAM,KAAK,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,UAAU,EAAE,CAAC;IACzD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,aAAa,OAAO,CAAC,QAAQ,IAAI,UAAU,EAAE,CAAC;IAC5D,MAAM,KAAK,GAAG,eAAe,KAAK,yBAAyB,SAAS,GAAG,CAAC;IACxE,MAAM,KAAK,GAAG,oCAAoC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;IACnE,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CACtB,CAAC,MAAM,IAAI,CAAC,KAAK;IACf,kHAAkH;IAClH,sFAAsF,KAAK,iBAAiB,OAAO,CAAC,SAAS,CAAC,EAAE,CACjI,CAAC,CAAC,CAAC,CAAC,CAAC;IAER,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,KAAK,kDAAkD,OAAO,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,eAAe,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1K,MAAM;QACR,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;gBAAE,MAAM,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;YAC1B,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YACtG,IAAI,OAAO,IAAI,CAAC;gBAAE,MAAM,IAAI,aAAa,CAAC,IAAI,EAAE,KAAK,IAAI,WAAW,EAAE,IAAI,EAAE,KAAK,IAAI,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAChH,oHAAoH;YACpH,IAAI,IAAI;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,KAAK,wBAAwB,OAAO,CAAC,SAAS,CAAC,gBAAgB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QACxJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK;QACL,KAAK;QACL,KAAK,CAAC,SAAS;YACb,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,KAAK,wBAAwB,KAAK,iBAAiB,OAAO,CAAC,SAAS,CAAC,gBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7J,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;YAC1B,IAAI,IAAI,EAAE,KAAK,KAAK,KAAK;gBAAE,MAAM,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;QAC5D,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,KAAK,wBAAwB,OAAO,CAAC,SAAS,CAAC,gBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QACzI,CAAC;KACF,CAAC;AACJ,CAAC;AAQD,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAC,OAAiE;IAC7F,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChH,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,OAAO,CAAC,CAAC;AACpG,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAa,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,OAAoB,EAAE,KAAa,EAAE,MAAc;IACpE,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,mBAAmB,IAAI,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,WAAW,EAAE,EAAqB,CAAC,CAAC;IAErK,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM;QACR,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,CAAC,CAAC;YAC5D,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,OAAO,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjE,IAAI,CAAC,OAAO,IAAI,OAAO,IAAI,CAAC;gBAAE,MAAM,IAAI,aAAa,CAAC,IAAI,EAAE,KAAK,IAAI,cAAc,EAAE,IAAI,EAAE,SAAS,IAAI,WAAW,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;YAC1I,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK;QACL,KAAK;QACL,MAAM;QACN,SAAS;YACP,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,KAAK;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;YACzF,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO;YACL,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,KAAK;gBAAE,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACvE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,IAAU,EAAE,KAAa,EAAE,IAA+C;IAC1G,IAAI,IAAa,CAAC;IAClB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;YACpC,IAAI,KAAK,CAAC,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;QACtB,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3F,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC,CAAC;IACF,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACrB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/history/postgres/ddl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The Postgres history's DDL: `<schema>.history` in a schema of its own
+ * (default `yodeler`, the environment's history database setting), the same
+ * columns as the ClickHouse table (`../ddl.ts`), so a row reads the same in
+ * both and `deriveState` adds them up the same way.
+ *
+ * `seq` is the primary key: two runs can never write the same one (a run
+ * takes it under the advisory lock, one more than the highest), and the key
+ * says so if one ever tried. Rows are only ever inserted.
+ */
+/** A Postgres identifier, double-quoted. */
+export declare const pgIdent: (name: string) => string;
+/** A Postgres string literal (standard_conforming_strings, the default since 9.1). */
+export declare const pgLiteral: (value: string) => string;
+/** The history table's columns, in the order {@link HISTORY_COLUMNS} (ClickHouse) has them. */
+export declare const PG_HISTORY_COLUMNS: readonly (readonly [name: string, type: string])[];
+/** The columns a row write names: all but `recorded_at`, which is the server's. */
+export declare const PG_WRITTEN_COLUMNS: string[];
+/** `<schema>.history`, quoted. */
+export declare const pgHistoryTable: (schema: string) => string;
+/** Every statement that makes the history ready, in order: the schema, the table, its comment. */
+export declare function pgHistoryDdl(schema: string): string[];

package/dist/history/postgres/ddl.js

@@ -0,0 +1,47 @@
+/**
+ * The Postgres history's DDL: `<schema>.history` in a schema of its own
+ * (default `yodeler`, the environment's history database setting), the same
+ * columns as the ClickHouse table (`../ddl.ts`), so a row reads the same in
+ * both and `deriveState` adds them up the same way.
+ *
+ * `seq` is the primary key: two runs can never write the same one (a run
+ * takes it under the advisory lock, one more than the highest), and the key
+ * says so if one ever tried. Rows are only ever inserted.
+ */
+import { HISTORY_TABLE } from "../ddl.js";
+/** A Postgres identifier, double-quoted. */
+export const pgIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+/** A Postgres string literal (standard_conforming_strings, the default since 9.1). */
+export const pgLiteral = (value) => `'${value.replace(/'/g, "''")}'`;
+/** The history table's columns, in the order {@link HISTORY_COLUMNS} (ClickHouse) has them. */
+export const PG_HISTORY_COLUMNS = [
+    ["seq", "bigint NOT NULL PRIMARY KEY"],
+    ["run_id", "text NOT NULL"],
+    ["kind", "text NOT NULL CHECK (kind IN ('migration', 'statement', 'step'))"],
+    ["migration_id", "text NOT NULL"],
+    ["parent", "text NOT NULL DEFAULT ''"],
+    ["checksum", "text NOT NULL DEFAULT ''"],
+    ["statement_index", "integer NOT NULL"],
+    ["statement_sha", "text NOT NULL DEFAULT ''"],
+    ["status", "text NOT NULL CHECK (status IN ('started', 'succeeded', 'failed'))"],
+    ["error", "text NOT NULL DEFAULT ''"],
+    ["applied_by", "text NOT NULL DEFAULT ''"],
+    ["plan_digest", "text NOT NULL DEFAULT ''"],
+    ["silences", "text NOT NULL DEFAULT '[]'"],
+    ["note", "text NOT NULL DEFAULT ''"],
+    ["recorded_at", "timestamptz NOT NULL DEFAULT pg_catalog.clock_timestamp()"],
+];
+/** The columns a row write names: all but `recorded_at`, which is the server's. */
+export const PG_WRITTEN_COLUMNS = PG_HISTORY_COLUMNS.map(([name]) => name).filter((n) => n !== "recorded_at");
+/** `<schema>.history`, quoted. */
+export const pgHistoryTable = (schema) => `${pgIdent(schema)}.${pgIdent(HISTORY_TABLE)}`;
+/** Every statement that makes the history ready, in order: the schema, the table, its comment. */
+export function pgHistoryDdl(schema) {
+    const columns = PG_HISTORY_COLUMNS.map(([name, type]) => `  ${name} ${type}`).join(",\n");
+    return [
+        `CREATE SCHEMA IF NOT EXISTS ${pgIdent(schema)}`,
+        `CREATE TABLE IF NOT EXISTS ${pgHistoryTable(schema)} (\n${columns}\n)`,
+        `COMMENT ON TABLE ${pgHistoryTable(schema)} IS 'yodel migration history: append-only, one row per migration, statement and step event'`,
+    ];
+}
+//# sourceMappingURL=ddl.js.map

package/dist/history/postgres/ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","sourceRoot":"","sources":["../../../src/history/postgres/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,4CAA4C;AAC5C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAEjF,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAErF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,kBAAkB,GAAuD;IACpF,CAAC,KAAK,EAAE,6BAA6B,CAAC;IACtC,CAAC,QAAQ,EAAE,eAAe,CAAC;IAC3B,CAAC,MAAM,EAAE,kEAAkE,CAAC;IAC5E,CAAC,cAAc,EAAE,eAAe,CAAC;IACjC,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IACtC,CAAC,UAAU,EAAE,0BAA0B,CAAC;IACxC,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IACvC,CAAC,eAAe,EAAE,0BAA0B,CAAC;IAC7C,CAAC,QAAQ,EAAE,oEAAoE,CAAC;IAChF,CAAC,OAAO,EAAE,0BAA0B,CAAC;IACrC,CAAC,YAAY,EAAE,0BAA0B,CAAC;IAC1C,CAAC,aAAa,EAAE,0BAA0B,CAAC;IAC3C,CAAC,UAAU,EAAE,4BAA4B,CAAC;IAC1C,CAAC,MAAM,EAAE,0BAA0B,CAAC;IACpC,CAAC,aAAa,EAAE,2DAA2D,CAAC;CAC7E,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC;AAE9G,kCAAkC;AAClC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;AAEzG,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1F,OAAO;QACL,+BAA+B,OAAO,CAAC,MAAM,CAAC,EAAE;QAChD,8BAA8B,cAAc,CAAC,MAAM,CAAC,OAAO,OAAO,KAAK;QACvE,oBAAoB,cAAc,CAAC,MAAM,CAAC,6FAA6F;KACxI,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * The Postgres history (#13): `<schema>.history` (default `yodeler.history`),
+ * the same rows as ClickHouse's, and the session advisory lock.
+ *
+ *   pgHistoryDdl(schema)                     CREATE SCHEMA / TABLE
+ *   new PostgresHistoryStore(client, {schema}) exists(), ensure(), rows(), state(), append(rows)
+ *   acquireAdvisoryLock(conn, {schema, holder}) the apply lock, on a connection of its own
+ *   lockKeys(schema)                          the lock's two keys
+ */
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./store.js";

package/dist/history/postgres/index.js

@@ -0,0 +1,13 @@
+/**
+ * The Postgres history (#13): `<schema>.history` (default `yodeler.history`),
+ * the same rows as ClickHouse's, and the session advisory lock.
+ *
+ *   pgHistoryDdl(schema)                     CREATE SCHEMA / TABLE
+ *   new PostgresHistoryStore(client, {schema}) exists(), ensure(), rows(), state(), append(rows)
+ *   acquireAdvisoryLock(conn, {schema, holder}) the apply lock, on a connection of its own
+ *   lockKeys(schema)                          the lock's two keys
+ */
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./store.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/history/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/history/postgres/lock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One apply at a time per environment, on Postgres: a session advisory lock.
+ *
+ * `pg_try_advisory_lock(<yodel>, <history schema>)` on a connection of its
+ * own, opened for the lock and held for the whole apply. The two keys are
+ * fixed: the first is yodel's ({@link LOCK_CLASS}), the second a hash of the
+ * history schema's name ({@link lockKeys}), so every runner of the same
+ * environment asks for the same lock, and two environments with their own
+ * history schemas in one database do not share one. A session lock is
+ * Postgres's own: it is released when the session ends, however it ends
+ * (the runner exits, crashes, or its connection drops), so it needs no
+ * expiry, and a dead runner never leaves one behind.
+ *
+ * The statements run on another connection (the work connection), so the
+ * lock's connection is never inside a transaction a statement rolls back.
+ *
+ * A runner that finds the lock taken refuses with exit 5, as on ClickHouse,
+ * naming the session that holds it (its pid, its `application_name`, which
+ * says who, and since when). The heartbeat checks that the lock's session
+ * still holds it; a dropped connection stops the apply before its next
+ * statement.
+ *
+ * Clearing it by hand, when you know the holder is stuck: end that session,
+ * `SELECT pg_terminate_backend(<pid>)`.
+ */
+import { type Lock } from "../lock.js";
+import type { PgClient } from "./store.js";
+/** The first key of every yodel lock: "YODL" as an int4. */
+export declare const LOCK_CLASS = 1498367052;
+/** The lock's two int4 keys for a history schema. Both non-negative, so `pg_locks.objid` (an oid) reads them back as they are. */
+export declare function lockKeys(schema: string): [number, number];
+/** A connection the lock holds for itself. */
+export interface PgLockConnection extends PgClient {
+    end(): Promise<void>;
+}
+export interface PgLockOptions {
+    /** The history schema: the lock's second key. */
+    schema: string;
+    /** Who holds it, for the refusal another runner sees. */
+    holder: string;
+}
+/**
+ * Takes the advisory lock on `conn`, a connection opened for it, or throws
+ * {@link LockHeldError} (exit 5). On a refusal the connection is closed.
+ * The lock is released with the returned {@link Lock}'s `release`, which
+ * also closes the connection.
+ */
+export declare function acquireAdvisoryLock(conn: PgLockConnection, options: PgLockOptions): Promise<Lock>;

package/dist/history/postgres/lock.js

@@ -0,0 +1,95 @@
+/**
+ * One apply at a time per environment, on Postgres: a session advisory lock.
+ *
+ * `pg_try_advisory_lock(<yodel>, <history schema>)` on a connection of its
+ * own, opened for the lock and held for the whole apply. The two keys are
+ * fixed: the first is yodel's ({@link LOCK_CLASS}), the second a hash of the
+ * history schema's name ({@link lockKeys}), so every runner of the same
+ * environment asks for the same lock, and two environments with their own
+ * history schemas in one database do not share one. A session lock is
+ * Postgres's own: it is released when the session ends, however it ends
+ * (the runner exits, crashes, or its connection drops), so it needs no
+ * expiry, and a dead runner never leaves one behind.
+ *
+ * The statements run on another connection (the work connection), so the
+ * lock's connection is never inside a transaction a statement rolls back.
+ *
+ * A runner that finds the lock taken refuses with exit 5, as on ClickHouse,
+ * naming the session that holds it (its pid, its `application_name`, which
+ * says who, and since when). The heartbeat checks that the lock's session
+ * still holds it; a dropped connection stops the apply before its next
+ * statement.
+ *
+ * Clearing it by hand, when you know the holder is stuck: end that session,
+ * `SELECT pg_terminate_backend(<pid>)`.
+ */
+import { createHash } from "node:crypto";
+import { lockOwner, LockHeldError, LockLostError } from "../lock.js";
+/** The first key of every yodel lock: "YODL" as an int4. */
+export const LOCK_CLASS = 0x594f444c;
+/** The lock's two int4 keys for a history schema. Both non-negative, so `pg_locks.objid` (an oid) reads them back as they are. */
+export function lockKeys(schema) {
+    const digest = createHash("sha256").update(`yodel apply lock\n${schema}`, "utf8").digest();
+    return [LOCK_CLASS, digest.readUInt32BE(0) & 0x7fffffff];
+}
+/** `application_name` is 63 bytes at most; the lock's says it is yodel's and whose. */
+const applicationName = (owner) => `yodel apply ${owner}`.slice(0, 63);
+/**
+ * Takes the advisory lock on `conn`, a connection opened for it, or throws
+ * {@link LockHeldError} (exit 5). On a refusal the connection is closed.
+ * The lock is released with the returned {@link Lock}'s `release`, which
+ * also closes the connection.
+ */
+export async function acquireAdvisoryLock(conn, options) {
+    const [k1, k2] = lockKeys(options.schema);
+    const owner = lockOwner(options.holder);
+    const where = `Postgres advisory lock (${String(k1)}, ${String(k2)}) for history schema ${options.schema}`;
+    try {
+        await conn.query("SELECT pg_catalog.set_config('application_name', $1, false)", [applicationName(owner)]);
+        const [row] = await conn.query("SELECT pg_catalog.pg_try_advisory_lock($1::int4, $2::int4) AS ok", [k1, k2]);
+        if (row?.ok !== true) {
+            const [held] = await conn.query(`SELECT l.pid, a.application_name AS app, pg_catalog.to_char(a.backend_start AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS') AS since
+           FROM pg_catalog.pg_locks l LEFT JOIN pg_catalog.pg_stat_activity a ON a.pid = l.pid
+          WHERE l.locktype = 'advisory' AND l.granted AND l.classid = $1::oid AND l.objid = $2::oid AND l.objsubid = 2
+          LIMIT 1`, [k1, k2]);
+            const who = held ? `${held.app || "(no application_name)"}, pid ${String(held.pid)}` : "(another session)";
+            throw new LockHeldError(who, held?.since ?? "(unknown)", where, held ? `SELECT pg_terminate_backend(${String(held.pid)})` : "end the session that holds it");
+        }
+    }
+    catch (e) {
+        await conn.end().catch(() => undefined);
+        throw e;
+    }
+    let released = false;
+    return {
+        kind: "advisory",
+        owner,
+        where,
+        async heartbeat() {
+            if (released)
+                throw new LockLostError(where);
+            let holds;
+            try {
+                const [row] = await conn.query("SELECT count(*) AS n FROM pg_catalog.pg_locks WHERE locktype = 'advisory' AND granted AND pid = pg_catalog.pg_backend_pid() AND classid = $1::oid AND objid = $2::oid AND objsubid = 2", [k1, k2]);
+                holds = Number(row?.n ?? 0) > 0;
+            }
+            catch {
+                holds = false;
+            }
+            if (!holds)
+                throw new LockLostError(where);
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                await conn.query("SELECT pg_catalog.pg_advisory_unlock($1::int4, $2::int4)", [k1, k2]);
+            }
+            finally {
+                await conn.end().catch(() => undefined);
+            }
+        },
+    };
+}
+//# sourceMappingURL=lock.js.map

package/dist/history/postgres/lock.js.map

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

package/dist/history/postgres/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reading and appending the Postgres history table. Nothing here updates or
+ * deletes a row.
+ *
+ * The store works on one connection, the apply's work connection, so a row
+ * appended while that connection has a transaction open commits or rolls
+ * back with it: that is how a statement and its `succeeded` row commit
+ * together (`../../versioned/postgres/executor.ts`).
+ */
+import { type HistoryRow, type HistoryState } from "../rows.js";
+import { type HistoryStoreLike } from "../store.js";
+/** What the history needs from a Postgres connection: chant's `PostgresClient`. */
+export interface PgClient {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+}
+export interface PgHistoryLocation {
+    /** The schema the history table lives in. */
+    schema: string;
+}
+export declare class PostgresHistoryStore implements HistoryStoreLike {
+    readonly client: PgClient;
+    readonly location: PgHistoryLocation;
+    constructor(client: PgClient, location: PgHistoryLocation);
+    get table(): string;
+    /** Whether the history table is there. A history that was never made has no rows. */
+    exists(): Promise<boolean>;
+    /** Creates the schema and table when they are not there. */
+    ensure(): Promise<void>;
+    /** Every row, in seq order. Postgres reads are consistent, so the `sync` option the ClickHouse store takes changes nothing here. */
+    rows(): Promise<HistoryRow[]>;
+    state(): Promise<HistoryState>;
+    /** Appends rows, as written; `recorded_at` is the server's. On the store's connection, so inside its open transaction, if any. */
+    append(rows: readonly HistoryRow[]): Promise<void>;
+}
+/** The parameterized `INSERT` of `rows`. */
+export declare function insertRows(schema: string, rows: readonly HistoryRow[]): {
+    sql: string;
+    params: unknown[];
+};

package/dist/history/postgres/store.js

@@ -0,0 +1,68 @@
+/**
+ * Reading and appending the Postgres history table. Nothing here updates or
+ * deletes a row.
+ *
+ * The store works on one connection, the apply's work connection, so a row
+ * appended while that connection has a transaction open commits or rolls
+ * back with it: that is how a statement and its `succeeded` row commit
+ * together (`../../versioned/postgres/executor.ts`).
+ */
+import { deriveState } from "../rows.js";
+import { fromRaw } from "../store.js";
+import { HISTORY_TABLE } from "../ddl.js";
+import { pgHistoryDdl, pgHistoryTable, PG_HISTORY_COLUMNS, PG_WRITTEN_COLUMNS } from "./ddl.js";
+/** The history's rows read back, `recorded_at` in the ClickHouse table's form (`YYYY-MM-DD hh:mm:ss.ffffff`, UTC). */
+const SELECT = PG_HISTORY_COLUMNS.map(([name]) => name === "recorded_at" ? `pg_catalog.to_char(recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.US') AS recorded_at` : name === "seq" ? "seq::text AS seq" : name).join(", ");
+export class PostgresHistoryStore {
+    client;
+    location;
+    constructor(client, location) {
+        this.client = client;
+        this.location = location;
+    }
+    get table() {
+        return pgHistoryTable(this.location.schema);
+    }
+    /** Whether the history table is there. A history that was never made has no rows. */
+    async exists() {
+        const [row] = await this.client.query("SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'r') AS present", [this.location.schema, HISTORY_TABLE]);
+        return row?.present === true;
+    }
+    /** Creates the schema and table when they are not there. */
+    async ensure() {
+        if (await this.exists())
+            return;
+        for (const sql of pgHistoryDdl(this.location.schema))
+            await this.client.query(sql);
+    }
+    /** Every row, in seq order. Postgres reads are consistent, so the `sync` option the ClickHouse store takes changes nothing here. */
+    async rows() {
+        if (!(await this.exists()))
+            return [];
+        const raw = await this.client.query(`SELECT ${SELECT} FROM ${this.table} ORDER BY seq`);
+        return raw.map(fromRaw);
+    }
+    async state() {
+        return deriveState(await this.rows());
+    }
+    /** Appends rows, as written; `recorded_at` is the server's. On the store's connection, so inside its open transaction, if any. */
+    async append(rows) {
+        if (rows.length === 0)
+            return;
+        const { sql, params } = insertRows(this.location.schema, rows);
+        await this.client.query(sql, params);
+    }
+}
+/** The parameterized `INSERT` of `rows`. */
+export function insertRows(schema, rows) {
+    const params = [];
+    const tuples = rows.map((r) => {
+        const values = PG_WRITTEN_COLUMNS.map((c) => {
+            params.push(c === "seq" ? String(r.seq) : r[c]);
+            return `$${String(params.length)}`;
+        });
+        return `(${values.join(", ")})`;
+    });
+    return { sql: `INSERT INTO ${pgHistoryTable(schema)} (${PG_WRITTEN_COLUMNS.join(", ")}) VALUES ${tuples.join(", ")}`, params };
+}
+//# sourceMappingURL=store.js.map

package/dist/history/postgres/store.js.map

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