@intentius/chant-lexicon-sql 0.124.46 → 0.124.49

package/dist/migrate/from-postgres/types.js

@@ -0,0 +1,211 @@
+/**
+ * The Postgres to ClickHouse type map (#4399).
+ *
+ * A type either maps with no judgment (`note` absent) or carries a `note`
+ * naming what the map could not keep. Only the first kind is mechanical: the
+ * translator writes no diagnostic for it. A type this file does not know (an
+ * enum, a domain, an extension type) maps to `String` with a note, because a
+ * mirror still has to hold the value.
+ *
+ * Source types and defaults are from the Postgres data types chapter
+ * (https://www.postgresql.org/docs/current/datatype.html): `timestamp` and
+ * `time` take a precision of 0 to 6 and default to microseconds, `numeric`
+ * with no precision holds any value, `money` is a fixed-point type with a
+ * locale-set scale, `float(n)` is `real` for n up to 24 and `double
+ * precision` above.
+ *
+ * Target types are ClickHouse types of the pinned server (`../../spec/pin.ts`);
+ * `types.test.ts` checks every family this file writes against the generated
+ * catalog.
+ */
+/** Split a column type as written into its words, its parenthesised arguments and its array dimensions. */
+export function parseType(text) {
+    let rest = text.trim();
+    let dims = 0;
+    for (;;) {
+        const m = /\s*\[\s*\d*\s*\]\s*$/.exec(rest);
+        if (!m)
+            break;
+        rest = rest.slice(0, m.index);
+        dims++;
+    }
+    const arrayWord = /\s+array(\s*\[\s*\d*\s*\])?$/i.exec(rest);
+    if (arrayWord) {
+        rest = rest.slice(0, arrayWord.index);
+        dims++;
+    }
+    const args = [];
+    rest = rest.replace(/\(([^)]*)\)/g, (_all, inner) => {
+        for (const part of inner.split(",")) {
+            const n = Number(part.trim());
+            if (Number.isFinite(n))
+                args.push(n);
+        }
+        return " ";
+    });
+    const base = rest
+        .replace(/"/g, "")
+        .replace(/^pg_catalog\./i, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+    return { base, args, dims, raw: text.trim() };
+}
+const STRING_NOTE = (what, evidence) => ({ message: `${what} is read as String.`, evidence });
+function mapScalar(t) {
+    const { base, args } = t;
+    switch (base) {
+        case "smallint":
+        case "int2":
+            return { ok: true, type: "Int16" };
+        case "integer":
+        case "int":
+        case "int4":
+            return { ok: true, type: "Int32" };
+        case "bigint":
+        case "int8":
+            return { ok: true, type: "Int64" };
+        case "smallserial":
+        case "serial2":
+            return { ok: true, type: "Int16", serial: true };
+        case "serial":
+        case "serial4":
+            return { ok: true, type: "Int32", serial: true };
+        case "bigserial":
+        case "serial8":
+            return { ok: true, type: "Int64", serial: true };
+        case "real":
+        case "float4":
+            return { ok: true, type: "Float32" };
+        case "double precision":
+        case "float8":
+            return { ok: true, type: "Float64" };
+        case "float":
+            return { ok: true, type: (args[0] ?? 53) <= 24 ? "Float32" : "Float64" };
+        case "numeric":
+        case "decimal": {
+            if (args.length === 0) {
+                return {
+                    ok: true,
+                    type: "Decimal(38, 18)",
+                    note: {
+                        message: "numeric with no precision is read as Decimal(38, 18).",
+                        evidence: ["Postgres stores up to 131072 digits before the point and 16383 after; a ClickHouse Decimal has a fixed precision and scale", "a value that does not fit fails the insert"],
+                    },
+                };
+            }
+            const p = args[0];
+            const s = args[1] ?? 0;
+            if (p > 76 || s < 0 || s > p) {
+                return {
+                    ok: true,
+                    type: "Decimal(76, 38)",
+                    note: { message: `numeric(${String(p)}, ${String(s)}) is read as Decimal(76, 38).`, evidence: ["ClickHouse Decimal holds at most 76 digits"] },
+                };
+            }
+            return { ok: true, type: `Decimal(${String(p)}, ${String(s)})` };
+        }
+        case "money":
+            return {
+                ok: true,
+                type: "Decimal(19, 2)",
+                note: { message: "money is read as Decimal(19, 2).", evidence: ["money takes its scale from the lc_monetary setting of the source server, and two decimals is the common one"] },
+            };
+        case "boolean":
+        case "bool":
+            return { ok: true, type: "Bool" };
+        case "text":
+        case "varchar":
+        case "character varying":
+        case "name":
+        case "citext":
+            return { ok: true, type: "String", ...(args[0] !== undefined ? { maxLength: args[0] } : {}) };
+        case "char":
+        case "character":
+        case "bpchar":
+            return {
+                ok: true,
+                type: "String",
+                ...(args[0] !== undefined ? { maxLength: args[0] } : {}),
+                ...(args[0] !== undefined && args[0] > 1 ? { note: STRING_NOTE("char(n)", ["Postgres pads a char(n) value with spaces to n characters; a String keeps the value as it is loaded"]) } : {}),
+            };
+        case "bytea":
+            return { ok: true, type: "String" };
+        case "uuid":
+            return { ok: true, type: "UUID" };
+        case "date":
+            return { ok: true, type: "Date32" };
+        case "time":
+        case "time without time zone":
+            return { ok: true, type: `Time64(${String(args[0] ?? 6)})` };
+        case "timetz":
+        case "time with time zone":
+            return { ok: true, type: "String", note: STRING_NOTE("timetz", ["a time of day with an offset has no ClickHouse type; the offset is kept in the text"]) };
+        case "timestamp":
+        case "timestamp without time zone":
+            return { ok: true, type: `DateTime64(${String(args[0] ?? 6)})` };
+        case "timestamptz":
+        case "timestamp with time zone":
+            return { ok: true, type: `DateTime64(${String(args[0] ?? 6)}, 'UTC')` };
+        case "interval":
+            return { ok: true, type: "String", note: STRING_NOTE("interval", ["a ClickHouse Interval type cannot be stored in a column", "the value is kept as Postgres prints it"]) };
+        case "json":
+        case "jsonb":
+            return { ok: true, type: "JSON" };
+        case "oid":
+            return { ok: true, type: "UInt32" };
+        case "inet":
+        case "cidr":
+            return {
+                ok: true,
+                type: "IPv6",
+                note: { message: `${base} is read as IPv6.`, evidence: ["an IPv6 column holds an IPv4 address in its mapped form", "the prefix length of a network is not kept"] },
+            };
+        case "xml":
+        case "macaddr":
+        case "macaddr8":
+        case "tsvector":
+        case "tsquery":
+        case "bit":
+        case "bit varying":
+        case "varbit":
+        case "point":
+        case "line":
+        case "lseg":
+        case "box":
+        case "path":
+        case "polygon":
+        case "circle":
+            return { ok: true, type: "String", note: STRING_NOTE(base, [`ClickHouse has no ${base} type`, "the value is kept as Postgres prints it"]) };
+        default:
+            return {
+                ok: true,
+                type: "String",
+                note: STRING_NOTE(t.raw, [`${t.raw} is not a built-in type chant maps (an enum, a domain, a composite or an extension type)`, "the value is kept as Postgres prints it; an enum could be an Enum8 or Enum16 once its labels are settled"]),
+            };
+    }
+}
+/** Map a column type as the declaration wrote it. */
+export function mapPostgresType(text) {
+    const t = parseType(text);
+    const inner = mapScalar(t);
+    if (t.dims === 0)
+        return inner;
+    let type = inner.type;
+    for (let i = 0; i < t.dims; i++)
+        type = `Array(${type})`;
+    return {
+        ok: true,
+        type,
+        array: true,
+        ...(inner.serial ? { serial: true } : {}),
+        note: {
+            message: `${t.raw} is read as ${type}.`,
+            evidence: [
+                ...(inner.note ? [inner.note.message] : []),
+                "ClickHouse cannot make an Array Nullable, so a NULL array is stored as an empty one",
+                "Postgres does not enforce the declared dimensions or lengths of an array",
+            ],
+        },
+    };
+}

package/dist/migration-classify.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Classify the migration files a pull request adds (#4407), the lexicon's
+ * answer to core's `classifyMigrations` hook. The "check" adoption level:
+ * each new file's up statements are read and given the class the schema-diff
+ * classifier gives the same change, and nothing else happens. No server is
+ * contacted, no migration tool runs and nothing is applied, so it needs no
+ * environment binding (compare `chant sql replay`, which does).
+ *
+ * The up statements are the ones replay would run: goose's `-- +goose Up`
+ * section, the whole file for golang-migrate and clickhouse-migrations, and a
+ * Flyway file after placeholder substitution with the configuration's values.
+ */
+import type { MigrationFileClassification } from "@intentius/chant/pr-migrations";
+import type { WorkspaceTree } from "@intentius/chant/workspace/tree";
+export declare const MIGRATION_DIALECTS: readonly ["postgres", "clickhouse"];
+export declare function classifyMigrationFiles(options: {
+    reader: string;
+    dialect: string;
+    tree: WorkspaceTree;
+    dir: string;
+    files: string[];
+}): MigrationFileClassification[];
+//# sourceMappingURL=migration-classify.d.ts.map

package/dist/migration-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-classify.d.ts","sourceRoot":"","sources":["../src/migration-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAKrE,eAAO,MAAM,kBAAkB,qCAAsC,CAAC;AAKtE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,2BAA2B,EAAE,CAmBrK"}

package/dist/migration-classify.js

@@ -0,0 +1,44 @@
+/**
+ * Classify the migration files a pull request adds (#4407), the lexicon's
+ * answer to core's `classifyMigrations` hook. The "check" adoption level:
+ * each new file's up statements are read and given the class the schema-diff
+ * classifier gives the same change, and nothing else happens. No server is
+ * contacted, no migration tool runs and nothing is applied, so it needs no
+ * environment binding (compare `chant sql replay`, which does).
+ *
+ * The up statements are the ones replay would run: goose's `-- +goose Up`
+ * section, the whole file for golang-migrate and clickhouse-migrations, and a
+ * Flyway file after placeholder substitution with the configuration's values.
+ */
+import { findFlywayConfig, readFlywayConfig, substitute } from "@intentius/chant/workspace/flyway-layout";
+import { classifyClickHouseStatements } from "./clickhouse/plan/statements.js";
+import { gooseUpStatements, splitStatements } from "./migration-replay.js";
+import { classifyPgStatements } from "./postgres/plan/statements.js";
+export const MIGRATION_DIALECTS = ["postgres", "clickhouse"];
+/** The reader names whose files this lexicon reads. */
+const READERS = new Set(["goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"]);
+export function classifyMigrationFiles(options) {
+    const { reader, dialect, tree, dir, files } = options;
+    if (!READERS.has(reader) || !MIGRATION_DIALECTS.includes(dialect))
+        return [];
+    const classify = dialect === "postgres" ? classifyPgStatements : classifyClickHouseStatements;
+    let flyway;
+    return files.map((file) => {
+        try {
+            const text = tree.read(file);
+            let statements;
+            if (reader === "goose-dir")
+                statements = gooseUpStatements(text);
+            else if (reader === "flyway-dir") {
+                flyway ?? (flyway = readFlywayConfig(tree, findFlywayConfig(tree, dir), dir));
+                statements = splitStatements(substitute(text, file, flyway));
+            }
+            else
+                statements = splitStatements(text);
+            return { file, statements: classify(statements) };
+        }
+        catch (err) {
+            return { file, statements: [], error: err instanceof Error ? err.message : String(err) };
+        }
+    });
+}

package/dist/migration-replay.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Replay a migration directory into an empty server and read the catalog
+ * (#4400). The workspace kinds for goose, golang-migrate,
+ * clickhouse-migrations and Flyway list a directory's migrations without
+ * running anything (`packages/core/src/workspace/migration-dirs.ts`); the
+ * tables and columns they produce come from here.
+ *
+ *     chant sql replay <dir> --kind <kind> --env <env> [--dir-field migrationsDir=<sub>] [--check]
+ *
+ * The replay applies each migration's up statements in the order the kind's
+ * reader lists them, then reads the tables, views and columns the server has
+ * and writes them as `chant.replay.json` beside the migrations, named by the
+ * contract of #3931: `<schema>.<table>` and `<schema>.<table>.<column>` for
+ * Postgres, `<database>.<table>` and `<database>.<table>.<column>` for
+ * ClickHouse. The file also holds a digest of the files it ran, so the
+ * reader knows when a migration changed after it. `--check` replays and
+ * compares instead of writing, exiting 1 when the file differs, the way
+ * `chant sql types --check` does.
+ *
+ * What it runs per kind:
+ * - goose: the `-- +goose Up` section of each file; `StatementBegin` to
+ *   `StatementEnd` is one statement.
+ * - golang-migrate and clickhouse-migrations: the whole up file.
+ * - Flyway: the SQL files of the locations, versioned in version order and
+ *   then repeatable ones, with placeholders substituted. Baseline and undo
+ *   files are not run.
+ *
+ * The server must hold no table, view or column of its own: the replay
+ * refuses a server that does, since it cannot tell what the migrations made.
+ * It runs the migrations' SQL against the server `--env` binds, so point it
+ * at a throwaway server or emulator.
+ */
+import type { CommandGroupContext } from "@intentius/chant/cli/command-group";
+import { type KindReadMigration, type KindReaderInput } from "@intentius/chant/workspace/kind-link-readers";
+import { type ReplaySnapshot } from "@intentius/chant/workspace/migration-dirs";
+import { type WorkspaceTree } from "@intentius/chant/workspace/tree";
+export declare const REPLAY_KINDS: readonly ["goose", "golang-migrate", "clickhouse-migrations", "flyway"];
+export type ReplayKind = (typeof REPLAY_KINDS)[number];
+/** One server the replay runs on. */
+export interface ReplayDb {
+    dialect: "postgres" | "clickhouse";
+    run(sql: string): Promise<void>;
+    rows(sql: string): Promise<Record<string, unknown>[]>;
+    close(): Promise<void>;
+}
+/**
+ * Split SQL text into statements at `;`. Single-quoted strings, quoted
+ * identifiers, `--` and `/* *\/` comments and Postgres dollar-quoted bodies
+ * hold semicolons without ending the statement. A statement of only
+ * comments is dropped.
+ */
+export declare function splitStatements(text: string): string[];
+/** goose's Up statements: the lines between `-- +goose Up` and `-- +goose Down`; a StatementBegin to StatementEnd block is one statement. */
+export declare function gooseUpStatements(text: string): string[];
+export interface ReplayStep {
+    migration: KindReadMigration;
+    statements: string[];
+}
+/** The statements to run, per migration, in order. Throws when a Flyway placeholder has no value. */
+export declare function replaySteps(kind: ReplayKind, tree: WorkspaceTree, dir: string, fields?: KindReaderInput["fields"]): {
+    steps: ReplayStep[];
+    files: string[];
+    dialect: string;
+};
+/** Apply each migration's statements; a failure names the migration file and the statement. */
+export declare function applySteps(db: ReplayDb, steps: readonly ReplayStep[]): Promise<void>;
+/** The tables, views and columns the server has, as workspace output names (#3931). */
+export declare function readCatalogOutputs(db: ReplayDb): Promise<string[]>;
+/** Replay a directory into `db`, which must hold nothing, and return the snapshot to record. */
+export declare function replayDirectory(db: ReplayDb, kind: ReplayKind, tree: WorkspaceTree, dir: string, fields?: KindReaderInput["fields"]): Promise<ReplaySnapshot>;
+export declare const renderSnapshot: (s: ReplaySnapshot) => string;
+export declare function runReplay(ctx: CommandGroupContext): Promise<number>;
+//# sourceMappingURL=migration-replay.d.ts.map

package/dist/migration-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-replay.d.ts","sourceRoot":"","sources":["../src/migration-replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAgB,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,8CAA8C,CAAC;AAC1H,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAE3H,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAElF,eAAO,MAAM,YAAY,yEAA0E,CAAC;AACpG,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvD,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,UAAU,GAAG,YAAY,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyCtD;AAED,6IAA6I;AAC7I,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BxD;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,eAAe,CAAC,QAAQ,CAAQ,GAAG;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAWnL;AAED,+FAA+F;AAC/F,wBAAsB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1F;AAoBD,uFAAuF;AACvF,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAaxE;AAED,gGAAgG;AAChG,wBAAsB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,eAAe,CAAC,QAAQ,CAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAOzK;AAED,eAAO,MAAM,cAAc,GAAI,GAAG,cAAc,KAAG,MAA2C,CAAC;AAiB/F,wBAAsB,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2DzE"}

package/dist/migration-replay.js

@@ -0,0 +1,294 @@
+/**
+ * Replay a migration directory into an empty server and read the catalog
+ * (#4400). The workspace kinds for goose, golang-migrate,
+ * clickhouse-migrations and Flyway list a directory's migrations without
+ * running anything (`packages/core/src/workspace/migration-dirs.ts`); the
+ * tables and columns they produce come from here.
+ *
+ *     chant sql replay <dir> --kind <kind> --env <env> [--dir-field migrationsDir=<sub>] [--check]
+ *
+ * The replay applies each migration's up statements in the order the kind's
+ * reader lists them, then reads the tables, views and columns the server has
+ * and writes them as `chant.replay.json` beside the migrations, named by the
+ * contract of #3931: `<schema>.<table>` and `<schema>.<table>.<column>` for
+ * Postgres, `<database>.<table>` and `<database>.<table>.<column>` for
+ * ClickHouse. The file also holds a digest of the files it ran, so the
+ * reader knows when a migration changed after it. `--check` replays and
+ * compares instead of writing, exiting 1 when the file differs, the way
+ * `chant sql types --check` does.
+ *
+ * What it runs per kind:
+ * - goose: the `-- +goose Up` section of each file; `StatementBegin` to
+ *   `StatementEnd` is one statement.
+ * - golang-migrate and clickhouse-migrations: the whole up file.
+ * - Flyway: the SQL files of the locations, versioned in version order and
+ *   then repeatable ones, with placeholders substituted. Baseline and undo
+ *   files are not run.
+ *
+ * The server must hold no table, view or column of its own: the replay
+ * refuses a server that does, since it cannot tell what the migrations made.
+ * It runs the migrations' SQL against the server `--env` binds, so point it
+ * at a throwaway server or emulator.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { LINK_READERS } from "@intentius/chant/workspace/kind-link-readers";
+import { migrationDigest, REPLAY_FILE, replayFiles } from "@intentius/chant/workspace/migration-dirs";
+import { findFlywayConfig, readFlywayConfig, substitute } from "@intentius/chant/workspace/flyway-layout";
+import { workingTree } from "@intentius/chant/workspace/tree";
+export const REPLAY_KINDS = ["goose", "golang-migrate", "clickhouse-migrations", "flyway"];
+const READER = { goose: "goose-dir", "golang-migrate": "golang-migrate-dir", "clickhouse-migrations": "clickhouse-migrations-dir", flyway: "flyway-dir" };
+/**
+ * Split SQL text into statements at `;`. Single-quoted strings, quoted
+ * identifiers, `--` and `/* *\/` comments and Postgres dollar-quoted bodies
+ * hold semicolons without ending the statement. A statement of only
+ * comments is dropped.
+ */
+export function splitStatements(text) {
+    const out = [];
+    let start = 0;
+    let i = 0;
+    const flush = (end) => {
+        const s = text.slice(start, end).trim();
+        if (s !== "" && s.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "").trim() !== "")
+            out.push(s);
+        start = end + 1;
+    };
+    while (i < text.length) {
+        const c = text[i];
+        const two = text.slice(i, i + 2);
+        if (two === "--") {
+            const nl = text.indexOf("\n", i);
+            i = nl < 0 ? text.length : nl + 1;
+        }
+        else if (two === "/*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end < 0 ? text.length : end + 2;
+        }
+        else if (c === "'" || c === '"' || c === "`") {
+            i++;
+            while (i < text.length) {
+                if (text[i] === "\\" && c !== '"')
+                    i += 2;
+                else if (text[i] === c) {
+                    if (text[i + 1] === c)
+                        i += 2;
+                    else
+                        break;
+                }
+                else
+                    i++;
+            }
+            i++;
+        }
+        else if (c === "$") {
+            const tag = /^\$[A-Za-z_]*\$/.exec(text.slice(i))?.[0];
+            if (tag) {
+                const end = text.indexOf(tag, i + tag.length);
+                i = end < 0 ? text.length : end + tag.length;
+            }
+            else
+                i++;
+        }
+        else if (c === ";") {
+            flush(i);
+            i++;
+        }
+        else
+            i++;
+    }
+    flush(text.length);
+    return out;
+}
+/** goose's Up statements: the lines between `-- +goose Up` and `-- +goose Down`; a StatementBegin to StatementEnd block is one statement. */
+export function gooseUpStatements(text) {
+    const out = [];
+    let section = "none";
+    let block;
+    let plain = [];
+    const annotation = (l) => {
+        const t = l.trim();
+        return t.startsWith("--") && t.includes("+goose") ? t.replace("+goose", "").replace(/^--\s*/, "").trim().toLowerCase() : undefined;
+    };
+    const flushPlain = () => {
+        out.push(...splitStatements(plain.join("\n")));
+        plain = [];
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const a = annotation(line);
+        if (a === "up")
+            section = "up";
+        else if (a === "down") {
+            flushPlain();
+            section = "down";
+        }
+        else if (a === "statementbegin" && section === "up") {
+            flushPlain();
+            block = [];
+        }
+        else if (a === "statementend" && section === "up" && block) {
+            const s = block.join("\n").trim();
+            if (s !== "")
+                out.push(s);
+            block = undefined;
+        }
+        else if (section === "up" && a === undefined)
+            (block ?? plain).push(line);
+    }
+    flushPlain();
+    return out;
+}
+/** The statements to run, per migration, in order. Throws when a Flyway placeholder has no value. */
+export function replaySteps(kind, tree, dir, fields = null) {
+    const read = LINK_READERS[READER[kind]]({ member: { name: "replay" }, dir, fields, tree });
+    const migrations = (read.migrations ?? []).filter((m) => m.type === "versioned" || m.type === "repeatable");
+    const config = kind === "flyway" ? readFlywayConfig(tree, findFlywayConfig(tree, dir), dir) : undefined;
+    const steps = migrations.map((migration) => {
+        const text = tree.read(migration.file);
+        const statements = kind === "goose" ? gooseUpStatements(text) : splitStatements(config ? substitute(text, migration.file, config) : text);
+        return { migration, statements };
+    });
+    const extra = config?.file !== undefined ? [config.file] : [];
+    return { steps, files: replayFiles(tree, read.migrations ?? [], extra), dialect: read.migrations?.[0]?.dialect ?? "postgres" };
+}
+/** Apply each migration's statements; a failure names the migration file and the statement. */
+export async function applySteps(db, steps) {
+    for (const { migration, statements } of steps) {
+        for (const [i, sql] of statements.entries()) {
+            try {
+                await db.run(sql);
+            }
+            catch (err) {
+                throw new Error(`${migration.file}: statement ${String(i + 1)} failed: ${err.message}\n${sql.slice(0, 200)}`);
+            }
+        }
+    }
+}
+const POSTGRES_CATALOG = `
+select n.nspname as schema, c.relname as relation, a.attname as col
+from pg_class c
+join pg_namespace n on n.oid = c.relnamespace
+left join pg_attribute a on a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped
+where c.relkind in ('r', 'p', 'v', 'm', 'f')
+  and n.nspname not in ('pg_catalog', 'information_schema')
+  and n.nspname not like 'pg\\_toast%' and n.nspname not like 'pg\\_temp%'
+order by 1, 2, a.attnum`;
+const CLICKHOUSE_CATALOG = `
+select t.database as schema, t.name as relation, c.name as col
+from system.tables t
+left join system.columns c on c.database = t.database and c.table = t.name
+where t.database not in ('system', 'INFORMATION_SCHEMA', 'information_schema')
+  and t.is_temporary = 0
+order by t.database, t.name, c.position`;
+/** The tables, views and columns the server has, as workspace output names (#3931). */
+export async function readCatalogOutputs(db) {
+    const rows = await db.rows(db.dialect === "postgres" ? POSTGRES_CATALOG : CLICKHOUSE_CATALOG);
+    const out = [];
+    const seen = new Set();
+    for (const r of rows) {
+        const rel = `${String(r.schema)}.${String(r.relation)}`;
+        if (!seen.has(rel)) {
+            seen.add(rel);
+            out.push(rel);
+        }
+        if (r.col !== null && r.col !== undefined)
+            out.push(`${rel}.${String(r.col)}`);
+    }
+    return out;
+}
+/** Replay a directory into `db`, which must hold nothing, and return the snapshot to record. */
+export async function replayDirectory(db, kind, tree, dir, fields = null) {
+    const before = await readCatalogOutputs(db);
+    if (before.length > 0)
+        throw new Error(`the server already has ${before[0].split(".").slice(0, 2).join(".")}${before.length > 1 ? ` and ${String(before.length - 1)} more names` : ""}; replay needs a server with no tables or views of its own, so the tables it finds are the migrations' (use a throwaway server or emulator)`);
+    const { steps, files, dialect } = replaySteps(kind, tree, dir, fields);
+    if (dialect !== db.dialect)
+        throw new Error(`the migrations are ${dialect} and the server is ${db.dialect}; set the member's dialect field or bind the matching server`);
+    await applySteps(db, steps);
+    return { schema: 1, dialect, digest: migrationDigest((f) => tree.read(f), files), outputs: await readCatalogOutputs(db) };
+}
+export const renderSnapshot = (s) => `${JSON.stringify(s, null, 2)}\n`;
+const USAGE = "usage: chant sql replay <dir> --kind goose|golang-migrate|clickhouse-migrations|flyway --env <env> [--migrations-dir <sub>] [--dialect postgres|clickhouse] [--check]";
+/** Open the server `--env` binds, of the migrations' dialect. */
+async function openBound(dialect, environment) {
+    if (dialect === "postgres") {
+        const { bindPostgres } = await import("./postgres/live/bind.js");
+        const { client } = await bindPostgres({ environment });
+        return { dialect, run: async (sql) => void (await client.query(sql)), rows: (sql) => client.query(sql), close: () => client.end() };
+    }
+    const { bindClickHouse } = await import("./clickhouse/live/bind.js");
+    const { clickhouseQuery } = await import("./clickhouse/http.js");
+    const target = await bindClickHouse({ environment });
+    return { dialect, run: async (sql) => void (await clickhouseQuery(target.endpoint, sql)), rows: (sql) => clickhouseQuery(target.endpoint, sql), async close() { } };
+}
+export async function runReplay(ctx) {
+    const args = ctx.rawArgs;
+    let kind;
+    let env;
+    let sub;
+    let dialect;
+    const check = args.includes("--check");
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--kind")
+            kind = args[++i];
+        else if (a === "--env")
+            env = args[++i];
+        else if (a === "--migrations-dir")
+            sub = args[++i];
+        else if (a === "--dialect")
+            dialect = args[++i];
+        else if (a === "--check")
+            continue;
+        else if (a.startsWith("--")) {
+            console.error(`unknown argument ${a}\n${USAGE}`);
+            return 1;
+        }
+        else
+            positional.push(a);
+    }
+    if (positional.length !== 1 || !kind || !REPLAY_KINDS.includes(kind) || !env) {
+        console.error(USAGE);
+        return 1;
+    }
+    const abs = resolve(process.cwd(), positional[0]);
+    const tree = workingTree(abs);
+    const fields = { ...(sub ? { migrationsDir: sub } : {}), ...(dialect ? { dialect } : {}) };
+    const { steps, dialect: found } = replaySteps(kind, tree, "", fields);
+    if (steps.length === 0) {
+        console.error(`chant sql replay: ${relative(process.cwd(), abs) || "."} lists no ${kind} migrations`);
+        return 1;
+    }
+    const db = await openBound(found, env);
+    let snapshot;
+    try {
+        snapshot = await replayDirectory(db, kind, tree, "", fields);
+    }
+    catch (err) {
+        console.error(`chant sql replay: ${err.message}`);
+        return 1;
+    }
+    finally {
+        await db.close();
+    }
+    const file = join(abs, REPLAY_FILE);
+    const text = renderSnapshot(snapshot);
+    const current = (() => {
+        try {
+            return readFileSync(file, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (check) {
+        if (current === text)
+            return 0;
+        console.error(`chant sql replay --check: ${relative(process.cwd(), file)} ${current === undefined ? "is missing" : "differs from a replay of the migrations"}; run chant sql replay and commit it`);
+        return 1;
+    }
+    writeFileSync(file, text);
+    console.log(`recorded ${String(snapshot.outputs.length)} names from ${String(steps.length)} migrations in ${relative(process.cwd(), file)}`);
+    return 0;
+}