@onreza/sqlx-js 0.0.0

package/dist/src/commands/migrate.js

@@ -0,0 +1,283 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { PgClient, parseDatabaseUrl, decodeText } from "../pg/wire.js";
+export const DEFAULT_MIGRATE_LOCK_KEY = 18750938867203960n;
+const FILE_RE = /^(\d+)_(.+)\.up\.sql$/;
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+function readMigrations(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir).sort()) {
+        const m = FILE_RE.exec(f);
+        if (!m)
+            continue;
+        const version = parseInt(m[1], 10);
+        const name = m[2];
+        if (!SAFE_NAME_RE.test(name)) {
+            throw new Error(`sqlx-js.migrate: unsafe migration filename ${f} — name must match /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/`);
+        }
+        const upPath = join(dir, f);
+        const downPath = join(dir, `${m[1]}_${name}.down.sql`);
+        const upSql = readFileSync(upPath, "utf8");
+        out.push({
+            version,
+            name,
+            upPath,
+            downPath: existsSync(downPath) ? downPath : null,
+            upSql,
+            upHash: createHash("sha256").update(upSql).digest("hex"),
+        });
+    }
+    return out;
+}
+export async function ensureTable(c) {
+    await c.simpleQuery(`
+    CREATE TABLE IF NOT EXISTS _sqlx_js_migrations (
+      version BIGINT PRIMARY KEY,
+      name TEXT NOT NULL,
+      up_hash TEXT NOT NULL,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+}
+export async function listApplied(c) {
+    const r = await c.simpleQuery("SELECT version, name, up_hash FROM _sqlx_js_migrations ORDER BY version");
+    const out = new Map();
+    for (const row of r.rows) {
+        out.set(Number(decodeText(row[0])), { name: decodeText(row[1]), hash: decodeText(row[2]) });
+    }
+    return out;
+}
+export async function applyPending(c, migrationsDir, onEvent) {
+    await ensureTable(c);
+    const applied = await listApplied(c);
+    const all = readMigrations(migrationsDir);
+    const counts = { applied: 0, tampered: 0, failed: 0 };
+    for (const m of all) {
+        const a = applied.get(m.version);
+        if (a) {
+            if (a.hash !== m.upHash) {
+                counts.tampered++;
+                onEvent?.({ kind: "tampered", version: m.version, name: m.name, applied: a.hash, current: m.upHash });
+                return counts;
+            }
+            continue;
+        }
+        await c.simpleQuery("BEGIN");
+        try {
+            await c.simpleQuery(m.upSql);
+            await c.execParamsText("INSERT INTO _sqlx_js_migrations (version, name, up_hash) VALUES ($1, $2, $3)", [String(m.version), m.name, m.upHash]);
+            await c.simpleQuery("COMMIT");
+            counts.applied++;
+            onEvent?.({ kind: "applied", version: m.version, name: m.name });
+        }
+        catch (err) {
+            let rollbackErr;
+            try {
+                await c.simpleQuery("ROLLBACK");
+            }
+            catch (rb) {
+                rollbackErr = rb.message;
+            }
+            counts.failed++;
+            const message = rollbackErr
+                ? `${err.message} (rollback also failed: ${rollbackErr})`
+                : err.message;
+            onEvent?.({ kind: "failed", version: m.version, name: m.name, error: message });
+            return counts;
+        }
+    }
+    return counts;
+}
+function lockKeyToString(lockKey) {
+    if (typeof lockKey === "bigint")
+        return lockKey.toString();
+    if (!Number.isSafeInteger(lockKey)) {
+        throw new Error(`sqlx-js.migrate: lockKey must be a safe integer or bigint, got ${lockKey}`);
+    }
+    return BigInt(lockKey).toString();
+}
+export async function acquireMigrateLock(c, lockKey = DEFAULT_MIGRATE_LOCK_KEY, timeoutMs) {
+    if (timeoutMs !== undefined && !Number.isFinite(timeoutMs)) {
+        throw new Error(`sqlx-js.migrate: lockTimeoutMs must be a finite number, got ${timeoutMs}`);
+    }
+    const key = lockKeyToString(lockKey);
+    if (timeoutMs === undefined || timeoutMs <= 0) {
+        await c.simpleQuery(`SELECT pg_advisory_lock(${key})`);
+        return;
+    }
+    const start = Date.now();
+    let delay = 50;
+    while (true) {
+        const r = await c.simpleQuery(`SELECT pg_try_advisory_lock(${key})`);
+        const got = decodeText(r.rows[0]?.[0] ?? null) === "t";
+        if (got)
+            return;
+        const elapsed = Date.now() - start;
+        if (elapsed >= timeoutMs) {
+            throw new Error(`sqlx-js.migrate: failed to acquire advisory lock ${key} within ${timeoutMs}ms`);
+        }
+        const remaining = timeoutMs - elapsed;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(delay, remaining)));
+        delay = Math.min(delay * 2, 2000);
+    }
+}
+export async function releaseMigrateLock(c, lockKey = DEFAULT_MIGRATE_LOCK_KEY) {
+    const key = lockKeyToString(lockKey);
+    await c.simpleQuery(`SELECT pg_advisory_unlock(${key})`);
+}
+export async function migrateRun(opts) {
+    const cfg = parseDatabaseUrl(opts.databaseUrl);
+    const c = new PgClient(cfg);
+    await c.connect();
+    let exitCode = 0;
+    let locked = false;
+    const lockKey = opts.lockKey ?? DEFAULT_MIGRATE_LOCK_KEY;
+    try {
+        await acquireMigrateLock(c, lockKey, opts.lockTimeoutMs);
+        locked = true;
+        await applyPending(c, opts.migrationsDir, (e) => {
+            if (e.kind === "applied")
+                console.log(`applying ${e.version}_${e.name}…\n  ✓ applied`);
+            else if (e.kind === "tampered") {
+                console.error(`migration ${e.version}_${e.name} was tampered with (hash mismatch)`);
+                console.error(`  applied: ${e.applied.slice(0, 16)}…`);
+                console.error(`  current: ${e.current.slice(0, 16)}…`);
+                exitCode = 1;
+            }
+            else {
+                console.error(`applying ${e.version}_${e.name}…\n  ✗ ${e.error}`);
+                exitCode = 1;
+            }
+        });
+    }
+    finally {
+        if (locked) {
+            try {
+                await releaseMigrateLock(c, lockKey);
+            }
+            catch (e) {
+                console.warn(`sqlx-js.migrate: failed to release advisory lock: ${e.message}`);
+            }
+        }
+        await c.end();
+    }
+    if (exitCode !== 0)
+        process.exit(exitCode);
+}
+export async function migrateInfo(opts) {
+    const cfg = parseDatabaseUrl(opts.databaseUrl);
+    const c = new PgClient(cfg);
+    await c.connect();
+    await ensureTable(c);
+    const applied = await listApplied(c);
+    const all = readMigrations(opts.migrationsDir);
+    console.log(`migrations in ${opts.migrationsDir}:`);
+    for (const m of all) {
+        const a = applied.get(m.version);
+        const status = !a ? "pending" : a.hash === m.upHash ? "applied" : "applied (tampered!)";
+        console.log(`  ${String(m.version).padStart(4, "0")}_${m.name}: ${status}`);
+    }
+    await c.end();
+}
+export async function revertLast(c, migrationsDir) {
+    await ensureTable(c);
+    const applied = await listApplied(c);
+    const all = readMigrations(migrationsDir);
+    let last = null;
+    for (let i = all.length - 1; i >= 0; i--) {
+        if (applied.has(all[i].version)) {
+            last = all[i];
+            break;
+        }
+    }
+    if (!last)
+        return { kind: "noop" };
+    if (!last.downPath)
+        return { kind: "no-down", version: last.version, name: last.name };
+    const downSql = readFileSync(last.downPath, "utf8");
+    await c.simpleQuery("BEGIN");
+    try {
+        await c.simpleQuery(downSql);
+        await c.execParamsText("DELETE FROM _sqlx_js_migrations WHERE version = $1", [String(last.version)]);
+        await c.simpleQuery("COMMIT");
+        return { kind: "reverted", version: last.version, name: last.name };
+    }
+    catch (err) {
+        let rollbackErr;
+        try {
+            await c.simpleQuery("ROLLBACK");
+        }
+        catch (rb) {
+            rollbackErr = rb.message;
+        }
+        const msg = rollbackErr
+            ? `${err.message} (rollback also failed: ${rollbackErr})`
+            : err.message;
+        return { kind: "failed", version: last.version, name: last.name, error: msg };
+    }
+}
+export async function migrateRevert(opts) {
+    const cfg = parseDatabaseUrl(opts.databaseUrl);
+    const c = new PgClient(cfg);
+    await c.connect();
+    const lockKey = opts.lockKey ?? DEFAULT_MIGRATE_LOCK_KEY;
+    let locked = false;
+    let exitCode = 0;
+    try {
+        await acquireMigrateLock(c, lockKey, opts.lockTimeoutMs);
+        locked = true;
+        const outcome = await revertLast(c, opts.migrationsDir);
+        if (outcome.kind === "noop") {
+            console.log("nothing to revert");
+        }
+        else if (outcome.kind === "no-down") {
+            console.error(`migration ${outcome.version}_${outcome.name} has no .down.sql`);
+            exitCode = 1;
+        }
+        else if (outcome.kind === "reverted") {
+            console.log(`reverting ${outcome.version}_${outcome.name}…`);
+            console.log(`  ✓ reverted`);
+        }
+        else {
+            console.error(`reverting ${outcome.version}_${outcome.name}…`);
+            console.error(`  ✗ ${outcome.error}`);
+            exitCode = 1;
+        }
+    }
+    finally {
+        if (locked) {
+            try {
+                await releaseMigrateLock(c, lockKey);
+            }
+            catch (e) {
+                console.warn(`sqlx-js.migrate: failed to release advisory lock: ${e.message}`);
+            }
+        }
+        await c.end();
+    }
+    if (exitCode !== 0)
+        process.exit(exitCode);
+}
+export function migrateAdd(opts) {
+    if (!existsSync(opts.migrationsDir))
+        mkdirSync(opts.migrationsDir, { recursive: true });
+    const existing = readMigrations(opts.migrationsDir);
+    const nextVersion = (existing[existing.length - 1]?.version ?? 0) + 1;
+    const safe = opts.name.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^[^a-zA-Z0-9]+/, "");
+    if (!safe)
+        throw new Error(`sqlx-js.migrate: invalid migration name "${opts.name}"`);
+    const padded = String(nextVersion).padStart(4, "0");
+    const upFname = `${padded}_${safe}.up.sql`;
+    const downFname = `${padded}_${safe}.down.sql`;
+    const upFull = join(opts.migrationsDir, upFname);
+    const downFull = join(opts.migrationsDir, downFname);
+    writeFileSync(upFull, `-- ${opts.name}\n-- write up DDL/DML here\n`);
+    if (!existsSync(downFull)) {
+        writeFileSync(downFull, `-- revert ${opts.name}\n-- write down DDL/DML here\n`);
+    }
+    console.log(`created ${upFull}`);
+    console.log(`created ${downFull}`);
+}

package/dist/src/commands/prepare.d.ts

@@ -0,0 +1,23 @@
+import { PgClient } from "../pg/wire.js";
+import { SchemaCache } from "../pg/schema.js";
+import { type SqlxJsConfig } from "../config.js";
+export type PrepareOptions = {
+    root: string;
+    databaseUrl: string;
+    cacheDir: string;
+    dtsPath: string;
+    check: boolean;
+    prune?: boolean;
+};
+export type PrepareSession = {
+    client: PgClient;
+    schema: SchemaCache;
+    userCfg: SqlxJsConfig;
+};
+export declare function openSession(opts: PrepareOptions): Promise<PrepareSession>;
+export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void): Promise<{
+    entries: number;
+    failures: number;
+    pruned: number;
+}>;
+export declare function runPrepare(opts: PrepareOptions): Promise<void>;

package/dist/src/commands/prepare.js

@@ -0,0 +1,314 @@
+import { PgClient, parseDatabaseUrl, PgError } from "../pg/wire.js";
+import { SchemaCache } from "../pg/schema.js";
+import { analyzeQuery } from "../pg/analyze.js";
+import { isBuiltinOid, oidToTs } from "../pg/oids.js";
+import { scanProject } from "../scan/scanner.js";
+import { Cache, fingerprint, effectiveNullable } from "../cache.js";
+import { emitDts } from "../codegen.js";
+import { loadConfig, lookupJsonbType } from "../config.js";
+import { buildParamMap } from "../pg/param-map.js";
+import { mergeExtensionTypes } from "../pg/extensions.js";
+const JSON_OIDS = new Set([114, 3802]);
+const JSON_ARRAY_OIDS = new Set([199, 3807]);
+function enumUnion(values) {
+    if (values.length === 0)
+        return "never";
+    return values.map((v) => JSON.stringify(v)).join(" | ");
+}
+function resolveTs(oid, customLookup) {
+    const c = customLookup(oid);
+    if (c) {
+        if (c.kind === "enum")
+            return enumUnion(c.values);
+        if (c.kind === "enumArray")
+            return `(${enumUnion(c.element.values)})[]`;
+        if (c.kind === "scalar")
+            return c.tsType;
+        if (c.kind === "scalarArray")
+            return `(${c.element.tsType})[]`;
+    }
+    return oidToTs(oid).ts;
+}
+function resolveColumnTs(f, schema, cfg) {
+    if (f.tableOid !== 0 && f.columnAttr !== 0) {
+        const tbl = schema.tableNameByOid(f.tableOid);
+        const colName = schema.columnNameByAttno(f.tableOid, f.columnAttr);
+        if (tbl && colName) {
+            if (JSON_OIDS.has(f.typeOid)) {
+                const decl = lookupJsonbType(cfg, tbl.schema, tbl.name, colName);
+                if (decl)
+                    return decl;
+            }
+            if (JSON_ARRAY_OIDS.has(f.typeOid)) {
+                const decl = lookupJsonbType(cfg, tbl.schema, tbl.name, colName);
+                if (decl)
+                    return `(${decl})[]`;
+            }
+        }
+    }
+    return resolveTs(f.typeOid, (oid) => schema.customType(oid));
+}
+function resolveParamTs(paramIndex, paramOid, paramMap, schema, cfg) {
+    if (JSON_OIDS.has(paramOid) || JSON_ARRAY_OIDS.has(paramOid)) {
+        const target = paramMap.get(paramIndex);
+        if (target) {
+            const decl = lookupJsonbType(cfg, target.schema ?? "public", target.table, target.column);
+            if (decl)
+                return JSON_ARRAY_OIDS.has(paramOid) ? `(${decl})[]` : decl;
+        }
+    }
+    return resolveTs(paramOid, (oid) => schema.customType(oid));
+}
+function resolveParamNullable(paramIndex, pm, schema) {
+    if (pm.forceNullable.has(paramIndex))
+        return true;
+    if (pm.dmlBound.has(paramIndex)) {
+        const t = pm.targets.get(paramIndex);
+        if (!t)
+            return false;
+        const oid = schema.resolveTable(t.schema, t.table);
+        if (oid === undefined)
+            return false;
+        const col = schema.columnsOf(oid)?.get(t.column);
+        if (!col)
+            return false;
+        return !col.notNull;
+    }
+    return false;
+}
+const ALIAS_OVERRIDE = /^(.+?)([!?])$/;
+function parseColumnOverride(name) {
+    const m = ALIAS_OVERRIDE.exec(name);
+    if (!m)
+        return { name };
+    return { name: m[1], override: m[2] === "!" ? "non-null" : "nullable" };
+}
+function isAliasOrExpression(f, schema) {
+    if (f.tableOid === 0 || f.columnAttr === 0)
+        return true;
+    const real = schema.columnNameByAttno(f.tableOid, f.columnAttr);
+    return real !== undefined && real !== f.name;
+}
+function formatSite(s) {
+    return `${s.file}:${s.line}:${s.column}`;
+}
+function snippet(query, max = 80) {
+    const oneLine = query.replace(/\s+/g, " ").trim();
+    return oneLine.length > max ? oneLine.slice(0, max) + "…" : oneLine;
+}
+export async function openSession(opts) {
+    const userCfg = await loadConfig(opts.root);
+    const cfg = parseDatabaseUrl(opts.databaseUrl);
+    const client = new PgClient(cfg);
+    await client.connect();
+    const schema = new SchemaCache(client);
+    schema.setTypeRegistry(mergeExtensionTypes(userCfg.customTypes));
+    return { client, schema, userCfg };
+}
+export async function prepareOnce(opts, session, log = console.log, err = console.error) {
+    const sites = scanProject(opts.root);
+    log(`scanned: found ${sites.length} sql() call site(s)`);
+    const cache = new Cache(opts.cacheDir);
+    const unique = new Map();
+    for (const s of sites) {
+        const fp = fingerprint(s.query);
+        const existing = unique.get(fp);
+        if (existing)
+            existing.sites.push(s);
+        else
+            unique.set(fp, { fp, query: s.query, sites: [s] });
+    }
+    const raw = [];
+    let failures = 0;
+    const { client, schema, userCfg } = session;
+    for (const { fp, query, sites: ss } of unique.values()) {
+        const site = ss[0];
+        try {
+            const d = await client.describe(query);
+            raw.push({ fp, query, sites: ss, paramOids: d.paramOids, fields: d.fields });
+        }
+        catch (e) {
+            failures++;
+            if (e instanceof PgError) {
+                const extras = [];
+                if (e.position)
+                    extras.push(`pos ${e.position}`);
+                if (e.code)
+                    extras.push(`code ${e.code}`);
+                const tail = extras.length > 0 ? ` (${extras.join(", ")})` : "";
+                err(`  ✗ ${formatSite(site)} — describe failed: ${e.message}${tail}`);
+                if (e.hint)
+                    err(`      hint: ${e.hint}`);
+                err(`      query: ${snippet(query)}`);
+            }
+            else {
+                err(`  ✗ ${formatSite(site)} — describe failed: ${e.message}`);
+                err(`      query: ${snippet(query)}`);
+            }
+        }
+    }
+    const allAttrRefs = [];
+    const allTableOids = [];
+    for (const r of raw) {
+        for (const f of r.fields) {
+            if (f.tableOid !== 0 && f.columnAttr !== 0) {
+                allAttrRefs.push({ tableOid: f.tableOid, attno: f.columnAttr });
+                allTableOids.push(f.tableOid);
+            }
+        }
+    }
+    await schema.loadAttributes(allAttrRefs);
+    await schema.loadTableNamesByOid(allTableOids);
+    const analyses = new Map();
+    const paramMaps = new Map();
+    const failedFps = new Set();
+    for (const r of raw) {
+        const site = r.sites[0];
+        try {
+            analyses.set(r.fp, await analyzeQuery(r.query, r.fields, schema));
+        }
+        catch (e) {
+            failures++;
+            failedFps.add(r.fp);
+            err(`  ✗ ${formatSite(site)} — analyze failed: ${e.message}`);
+            err(`      query: ${snippet(r.query)}`);
+            continue;
+        }
+        try {
+            paramMaps.set(r.fp, await buildParamMap(r.query));
+        }
+        catch (e) {
+            failures++;
+            failedFps.add(r.fp);
+            err(`  ✗ ${formatSite(site)} — paramMap failed: ${e.message}`);
+            err(`      query: ${snippet(r.query)}`);
+        }
+    }
+    const dmlTablesToLoad = new Set();
+    for (const pm of paramMaps.values()) {
+        for (const idx of pm.dmlBound) {
+            const t = pm.targets.get(idx);
+            if (t)
+                dmlTablesToLoad.add(`${t.schema ?? "public"}.${t.table}`);
+        }
+    }
+    if (dmlTablesToLoad.size > 0) {
+        const names = [...dmlTablesToLoad].map((k) => {
+            const [schema, name] = k.split(".");
+            return { schema, name: name };
+        });
+        await schema.loadTableNames(names);
+        const oids = [];
+        for (const n of names) {
+            const oid = schema.resolveTable(n.schema, n.name);
+            if (oid !== undefined)
+                oids.push(oid);
+        }
+        await schema.loadColumnsForTables(oids);
+    }
+    const unknownOids = new Set();
+    for (const r of raw) {
+        for (const o of r.paramOids)
+            if (!isBuiltinOid(o))
+                unknownOids.add(o);
+        for (const f of r.fields)
+            if (!isBuiltinOid(f.typeOid))
+                unknownOids.add(f.typeOid);
+    }
+    await schema.loadCustomTypes([...unknownOids]);
+    const entries = [];
+    for (const r of raw) {
+        if (failedFps.has(r.fp))
+            continue;
+        const analysis = analyses.get(r.fp);
+        const pm = paramMaps.get(r.fp) ?? {
+            targets: new Map(),
+            forceNullable: new Set(),
+            dmlBound: new Set(),
+        };
+        const fileSites = r.sites.filter((s) => s.kind === "file");
+        const hasInline = r.sites.some((s) => s.kind !== "file");
+        const filePaths = fileSites.length > 0
+            ? Array.from(new Set(fileSites.map((s) => s.sqlFilePath))).sort()
+            : undefined;
+        const entry = {
+            query: r.query,
+            paramOids: r.paramOids,
+            paramTsTypes: r.paramOids.map((o, idx) => resolveParamTs(idx + 1, o, pm.targets, schema, userCfg)),
+            paramNullable: r.paramOids.map((_o, idx) => resolveParamNullable(idx + 1, pm, schema)),
+            columns: r.fields.map((f, i) => {
+                const parsed = parseColumnOverride(f.name);
+                const treatAsOverride = parsed.override !== undefined && isAliasOrExpression(f, schema);
+                return {
+                    name: parsed.name,
+                    typeOid: f.typeOid,
+                    tsType: resolveColumnTs(f, schema, userCfg),
+                    nullable: analysis.perColumnNullable[i] ?? true,
+                    ...(treatAsOverride ? { override: parsed.override } : {}),
+                };
+            }),
+            hasResultSet: r.fields.length > 0,
+            hasInline,
+            ...(filePaths ? { filePaths } : {}),
+            ...(analysis.degraded ? { degraded: analysis.degraded } : {}),
+        };
+        cache.write(r.fp, entry);
+        entries.push(entry);
+        const nn = entry.columns.filter((c) => !effectiveNullable(c)).length;
+        const tag = entry.degraded ? ` [degraded: ${entry.degraded.reason}]` : "";
+        log(`  ✓ ${formatSite(r.sites[0])} → ${r.paramOids.length} param(s), ${r.fields.length} col(s) [${nn} non-null]${tag}`);
+    }
+    let pruned = 0;
+    if (opts.prune !== false) {
+        pruned = cache.prune(unique.keys()).length;
+        if (pruned > 0)
+            log(`pruned ${pruned} orphaned cache entry/entries`);
+    }
+    emitDts(opts.dtsPath, entries);
+    return { entries: entries.length, failures, pruned };
+}
+export async function runPrepare(opts) {
+    if (opts.check) {
+        const sites = scanProject(opts.root);
+        console.log(`scanned: found ${sites.length} sql() call site(s)`);
+        const cache = new Cache(opts.cacheDir);
+        const unique = new Map();
+        for (const s of sites) {
+            const fp = fingerprint(s.query);
+            const existing = unique.get(fp);
+            if (existing)
+                existing.sites.push(s);
+            else
+                unique.set(fp, { fp, query: s.query, sites: [s] });
+        }
+        let stale = 0;
+        for (const { fp, query, sites: ss } of unique.values()) {
+            if (!cache.has(fp)) {
+                stale++;
+                console.error(`stale: ${formatSite(ss[0])} — query not in cache`);
+                console.error(`       query: ${snippet(query)}`);
+            }
+        }
+        if (stale > 0) {
+            console.error(`\nsqlx-js prepare --check: ${stale} stale/missing entries. Run \`sqlx-js prepare\` against a live DB.`);
+            process.exit(1);
+        }
+        const entries = [...unique.values()].map((u) => cache.read(u.fp)).filter(Boolean);
+        emitDts(opts.dtsPath, entries);
+        console.log(`ok — ${entries.length} unique queries, types regenerated`);
+        return;
+    }
+    const session = await openSession(opts);
+    try {
+        const r = await prepareOnce(opts, session);
+        if (r.failures > 0) {
+            console.error(`\n${r.failures} query/queries failed to prepare`);
+            await session.client.end();
+            process.exit(1);
+        }
+        console.log(`\nprepared ${r.entries} unique query/queries → ${opts.dtsPath}`);
+    }
+    finally {
+        await session.client.end();
+    }
+}

package/dist/src/commands/schema.d.ts

@@ -0,0 +1,14 @@
+export type SchemaCommandOptions = {
+    databaseUrl: string;
+    snapshotPath: string;
+    manifestPath: string;
+    writeManifest: boolean;
+    shadowUrl?: string;
+    migrationsDir: string;
+};
+export type ShadowMigrationResult = {
+    applied: number;
+};
+export declare function applyShadowMigrations(databaseUrl: string, migrationsDir: string, log?: (msg: string) => void): Promise<ShadowMigrationResult>;
+export declare function runSchemaDump(opts: SchemaCommandOptions): Promise<void>;
+export declare function runSchemaCheck(opts: SchemaCommandOptions): Promise<void>;