@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/history/store.js

@@ -0,0 +1,134 @@
+/**
+ * Reading and appending the history table. Nothing here updates or deletes
+ * a row.
+ */
+import { hostname, userInfo } from "node:os";
+import { randomUUID } from "node:crypto";
+import { HISTORY_COLUMNS, HISTORY_TABLE, historyDdl, ident, literal } from "./ddl.js";
+import { replicates } from "./topology.js";
+import { deriveState } from "./rows.js";
+/** Settings every history write carries: synchronous, and never deduplicated away on a Replicated engine. */
+const WRITE_SETTINGS = { async_insert: "0", insert_deduplicate: "0" };
+/** Who is applying: the CI actor or the user, at this host. */
+export function appliedBy(env = process.env) {
+    let user = env.GITHUB_ACTOR ?? env.GITLAB_USER_LOGIN ?? env.USER;
+    if (!user) {
+        try {
+            user = userInfo().username;
+        }
+        catch {
+            user = "unknown";
+        }
+    }
+    return `${user}@${hostname()}`;
+}
+const columnNames = HISTORY_COLUMNS.map(([name]) => name);
+/** A row as a server returns it (strings or numbers), as a {@link HistoryRow}. */
+export function fromRaw(r) {
+    const s = (k) => {
+        const v = r[k];
+        return typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : "";
+    };
+    return {
+        seq: Number(r.seq),
+        run_id: s("run_id"),
+        kind: s("kind") === "statement" || s("kind") === "step" ? s("kind") : "migration",
+        migration_id: s("migration_id"),
+        parent: s("parent"),
+        checksum: s("checksum"),
+        statement_index: Number(r.statement_index),
+        statement_sha: s("statement_sha"),
+        status: (["started", "succeeded", "failed"].includes(s("status")) ? s("status") : "started"),
+        error: s("error"),
+        applied_by: s("applied_by"),
+        plan_digest: s("plan_digest"),
+        silences: s("silences") || "[]",
+        note: s("note"),
+        recorded_at: s("recorded_at"),
+    };
+}
+export class HistoryStore {
+    port;
+    location;
+    constructor(port, location) {
+        this.port = port;
+        this.location = location;
+    }
+    get table() {
+        return `${ident(this.location.database)}.${HISTORY_TABLE}`;
+    }
+    /** Whether the history table is there. A history that was never made has no rows. */
+    async exists() {
+        const rows = await this.port.query(`SELECT count() AS n FROM system.tables WHERE database = ${literal(this.location.database)} AND name = ${literal(HISTORY_TABLE)}`);
+        return Number(rows[0]?.n ?? 0) > 0;
+    }
+    /** Creates the database and table when they are not there. */
+    async ensure() {
+        for (const sql of historyDdl(this.location))
+            await this.port.query(sql);
+    }
+    /**
+     * Every row. On a cluster or a Replicated database the replica first
+     * catches up with the others (`SYSTEM SYNC REPLICA`), so a run reads what
+     * a run on another host wrote; on Cloud the read is sequentially
+     * consistent. `sync: false` skips that, for a status read that need not
+     * wait.
+     */
+    async rows(options = {}) {
+        if (!(await this.exists()))
+            return [];
+        const { topology } = this.location;
+        if (options.sync !== false && replicates(topology))
+            await this.port.query(`SYSTEM SYNC REPLICA ${this.table}`);
+        const settings = topology.kind === "cloud" && options.sync !== false ? { settings: { select_sequential_consistency: "1" } } : {};
+        const select = columnNames.map((c) => (c === "recorded_at" ? "toString(recorded_at) AS recorded_at" : c)).join(", ");
+        const raw = await this.port.query(`SELECT ${select} FROM ${this.table} ORDER BY seq`, settings);
+        return raw.map(fromRaw);
+    }
+    async state(options = {}) {
+        return deriveState(await this.rows(options));
+    }
+    /** Appends rows, as written; `recorded_at` is the server's. */
+    async append(rows) {
+        if (rows.length === 0)
+            return;
+        const body = rows
+            .map((r) => JSON.stringify({ ...r, recorded_at: undefined }))
+            .join("\n");
+        await this.port.query(`INSERT INTO ${this.table} FORMAT JSONEachRow\n${body}`, { settings: WRITE_SETTINGS });
+    }
+}
+export const newRunContext = (planDigest, env = process.env) => ({
+    runId: randomUUID(),
+    appliedBy: appliedBy(env),
+    planDigest,
+});
+/**
+ * Writes one run's rows, each with the next `seq`. Made under the lock from
+ * the history's highest seq, so seqs never collide across runs.
+ */
+export class HistoryRecorder {
+    store;
+    run;
+    next;
+    constructor(store, run, maxSeq) {
+        this.store = store;
+        this.run = run;
+        this.next = maxSeq + 1;
+    }
+    async record(row) {
+        const full = {
+            error: "",
+            note: "",
+            silences: "[]",
+            ...row,
+            seq: this.next++,
+            run_id: this.run.runId,
+            applied_by: this.run.appliedBy,
+            plan_digest: this.run.planDigest,
+        };
+        await this.store.append([full]);
+        return full;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/history/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/history/store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EAAE,UAAU,EAAwB,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,WAAW,EAAsC,MAAM,WAAW,CAAC;AAO5E,6GAA6G;AAC7G,MAAM,cAAc,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,CAAC;AAEtE,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5D,IAAI,IAAI,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,IAAI,CAAC;IACjE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC;YACH,IAAI,GAAG,QAAQ,EAAE,CAAC,QAAQ,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,IAAI,IAAI,QAAQ,EAAE,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAI1D,kFAAkF;AAClF,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,MAAM,CAAC,GAAG,CAAC,CAAS,EAAU,EAAE;QAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtG,CAAC,CAAC;IACF,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QAClB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC;QACnB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,MAAM,CAA0B,CAAC,CAAC,CAAC,WAAW;QAC3G,YAAY,EAAE,CAAC,CAAC,cAAc,CAAC;QAC/B,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC;QACnB,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1C,aAAa,EAAE,CAAC,CAAC,eAAe,CAAC;QACjC,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAyB;QACpH,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;QACjB,UAAU,EAAE,CAAC,CAAC,YAAY,CAAC;QAC3B,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC;QAC7B,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,IAAI;QAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC;KAC9B,CAAC;AACJ,CAAC;AAWD,MAAM,OAAO,YAAY;IAEZ;IACA;IAFX,YACW,IAAoB,EACpB,QAAyB;QADzB,SAAI,GAAJ,IAAI,CAAgB;QACpB,aAAQ,GAAR,QAAQ,CAAiB;IACjC,CAAC;IAEJ,IAAI,KAAK;QACP,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,aAAa,EAAE,CAAC;IAC7D,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAChC,2DAA2D,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,eAAe,OAAO,CAAC,aAAa,CAAC,EAAE,CAClI,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,8DAA8D;IAC9D,KAAK,CAAC,MAAM;QACV,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,UAA8B,EAAE;QACzC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/G,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,6BAA6B,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjI,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAS,UAAU,MAAM,SAAS,IAAI,CAAC,KAAK,eAAe,EAAE,QAAQ,CAAC,CAAC;QACxG,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,UAA8B,EAAE;QAC1C,OAAO,WAAW,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,MAAM,CAAC,IAA2B;QACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC9B,MAAM,IAAI,GAAG,IAAI;aACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;aAC5D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,KAAK,wBAAwB,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IAC/G,CAAC;CACF;AASD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,UAAkB,EAAE,MAAyB,OAAO,CAAC,GAAG,EAAc,EAAE,CAAC,CAAC;IACtG,KAAK,EAAE,UAAU,EAAE;IACnB,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC;IACzB,UAAU;CACX,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,OAAO,eAAe;IAIf;IACA;IAJH,IAAI,CAAS;IAErB,YACW,KAAuB,EACvB,GAAe,EACxB,MAAc;QAFL,UAAK,GAAL,KAAK,CAAkB;QACvB,QAAG,GAAH,GAAG,CAAY;QAGxB,IAAI,CAAC,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAiL;QAC5L,MAAM,IAAI,GAAe;YACvB,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,EAAE;YACR,QAAQ,EAAE,IAAI;YACd,GAAG,GAAG;YACN,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE;YAChB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK;YACtB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS;YAC9B,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU;SACjC,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/history/topology.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Where the history table lives, as far as its DDL cares: a single node, a
+ * cluster (`ON CLUSTER`), a `Replicated` database, or ClickHouse Cloud.
+ *
+ * The same four kinds as chant's ClickHouse topology, with the same string
+ * form (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`). Each environment names one in `yodel.config.ts` (#9, see
+ * `../config/settings.ts` for the fallbacks); the default is a single node.
+ */
+export type HistoryTopology = {
+    kind: "single";
+} | {
+    kind: "cluster";
+    /** The cluster's name in `remote_servers`, or a macro such as `{cluster}`. */
+    cluster: string;
+    /** The history table's Keeper path. Default {@link defaultReplicaPath}. */
+    replicaPath?: string;
+    /** Its replica name. Default {@link DEFAULT_HISTORY_REPLICA_NAME}. */
+    replicaName?: string;
+} | {
+    kind: "replicated";
+    /** A cluster to create the history's `Replicated` database on, when yodel creates it. */
+    cluster?: string;
+} | {
+    kind: "cloud";
+};
+export declare const SINGLE: HistoryTopology;
+/**
+ * A cluster's history table is one copy for the whole cluster, not one per
+ * shard: every runner, on any host, must read the same rows. So the Keeper
+ * path names no `{shard}`, and the replica name carries the shard as well as
+ * the replica, so replicas of different shards do not collide.
+ */
+export declare const defaultReplicaPath: (database: string, table: string) => string;
+export declare const DEFAULT_HISTORY_REPLICA_NAME = "{shard}-{replica}";
+/** A topology from its string form. */
+export declare function parseHistoryTopology(value: string): HistoryTopology;
+/** The string form of a topology, for messages. */
+export declare function describeTopology(t: HistoryTopology): string;
+/** Whether the history's tables replicate through Keeper, so a read on one host must first catch up with the others. */
+export declare const replicates: (t: HistoryTopology) => boolean;

package/dist/history/topology.js

@@ -0,0 +1,54 @@
+/**
+ * Where the history table lives, as far as its DDL cares: a single node, a
+ * cluster (`ON CLUSTER`), a `Replicated` database, or ClickHouse Cloud.
+ *
+ * The same four kinds as chant's ClickHouse topology, with the same string
+ * form (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`). Each environment names one in `yodel.config.ts` (#9, see
+ * `../config/settings.ts` for the fallbacks); the default is a single node.
+ */
+import { YodelError } from "../project.js";
+export const SINGLE = { kind: "single" };
+/**
+ * A cluster's history table is one copy for the whole cluster, not one per
+ * shard: every runner, on any host, must read the same rows. So the Keeper
+ * path names no `{shard}`, and the replica name carries the shard as well as
+ * the replica, so replicas of different shards do not collide.
+ */
+export const defaultReplicaPath = (database, table) => `/clickhouse/yodeler/${database}/${table}`;
+export const DEFAULT_HISTORY_REPLICA_NAME = "{shard}-{replica}";
+/** A topology from its string form. */
+export function parseHistoryTopology(value) {
+    const at = value.indexOf(":");
+    const kind = (at < 0 ? value : value.slice(0, at)).trim();
+    const arg = at < 0 ? undefined : value.slice(at + 1).trim();
+    switch (kind) {
+        case "single":
+        case "cloud":
+            if (arg !== undefined)
+                throw new YodelError(`topology ${kind} takes no argument: ${JSON.stringify(value)}`);
+            return { kind };
+        case "cluster":
+            if (!arg)
+                throw new YodelError(`topology cluster needs the cluster's name: cluster:<name>, got ${JSON.stringify(value)}`);
+            return { kind, cluster: arg };
+        case "replicated":
+            return arg ? { kind, cluster: arg } : { kind };
+        default:
+            throw new YodelError(`unknown topology ${JSON.stringify(value)}: expected single, cluster:<name>, replicated or cloud`);
+    }
+}
+/** The string form of a topology, for messages. */
+export function describeTopology(t) {
+    switch (t.kind) {
+        case "cluster":
+            return `cluster:${t.cluster}`;
+        case "replicated":
+            return t.cluster ? `replicated:${t.cluster}` : "replicated";
+        default:
+            return t.kind;
+    }
+}
+/** Whether the history's tables replicate through Keeper, so a read on one host must first catch up with the others. */
+export const replicates = (t) => t.kind === "cluster" || t.kind === "replicated";
+//# sourceMappingURL=topology.js.map

package/dist/history/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../src/history/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAoB3C,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAE,KAAa,EAAU,EAAE,CAAC,uBAAuB,QAAQ,IAAI,KAAK,EAAE,CAAC;AAC1H,MAAM,CAAC,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAEhE,uCAAuC;AACvC,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,YAAY,IAAI,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5G,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,KAAK,SAAS;YACZ,IAAI,CAAC,GAAG;gBAAE,MAAM,IAAI,UAAU,CAAC,kEAAkE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC1H,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAChC,KAAK,YAAY;YACf,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACjD;YACE,MAAM,IAAI,UAAU,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5H,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,CAAkB;IACjD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;QAChC,KAAK,YAAY;YACf,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;QAC9D;YACE,OAAO,CAAC,CAAC,IAAI,CAAC;IAClB,CAAC;AACH,CAAC;AAED,wHAAwH;AACxH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAkB,EAAW,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The package root, for a project's `yodel.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ * export default defineConfig({ environments: { prod: { topology: "cluster:main" } } });
+ * ```
+ */
+export { defineConfig } from "./config/define.js";
+export type { EnvironmentConfig, PolicyConfig, PolicyMigration, PolicyPlan, PolicyRule, PolicyStep, Topology, TopologySetting, YodelConfig } from "./config/define.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * The package root, for a project's `yodel.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ * export default defineConfig({ environments: { prod: { topology: "cluster:main" } } });
+ * ```
+ */
+export { defineConfig } from "./config/define.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/init/adopt.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `yodel init --from <env>`: adopt a live database in one go.
+ *
+ *  1. Refuse, before anything is written, when the project already declares
+ *     a schema (unless `force`), already has migrations, or the
+ *     environment's history already records any; and when the environment
+ *     names no `databases` (ClickHouse) or `schemas` (Postgres), or names
+ *     the history's own.
+ *  2. Read the live database with chant's import (`chant import --from`'s
+ *     library functions) and write the declarations into the source
+ *     directory.
+ *  3. Build them and plan the build against the same database. The plan
+ *     must be empty: the declarations are the database. If it is not, the
+ *     import does not round-trip, and everything written is taken back.
+ *  4. Write the baseline migration: the first migration (parent `null`),
+ *     whose statements create everything, from an empty schema to the build.
+ *  5. Record it applied in the history without running it (`./baseline.ts`),
+ *     on ClickHouse in `<history database>.history`, on Postgres in
+ *     `<history schema>.history` (#13), under the apply lock.
+ *
+ * Any failure in 2 to 5 takes back every file written. The live database
+ * is only read; the one write to the server is the history row, and the
+ * history database (schema) and table when they were not there.
+ */
+import { type Environment, type Project } from "../project.js";
+import type { HistoryRow } from "../history/index.js";
+export interface AdoptOptions {
+    /** Overwrite declaration files the source directory already has. */
+    force?: boolean;
+    /** The baseline migration's name. Default {@link BASELINE_NAME}. */
+    name?: string;
+    now?: Date;
+    processEnv?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+}
+export interface Adopted {
+    environment: string;
+    dialect: Project["dialect"];
+    /** The objects read, as `<kind> <name>`. */
+    objects: string[];
+    /** The declaration files written, relative to the project. */
+    schemaFiles: string[];
+    /** The baseline migration's directory, relative to the project. */
+    migrationPath: string;
+    baseline: {
+        id: string;
+        checksum: string;
+        statements: number;
+    };
+    /** The baseline's history row, recorded applied; init records it on both dialects. */
+    recorded: {
+        database: string;
+        row: HistoryRow;
+        lock: {
+            kind: string;
+            where: string;
+            notice?: string;
+        };
+    };
+    warnings: string[];
+}
+/** Where the declarations go: `sourceDir` when the config names one, else `src`. */
+export declare const schemaDir: (project: Project) => string;
+/** The refusals that need no server: a schema already declared, migrations already there, a ClickHouse scope that would take in the history. */
+export declare function preflight(project: Project, env: Environment, options?: {
+    force?: boolean;
+    processEnv?: NodeJS.ProcessEnv;
+}): void;
+/** Adopts `env`'s live database into the project; see the module comment. */
+export declare function adopt(project: Project, env: Environment, options?: AdoptOptions): Promise<Adopted>;

package/dist/init/adopt.js

@@ -0,0 +1,143 @@
+/**
+ * `yodel init --from <env>`: adopt a live database in one go.
+ *
+ *  1. Refuse, before anything is written, when the project already declares
+ *     a schema (unless `force`), already has migrations, or the
+ *     environment's history already records any; and when the environment
+ *     names no `databases` (ClickHouse) or `schemas` (Postgres), or names
+ *     the history's own.
+ *  2. Read the live database with chant's import (`chant import --from`'s
+ *     library functions) and write the declarations into the source
+ *     directory.
+ *  3. Build them and plan the build against the same database. The plan
+ *     must be empty: the declarations are the database. If it is not, the
+ *     import does not round-trip, and everything written is taken back.
+ *  4. Write the baseline migration: the first migration (parent `null`),
+ *     whose statements create everything, from an empty schema to the build.
+ *  5. Record it applied in the history without running it (`./baseline.ts`),
+ *     on ClickHouse in `<history database>.history`, on Postgres in
+ *     `<history schema>.history` (#13), under the apply lock.
+ *
+ * Any failure in 2 to 5 takes back every file written. The live database
+ * is only read; the one write to the server is the history row, and the
+ * history database (schema) and table when they were not there.
+ */
+import { join, relative } from "node:path";
+import { loadProject, YodelError } from "../project.js";
+import { buildSchema } from "../chant/build.js";
+import { planEnvironment, renderPlan } from "../chant/plan.js";
+import { createMigration, MIGRATIONS_DIR, writeMigration } from "../migrations/index.js";
+import { environmentSettings } from "../config/settings.js";
+import { closeVersioned, hasMigrations, openVersioned, REFUSED } from "../versioned/index.js";
+import { BASELINE_NAME, checkHistoryEmpty, recordBaseline } from "./baseline.js";
+import { declarationFiles, Journal } from "./files.js";
+import { describeImported, importLive } from "./live.js";
+/** Where the declarations go: `sourceDir` when the config names one, else `src`. */
+export const schemaDir = (project) => join(project.dir, project.config.sourceDir ?? "src");
+/** The refusals that need no server: a schema already declared, migrations already there, a ClickHouse scope that would take in the history. */
+export function preflight(project, env, options = {}) {
+    if (hasMigrations(project)) {
+        throw new YodelError(`refused: ${join(project.dir, MIGRATIONS_DIR)} already holds migrations; init writes the first one (the baseline), so it adopts a database only in a project with none. Nothing was written.`, REFUSED);
+    }
+    const dir = schemaDir(project);
+    const existing = declarationFiles(dir);
+    if (existing.length > 0 && !options.force) {
+        throw new YodelError(`refused: ${relative(project.dir, dir) || "."} already declares a schema (${existing.slice(0, 3).join(", ")}${existing.length > 3 ? ", ..." : ""}); ` +
+            `init writes the declarations from the live database there. Pass --force to overwrite (files the import does not write are kept, and are built with it). Nothing was written.`, REFUSED);
+    }
+    const { historyDatabase } = environmentSettings(project, env.name, options.processEnv);
+    const [key, what] = project.dialect === "postgres" ? ["schemas", "schema"] : ["databases", "database"];
+    const scope = project.dialect === "postgres" ? env.profile.schemas : env.profile.databases;
+    if (!scope || scope.length === 0) {
+        throw new YodelError(`refused: sql.profiles.${env.name} names no ${key}, so the import would read every ${what} on the server, the history's (${historyDatabase}) included. ` +
+            `List the ${key} this project owns in sql.profiles.${env.name}.${key}. Nothing was written.`, REFUSED);
+    }
+    if (scope.includes(historyDatabase)) {
+        throw new YodelError(`refused: sql.profiles.${env.name}.${key} includes ${historyDatabase}, the history's ${what} (yodel.config.ts environments.${env.name}.history.database, else YODEL_HISTORY_DATABASE); the history is yodel's, never part of the declared schema. Nothing was written.`, REFUSED);
+    }
+}
+/**
+ * Whether a plan has nothing to do: no change to a declared object, and no
+ * undeclared object it would drop, but for the objects the import left out
+ * as another tool's (`leftOut`), which an ApplyOp never drops since they
+ * carry no chant marker.
+ */
+const planIsEmpty = (plan, leftOut = []) => plan.diff.changes.every((c) => leftOut.includes(c.object)) && plan.refused.length === 0;
+/** Adopts `env`'s live database into the project; see the module comment. */
+export async function adopt(project, env, options = {}) {
+    const processEnv = options.processEnv ?? process.env;
+    const log = options.log ?? (() => undefined);
+    preflight(project, env, { ...(options.force !== undefined ? { force: options.force } : {}), processEnv });
+    const venv = await openVersioned(project, env, processEnv);
+    try {
+        await checkHistoryEmpty(venv);
+        return await adoptWith(project, env, venv, options, processEnv, log);
+    }
+    finally {
+        await closeVersioned(venv);
+    }
+}
+async function adoptWith(project, env, venv, options, processEnv, log) {
+    const live = await importLive(project, env, processEnv);
+    if (live.ir.resources.length === 0) {
+        throw new YodelError(`refused: ${env.name} holds no objects in its scope (sql.profiles.${env.name}); there is nothing to adopt. Declare a schema and run yodel new instead. Nothing was written.`, REFUSED);
+    }
+    const objects = describeImported(live.ir);
+    log(`read ${String(objects.length)} object(s) from ${env.name}`);
+    const journal = new Journal();
+    try {
+        const dir = schemaDir(project);
+        journal.mkdir(dir);
+        const schemaFiles = [];
+        for (const f of live.files) {
+            const path = join(dir, f.path);
+            journal.write(path, f.content);
+            schemaFiles.push(relative(project.dir, path));
+        }
+        log(`wrote ${schemaFiles.join(", ")}`);
+        // The source directory may have been made just now; load the project again so it is built from there.
+        const adopted = await loadProject(project.dir);
+        const build = await buildSchema(adopted, { env: processEnv });
+        let made;
+        try {
+            const plan = await planEnvironment(adopted, env, build, { env: processEnv });
+            if (!planIsEmpty(plan, live.leftOut)) {
+                throw new YodelError(`the declarations chant's import wrote do not plan clean against ${env.name}, so they are not yet the database; nothing was kept. ` +
+                    `This is an object chant cannot round-trip; please report it with the plan:\n${await renderPlan(plan, `Plan for ${env.name} after import`)}`);
+            }
+            log(`planned against ${env.name}: no change`);
+            made = createMigration({ name: options.name ?? BASELINE_NAME, build: build.output, ...(options.now ? { now: options.now } : {}) });
+        }
+        finally {
+            build.dispose();
+        }
+        if (made.id === undefined)
+            throw new YodelError("the build declares nothing, so there is no baseline to write");
+        const migrations = join(project.dir, MIGRATIONS_DIR);
+        journal.mkdir(migrations);
+        const path = writeMigration(migrations, made);
+        journal.created(path);
+        const migration = { id: made.id, dir: path, parent: null, checksum: made.document.checksum, document: made.document, files: made.files };
+        const statements = made.statements.steps.length;
+        log(`wrote ${relative(project.dir, path)} (${String(statements)} statement${statements === 1 ? "" : "s"})`);
+        const base = {
+            environment: env.name,
+            dialect: project.dialect,
+            objects,
+            schemaFiles,
+            migrationPath: relative(project.dir, path),
+            baseline: { id: made.id, checksum: made.document.checksum, statements },
+            warnings: live.warnings,
+        };
+        const { row, lock } = await recordBaseline(venv, migration, processEnv);
+        if (lock.notice)
+            log(`lock: ${lock.notice}`);
+        log(`recorded ${made.id} applied in ${venv.location.database}.history as a baseline; none of its statements was run`);
+        return { ...base, recorded: { database: venv.location.database, row, lock } };
+    }
+    catch (e) {
+        journal.undo();
+        throw e;
+    }
+}
+//# sourceMappingURL=adopt.js.map

package/dist/init/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../src/init/adopt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAkC,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AACzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,EAAqB,MAAM,uBAAuB,CAAC;AAEjH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AA2BzD,oFAAoF;AACpF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAU,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC;AAE5G,gJAAgJ;AAChJ,MAAM,UAAU,SAAS,CAAC,OAAgB,EAAE,GAAgB,EAAE,UAA+D,EAAE;IAC7H,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CAClB,YAAY,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,gJAAgJ,EAC7L,OAAO,CACR,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAClB,YAAY,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,GAAG,+BAA+B,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK;YACnJ,8KAA8K,EAChL,OAAO,CACR,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACvF,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAE,CAAC,SAAS,EAAE,QAAQ,CAAW,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,UAAU,CAAW,CAAC;IAC7H,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;IAC3F,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CAClB,yBAAyB,GAAG,CAAC,IAAI,aAAa,GAAG,oCAAoC,IAAI,kCAAkC,eAAe,cAAc;YACtJ,YAAY,GAAG,sCAAsC,GAAG,CAAC,IAAI,IAAI,GAAG,wBAAwB,EAC9F,OAAO,CACR,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,UAAU,CAClB,yBAAyB,GAAG,CAAC,IAAI,IAAI,GAAG,aAAa,eAAe,mBAAmB,IAAI,kCAAkC,GAAG,CAAC,IAAI,kIAAkI,EACvQ,OAAO,CACR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,WAAW,GAAG,CAAC,IAAU,EAAE,UAA6B,EAAE,EAAW,EAAE,CAC3E,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;AAE1F,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAgB,EAAE,GAAgB,EAAE,UAAwB,EAAE;IACxF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7C,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IAE1G,MAAM,IAAI,GAAiB,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACzE,IAAI,CAAC;QACH,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;IACvE,CAAC;YAAS,CAAC;QACT,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,OAAgB,EAAE,GAAgB,EAAE,IAAkB,EAAE,OAAqB,EAAE,UAA6B,EAAE,GAA2B;IAChK,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,YAAY,GAAG,CAAC,IAAI,gDAAgD,GAAG,CAAC,IAAI,gGAAgG,EAAE,OAAO,CAAC,CAAC;IAC9M,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1C,GAAG,CAAC,QAAQ,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;YAC/B,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,GAAG,CAAC,SAAS,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEvC,sGAAsG;QACtG,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9D,IAAI,IAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,UAAU,CAClB,mEAAmE,GAAG,CAAC,IAAI,wDAAwD;oBACjI,+EAA+E,MAAM,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,IAAI,eAAe,CAAC,EAAE,CAC/I,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,mBAAmB,GAAG,CAAC,IAAI,aAAa,CAAC,CAAC;YAC9C,IAAI,GAAG,eAAe,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACrI,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS;YAAE,MAAM,IAAI,UAAU,CAAC,8DAA8D,CAAC,CAAC;QAEhH,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACrD,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC1B,MAAM,IAAI,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC9C,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,SAAS,GAAc,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACpJ,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;QAChD,GAAG,CAAC,SAAS,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,MAAM,CAAC,UAAU,CAAC,aAAa,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAE5G,MAAM,IAAI,GAAG;YACX,WAAW,EAAE,GAAG,CAAC,IAAI;YACrB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO;YACP,WAAW;YACX,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC;YAC1C,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE;YACvE,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC;QACF,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACxE,IAAI,IAAI,CAAC,MAAM;YAAE,GAAG,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7C,GAAG,CAAC,YAAY,IAAI,CAAC,EAAE,eAAe,IAAI,CAAC,QAAQ,CAAC,QAAQ,wDAAwD,CAAC,CAAC;QACtH,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;IAChF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/init/baseline.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The baseline: the first migration of an adopted database, holding the
+ * schema the database already had, recorded applied without running it.
+ *
+ * ## How the history records it
+ *
+ * One migration row, `status = 'succeeded'`, `note` starting `baseline`
+ * ({@link BASELINE_NOTE}), the migration's checksum, `parent = ''`, and no
+ * statement rows: none of its statements was sent, since the objects they
+ * create are the ones it was read from. `plan_digest` is empty, as nothing
+ * was approved.
+ *
+ * The rest of yodel needs nothing new to read it. `deriveState` makes the
+ * migration's state its latest migration row, `succeeded`, so `isApplied`
+ * holds; `compareHistory` lists it applied, checks its checksum like any
+ * other's, and never puts it among the pending, so `yodel apply` never sends
+ * its statements; and statement rows are only read for a migration that is
+ * part way. A status other than `succeeded` (say `adopted`) would read as
+ * part way, and apply would run it, so the status stays `succeeded` and the
+ * note is what says it was adopted.
+ */
+import { YodelError } from "../project.js";
+import type { Migration } from "../migrations/index.js";
+import { type HistoryRow } from "../history/index.js";
+import { type VersionedEnv } from "../versioned/index.js";
+/** The baseline migration's name: its id is `<YYYYMMDDTHHMM>-baseline`. */
+export declare const BASELINE_NAME = "baseline";
+/** The start of a baseline row's `note`. */
+export declare const BASELINE_NOTE = "baseline";
+/** The note a baseline row carries. */
+export declare const baselineNote: (environment: string) => string;
+/** Whether a history row records a baseline. */
+export declare const isBaselineRow: (row: Pick<HistoryRow, "kind" | "note">) => boolean;
+/** The one row that records `m` applied as a baseline. */
+export declare function baselineRow(m: Pick<Migration, "id" | "parent" | "checksum">, input: {
+    seq: number;
+    runId: string;
+    appliedBy: string;
+    environment: string;
+}): HistoryRow;
+/** Why the history cannot take a baseline, or `undefined`: a baseline is the first thing a history records. */
+export declare function historyRefusal(state: {
+    migrations: readonly {
+        id: string;
+    }[];
+}, location: string): YodelError | undefined;
+/** Reads the history without the lock, for a refusal before anything is written. */
+export declare function checkHistoryEmpty(venv: VersionedEnv): Promise<void>;
+/**
+ * Records `m` applied as the baseline, under the apply lock: makes the
+ * history when it is not there, checks again that it records nothing, and
+ * appends the one row.
+ */
+export declare function recordBaseline(venv: VersionedEnv, m: Migration, processEnv?: NodeJS.ProcessEnv): Promise<{
+    row: HistoryRow;
+    lock: {
+        kind: string;
+        where: string;
+        notice?: string;
+    };
+}>;

package/dist/init/baseline.js

@@ -0,0 +1,88 @@
+/**
+ * The baseline: the first migration of an adopted database, holding the
+ * schema the database already had, recorded applied without running it.
+ *
+ * ## How the history records it
+ *
+ * One migration row, `status = 'succeeded'`, `note` starting `baseline`
+ * ({@link BASELINE_NOTE}), the migration's checksum, `parent = ''`, and no
+ * statement rows: none of its statements was sent, since the objects they
+ * create are the ones it was read from. `plan_digest` is empty, as nothing
+ * was approved.
+ *
+ * The rest of yodel needs nothing new to read it. `deriveState` makes the
+ * migration's state its latest migration row, `succeeded`, so `isApplied`
+ * holds; `compareHistory` lists it applied, checks its checksum like any
+ * other's, and never puts it among the pending, so `yodel apply` never sends
+ * its statements; and statement rows are only read for a migration that is
+ * part way. A status other than `succeeded` (say `adopted`) would read as
+ * part way, and apply would run it, so the status stays `succeeded` and the
+ * note is what says it was adopted.
+ */
+import { randomUUID } from "node:crypto";
+import { YodelError } from "../project.js";
+import { appliedBy, MIGRATION_ROW, withLock } from "../history/index.js";
+import { REFUSED } from "../versioned/index.js";
+/** The baseline migration's name: its id is `<YYYYMMDDTHHMM>-baseline`. */
+export const BASELINE_NAME = "baseline";
+/** The start of a baseline row's `note`. */
+export const BASELINE_NOTE = "baseline";
+/** The note a baseline row carries. */
+export const baselineNote = (environment) => `${BASELINE_NOTE}: adopted from the live database by yodel init --from ${environment}; its statements were not run`;
+/** Whether a history row records a baseline. */
+export const isBaselineRow = (row) => row.kind === "migration" && (row.note === BASELINE_NOTE || row.note.startsWith(`${BASELINE_NOTE}:`));
+/** The one row that records `m` applied as a baseline. */
+export function baselineRow(m, input) {
+    if (m.parent !== null)
+        throw new YodelError(`${m.id} follows ${m.parent}; only a first migration can be a baseline`);
+    return {
+        seq: input.seq,
+        run_id: input.runId,
+        kind: "migration",
+        migration_id: m.id,
+        parent: "",
+        checksum: m.checksum,
+        statement_index: MIGRATION_ROW,
+        statement_sha: "",
+        status: "succeeded",
+        error: "",
+        applied_by: input.appliedBy,
+        plan_digest: "",
+        silences: "[]",
+        note: baselineNote(input.environment),
+    };
+}
+/** Why the history cannot take a baseline, or `undefined`: a baseline is the first thing a history records. */
+export function historyRefusal(state, location) {
+    if (state.migrations.length === 0)
+        return undefined;
+    const ids = state.migrations.map((m) => m.id);
+    return new YodelError(`refused: the history (${location}) already records ${ids.length === 1 ? "a migration" : `${String(ids.length)} migrations`} (${ids.slice(0, 3).join(", ")}${ids.length > 3 ? ", ..." : ""}); ` +
+        `this environment is already under versioned migrations, so there is nothing to adopt. Nothing was written.`, REFUSED);
+}
+/** Reads the history without the lock, for a refusal before anything is written. */
+export async function checkHistoryEmpty(venv) {
+    const refusal = historyRefusal(await venv.store.state(), `${venv.location.database}.history`);
+    if (refusal)
+        throw refusal;
+}
+/**
+ * Records `m` applied as the baseline, under the apply lock: makes the
+ * history when it is not there, checks again that it records nothing, and
+ * appends the one row.
+ */
+export async function recordBaseline(venv, m, processEnv = process.env) {
+    const by = appliedBy(processEnv);
+    const lock = await venv.driver.acquireLock(by);
+    return withLock(lock, venv.lockTtlMs, async () => {
+        await venv.store.ensure();
+        const state = await venv.store.state();
+        const refusal = historyRefusal(state, `${venv.location.database}.history`);
+        if (refusal)
+            throw refusal;
+        const row = baselineRow(m, { seq: state.maxSeq + 1, runId: randomUUID(), appliedBy: by, environment: venv.environment });
+        await venv.store.append([row]);
+        return { row, lock: { kind: lock.kind, where: lock.where, ...(lock.notice ? { notice: lock.notice } : {}) } };
+    });
+}
+//# sourceMappingURL=baseline.js.map