backupdrill 2.6.0 → 2.7.1

package/dist/external-refs.js

@@ -0,0 +1,435 @@
+// 指向备份之外的外键:恢复前查目标库里有没有被引用的行。
+//
+// 触因(2026-10-22 实验):只备 public 的快照,profiles.id 外键指向 auth.users。演练沙箱没有
+// auth.users,这条外键被归为托管对象跳过,演练 PASS;dry-run 只拿 manifest 对目标环境,
+// 根本不看 dump,也过了;恢复到新 Supabase 项目时 auth.users 在、但一行都没有,
+// ADD CONSTRAINT 校验已有行失败。外键定义和引用方的数据都只在 dump 里,所以这项检查必须读 dump。
+//
+// 只查"会校验已有行"的外键(NOT VALID / NOT ENFORCED 的恢复时不校验),只查被引用表在
+// 备份之外的(备份之内的表和数据一起恢复,天然对得上)。
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { MAX_COPY_HEADER, decodeCopyField, formatQualified, parseCopyHeader, parseForeignKeys, parsePartitionAttachments, parseTableColumns, } from "./dump-sql.js";
+import { libpqChildEnv, pgRestoreOutput, quoteIdent } from "./restore-engine.js";
+import { resolvePgRestoreBin } from "./pgbin.js";
+import { connectPg } from "./supabase-ca.js";
+/** 一批最多带多少个不同的键去目标库查。uuid 键一批约 200 KB 参数,目标端一次反连接。 */
+const KEY_BATCH = 5000;
+const keyOf = (name) => `${name.schema}\u0000${name.name}`;
+/**
+ * 读 dump,找出指向 dumpedSchemas 之外的外键,逐条拿目标库对行。只读:目标库上只跑 select。
+ * pg_restore 起不来、归档读不了时抛错,由调用方当成 blocker。单条外键查不成(目标端报错、
+ * 数据块读不了)只影响它自己,记进 unchecked,不拖累别的外键的结论。
+ */
+export async function checkExternalReferences(opts) {
+    const bin = resolvePgRestoreBin();
+    const result = { checked: [], problems: [], unchecked: [], waitingForExtensions: false };
+    const listing = await pgRestoreOutput(bin, ["--list", opts.dumpPath]);
+    if (listing.code !== 0)
+        throw new Error(`pg_restore --list exited with code ${listing.code}: ${oneLine(listing.stderr)}`);
+    const entries = listing.stdout.split("\n");
+    const fkEntries = entries.filter((line) => /^\d+; \d+ \d+ FK CONSTRAINT /.test(line));
+    if (!fkEntries.length)
+        return result;
+    const attachEntries = entries.filter((line) => /^\d+; \d+ \d+ TABLE ATTACH /.test(line));
+    // 建表语句:比较时要用引用方列的类型
+    const tableEntries = entries.filter((line) => /^\d+; \d+ \d+ TABLE (?!DATA |ATTACH )/.test(line));
+    const listDir = await mkdtemp(join(tmpdir(), "backupdrill-refs-"));
+    let definitions;
+    try {
+        const listFile = join(listDir, "fk.list");
+        await writeFile(listFile, [...tableEntries, ...fkEntries, ...attachEntries].join("\n") + "\n");
+        const ddl = await pgRestoreOutput(bin, ["-f", "-", `--use-list=${listFile}`, opts.dumpPath]);
+        if (ddl.code !== 0)
+            throw new Error(`pg_restore exited with code ${ddl.code}: ${oneLine(ddl.stderr)}`);
+        definitions = ddl.stdout;
+    }
+    finally {
+        await rm(listDir, { recursive: true, force: true });
+    }
+    const foreignKeys = parseForeignKeys(definitions);
+    if (foreignKeys.length < fkEntries.length) {
+        result.unchecked.push(`${fkEntries.length - foreignKeys.length} foreign key definition(s) in the dump are in a form this check can't read`);
+    }
+    const dumped = new Set(opts.dumpedSchemas);
+    const external = foreignKeys.filter((fk) => !dumped.has(fk.references.schema) && fk.validatesRows);
+    if (!external.length)
+        return result;
+    // 分区父表上的外键,数据在各级叶子分区里(dump 只给叶子写 COPY)
+    const children = new Map();
+    for (const { parent, child } of parsePartitionAttachments(definitions)) {
+        children.set(keyOf(parent), [...(children.get(keyOf(parent)) ?? []), child]);
+    }
+    const leavesOf = (table) => {
+        const below = children.get(keyOf(table)) ?? [];
+        return below.length ? below.flatMap(leavesOf) : [table];
+    };
+    const pending = opts.pendingExtensions ?? [];
+    const waitForExtensions = (fk, what) => {
+        result.waitingForExtensions = true;
+        result.unchecked.push(`${describe(fk)}: ${what}; extension(s) ${pending.join(", ")} that the restore installs first may provide it, ` +
+            `so it is checked after they are installed`);
+    };
+    const tableColumns = parseTableColumns(definitions);
+    const client = opts.inTransaction ?? (await connectPg(opts.targetUrl));
+    if (opts.inTransaction)
+        insideCallerTransaction.add(client);
+    try {
+        const scans = [];
+        for (const fk of external) {
+            let lookup;
+            try {
+                lookup = await comparisonPlan(client, fk, tableColumns.get(keyOf(fk.table)));
+            }
+            catch (error) {
+                result.unchecked.push(`${describe(fk)}: could not look up ${formatQualified(fk.references)} on the target (${error.message})`);
+                continue;
+            }
+            if ("unchecked" in lookup) {
+                if (lookup.typeMissing && pending.length)
+                    waitForExtensions(fk, lookup.unchecked);
+                else
+                    result.unchecked.push(`${describe(fk)}: ${lookup.unchecked}`);
+                continue;
+            }
+            if ("problem" in lookup) {
+                if (lookup.tableMissing && pending.length) {
+                    waitForExtensions(fk, `${formatQualified(fk.references)} isn't on the target yet`);
+                }
+                else {
+                    result.problems.push(`${describe(fk)}: ${lookup.problem}`);
+                }
+                continue;
+            }
+            const checked = { fk, rows: 0, missingRows: 0 };
+            result.checked.push(checked);
+            scans.push({ checked, comparisons: lookup.comparisons, only: lookup.only, leaves: new Set(leavesOf(fk.table).map(keyOf)), seen: new Set(), batch: new Map() });
+        }
+        if (scans.length) {
+            try {
+                await scanDumpData(bin, opts.dumpPath, scans, client);
+            }
+            catch (error) {
+                for (const scan of scans)
+                    scan.failed ??= `could not read the dump's data (${error.message})`;
+            }
+            for (const scan of scans) {
+                const unseen = [...scan.leaves].filter((table) => !scan.seen.has(table));
+                if (!scan.failed && unseen.length) {
+                    const names = unseen.map((key) => {
+                        const [schema, name] = key.split("\u0000");
+                        return formatQualified({ schema, name });
+                    });
+                    scan.failed = `could not read the dumped data of ${names.join(", ")}`;
+                }
+                const { fk, rows, missingRows } = scan.checked;
+                if (missingRows > 0) {
+                    // 已经确认缺的行是事实,后面查不下去也不能把它吞掉
+                    result.problems.push(scan.failed
+                        ? `${describe(fk)}: at least ${missingRows.toLocaleString("en-US")} row(s) point at ` +
+                            `${formatQualified(fk.references)} rows the target doesn't have (the check stopped early: ${scan.failed})`
+                        : `${describe(fk)}: ${missingRows.toLocaleString("en-US")} of ${rows.toLocaleString("en-US")} row(s) ` +
+                            `point at ${formatQualified(fk.references)} rows the target doesn't have`);
+                }
+                else if (scan.failed) {
+                    result.unchecked.push(`${describe(fk)}: ${scan.failed}`);
+                    result.checked = result.checked.filter((c) => c !== scan.checked);
+                }
+            }
+        }
+    }
+    finally {
+        if (opts.inTransaction)
+            insideCallerTransaction.delete(client);
+        else
+            await client.end();
+    }
+    return result;
+}
+export function describe(fk) {
+    return `${formatQualified(fk.table)} → ${formatQualified(fk.references)} (${fk.constraint})`;
+}
+/**
+ * 目标端的查询一律放进只读事务,查完回滚:dry-run 承诺零写入,而类型转换、域约束、自定义相等
+ * 运算符都能调用户函数(交叉审查第二轮复现过域 CHECK 写审计表)。每条语句各开一个事务,
+ * 一条出错不会让后面的查询跟着报 "current transaction is aborted"。
+ */
+/** 用的是调用方事务的连接:不能另开事务,改用保存点,查完回滚到保存点(写了什么都撤掉)。 */
+const insideCallerTransaction = new WeakSet();
+async function readOnly(client, sql, params) {
+    if (insideCallerTransaction.has(client)) {
+        await client.query("savepoint backupdrill_check");
+        try {
+            // 保存点里也设成只读:回滚到保存点撤不掉序列的 nextval/setval(交叉审查复现),只读才拦得住;
+            // 这个设置随保存点一起撤销,外层事务照样能提交扩展
+            await client.query("set local transaction_read_only = on");
+            await client.query("set local row_security = off");
+            return await client.query(sql, params);
+        }
+        finally {
+            // 回滚之后保存点还在,不 release 的话每条查询都往里套一层
+            await client.query("rollback to savepoint backupdrill_check").catch(() => { });
+            await client.query("release savepoint backupdrill_check").catch(() => { });
+        }
+    }
+    await client.query("begin transaction read only");
+    try {
+        // 外键校验看得到被 RLS 藏起来的行,我们的查询看不到:关掉行级安全,真被它影响时 Postgres 直接报错
+        // (算"没查成"),而不是悄悄少返回几行、把存在的行报成缺(推送前审查)
+        await client.query("set local row_security = off");
+        return await client.query(sql, params);
+    }
+    finally {
+        await client.query("rollback").catch(() => { });
+    }
+}
+/**
+ * 拿来写 `::类型` 的名字。format_type 给 bpchar 和 bit 的是 character / bit,写进转换里就成了
+ * char(1) / bit(1),值被截成一位(交叉审查复现:ABCD 和 AXYZ 被当成同一个键)。这两个换成不带长度的写法。
+ */
+const CAST_NAME = (oid) => `case ${oid}
+    when 'pg_catalog.bpchar'::regtype then 'pg_catalog.bpchar'
+    when 'pg_catalog._bpchar'::regtype then 'pg_catalog.bpchar[]'
+    when 'pg_catalog.bit'::regtype then 'pg_catalog.varbit'
+    when 'pg_catalog._bit'::regtype then 'pg_catalog.varbit[]'
+    else format_type(${oid}, null) end`;
+/**
+ * 照外键自己的做法定比较方式(ATAddForeignKeyConstraint):找被引用列上那个唯一索引,取它每列的
+ * 运算符族,在族里找 (索引输入类型, 引用方类型) 的相等运算符;找不到而引用方类型能隐式转成索引输入
+ * 类型时,用 (输入类型, 输入类型) 那个。运算符带 schema 写死:裸 `=` 在 search_path 里看不到
+ * extensions 时会把 citext 解析成 text 的相等,大小写不同的值就被误报成缺(交叉审查复现)。
+ * 引用方列的类型从 dump 的建表语句读,值本来就出自这一列。
+ * 被引用的表、列、唯一索引不在时返回 problem(建外键必然失败);其余没法照做的报 unchecked。
+ */
+async function comparisonPlan(client, fk, columnsInDump) {
+    const relation = `${quoteIdent(fk.references.schema)}.${quoteIdent(fk.references.name)}`;
+    const exists = await readOnly(client, "select to_regclass($1)::oid as oid, (select relkind from pg_class where oid = to_regclass($1)) as kind", [relation]);
+    const relid = exists.rows[0].oid;
+    if (!relid) {
+        return { problem: `${formatQualified(fk.references)} does not exist on the target`, tableMissing: true };
+    }
+    const attributes = await readOnly(client, `select a.attname as name, a.attnum::int as num from pg_attribute a
+      where a.attrelid = $1::oid and a.attnum > 0 and not a.attisdropped and a.attname = any($2::text[])`, [relid, fk.referencedColumns]);
+    const attnum = new Map(attributes.rows.map((row) => [row.name, row.num]));
+    const absent = fk.referencedColumns.filter((name) => !attnum.has(name));
+    if (absent.length) {
+        return { problem: `${formatQualified(fk.references)} on the target has no column(s) ${absent.join(", ")}`, tableMissing: false };
+    }
+    // 外键要求被引用列上有一个恰好覆盖这几列的唯一索引(顺序不限),而且不能是可延迟的(indimmediate)
+    const indexes = await readOnly(client, `select i.indkey::text as keys, i.indclass::text as classes, i.indnkeyatts::int as nkeys from pg_index i
+      where i.indrelid = $1::oid and i.indisunique and i.indimmediate and i.indisvalid
+        and i.indpred is null and i.indexprs is null`, [relid]);
+    const wanted = fk.referencedColumns.map((name) => attnum.get(name)).sort((a, b) => a - b).join(" ");
+    const index = indexes.rows
+        .map((row) => ({ keys: row.keys.split(" ").slice(0, row.nkeys).map(Number), classes: row.classes.split(" ") }))
+        .find((row) => [...row.keys].sort((a, b) => a - b).join(" ") === wanted);
+    if (!index) {
+        return {
+            problem: `${formatQualified(fk.references)} on the target has no unique index on (${fk.referencedColumns.join(", ")}), so the foreign key can't be created`,
+            tableMissing: false,
+        };
+    }
+    const comparisons = [];
+    for (let i = 0; i < fk.columns.length; i++) {
+        const column = fk.columns[i];
+        const declared = columnsInDump?.get(column);
+        if (!declared)
+            return { unchecked: `could not read the type of column ${column} from the dump` };
+        const fkType = await readOnly(client, 
+        // 域按外键的做法换成底层类型(可以多层嵌套)
+        `with recursive t(oid, base, depth) as (
+         select to_regtype($1)::oid, to_regtype($1)::oid, 0
+         union all
+         select t.oid, ty.typbasetype, t.depth + 1 from t join pg_type ty on ty.oid = t.base
+          where ty.typtype = 'd' and t.depth < 20)
+       select oid::text as oid, base::text as base, ${CAST_NAME("base")} as name from t order by depth desc limit 1`, [declared]);
+        const fkBase = fkType.rows[0]?.base;
+        if (!fkType.rows[0]?.oid || !fkBase) {
+            return { unchecked: `column ${column} uses type ${declared}, which is missing on the target`, typeMissing: true };
+        }
+        const opclass = index.classes[index.keys.indexOf(attnum.get(fk.referencedColumns[i]))];
+        // 先找 (输入类型, 引用方类型);没有就看能不能隐式转成输入类型,用 (输入类型, 输入类型)
+        const operator = await readOnly(client, `select n.nspname as schema, o.oprname as name,
+              ${CAST_NAME("o.oprright")} as right, o.oprright <> $2::oid as coerced
+         from pg_opclass oc
+         join pg_amop am on am.amopfamily = oc.opcfamily and am.amoplefttype = oc.opcintype and am.amopstrategy = 3
+         join pg_operator o on o.oid = am.amopopr
+         join pg_namespace n on n.oid = o.oprnamespace
+        where oc.oid = $1::oid
+          and (am.amoprighttype = $2::oid
+               or (am.amoprighttype = oc.opcintype
+                   and not exists (select 1 from pg_amop x where x.amopfamily = oc.opcfamily and x.amoplefttype = oc.opcintype
+                                     and x.amoprighttype = $2::oid and x.amopstrategy = 3)
+                   and exists (select 1 from pg_cast c where c.castsource = $2::oid and c.casttarget = oc.opcintype
+                                 and c.castcontext = 'i')))
+        order by (am.amoprighttype = $2::oid) desc limit 1`, [opclass, fkBase]);
+        const op = operator.rows[0];
+        if (!op) {
+            return { unchecked: `can't tell how the foreign key would compare ${declared} with ${formatQualified(fk.references)}.${fk.referencedColumns[i]}` };
+        }
+        // 运算符名只由符号组成(系统表保证),schema 照常加引号
+        comparisons.push({
+            referencedColumn: fk.referencedColumns[i],
+            operator: `OPERATOR(${quoteIdent(op.schema)}.${op.name})`,
+            rightCast: op.coerced ? `${fkType.rows[0].name}::${op.right}` : op.right,
+        });
+    }
+    // 普通表的外键只认它自己的行,继承出来的子表里的行不算(查 ONLY);分区表的行都在分区里,不能加 ONLY
+    return { comparisons, only: exists.rows[0].kind !== "p" };
+}
+/**
+ * 把需要的表的数据从 dump 里流出来(pg_restore --data-only -f -),按 COPY 块分发给各条外键。
+ * 流式读,内存只占一批键。-n/-t 在 pg_restore 里是精确名字匹配、两者取交集,
+ * 多选出来的表按 COPY 头里的全名再筛一遍。
+ */
+async function scanDumpData(bin, dumpPath, scans, client) {
+    const wanted = new Map();
+    const schemas = new Set();
+    const names = new Set();
+    for (const scan of scans) {
+        for (const table of scan.leaves) {
+            wanted.set(table, [...(wanted.get(table) ?? []), scan]);
+            const [schema, name] = table.split("\u0000");
+            schemas.add(schema);
+            names.add(name);
+        }
+    }
+    const args = ["--data-only", "-f", "-"];
+    for (const schema of schemas)
+        args.push("-n", schema);
+    for (const name of names)
+        args.push("-t", name);
+    args.push(dumpPath);
+    const proc = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], env: libpqChildEnv() });
+    let stderr = "";
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+    const exited = new Promise((resolve, reject) => {
+        proc.on("error", (error) => reject(new Error(`${bin} failed to start: ${error.code ?? error.message}`)));
+        proc.on("close", resolve);
+    });
+    exited.catch(() => { });
+    const flush = async (scan) => {
+        if (!scan.batch.size || scan.failed)
+            return;
+        const entries = [...scan.batch.values()];
+        scan.batch.clear();
+        try {
+            const missing = await missingKeyIndexes(client, scan.checked.fk, scan.comparisons, scan.only, entries.map((e) => e.key));
+            for (const index of missing)
+                scan.checked.missingRows += entries[index - 1].rows;
+        }
+        catch (error) {
+            // 只停这一条外键:比如值转不成被引用列的类型
+            scan.failed = `could not compare its rows on the target (${error.message})`;
+        }
+    };
+    // 当前 COPY 块里每条外键要取的列下标;null = 不在 COPY 块里,[] = 在一个不需要的块里
+    let current = null;
+    // 带引号的名字里可以有换行,COPY 头就会跨行:攒到引号配平、以 FROM stdin; 结尾为止
+    let header = null;
+    const openHeader = (text) => {
+        const parsed = parseCopyHeader(text);
+        current = [];
+        if (!parsed)
+            return; // 读不了的块整块跳过;它的表没记成 seen,最后会报没查成
+        const consumers = wanted.get(keyOf(parsed.table)) ?? [];
+        for (const scan of consumers) {
+            scan.seen.add(keyOf(parsed.table));
+            const indexes = scan.checked.fk.columns.map((column) => parsed.columns.indexOf(column));
+            if (indexes.some((i) => i < 0)) {
+                // 生成列不进 COPY
+                scan.failed ??= `column(s) ${scan.checked.fk.columns.join(", ")} are not in the dumped data of ${formatQualified(parsed.table)}`;
+                continue;
+            }
+            current.push({ scan, indexes });
+        }
+    };
+    const onLine = (line) => {
+        if (current === null) {
+            if (header === null && !line.startsWith("COPY "))
+                return;
+            header = header === null ? line : `${header}\n${line}`;
+            const quotes = header.split('"').length - 1;
+            if ((quotes % 2 === 0 && header.endsWith(" FROM stdin;")) || header.length > MAX_COPY_HEADER) {
+                openHeader(header);
+                header = null;
+            }
+            return;
+        }
+        if (line === "\\.") {
+            current = null;
+            return;
+        }
+        if (!current.length)
+            return;
+        const fields = line.split("\t");
+        let full = null;
+        for (const { scan, indexes } of current) {
+            if (scan.failed)
+                continue;
+            const key = indexes.map((i) => (i < fields.length ? decodeCopyField(fields[i]) : null));
+            if (key.some((value) => value === null))
+                continue;
+            scan.checked.rows += 1;
+            const id = JSON.stringify(key);
+            const seen = scan.batch.get(id);
+            if (seen)
+                seen.rows += 1;
+            else
+                scan.batch.set(id, { key: key, rows: 1 });
+            if (scan.batch.size >= KEY_BATCH)
+                (full ??= []).push(scan);
+        }
+        // 一个接一个查:几条外键共用一条连接,同时开事务会互相串(一条报错把另一条的查询也拖成 aborted)
+        if (full) {
+            const ready = full;
+            return ready.reduce((chain, scan) => chain.then(() => flush(scan)), Promise.resolve());
+        }
+    };
+    try {
+        const decoder = new StringDecoder("utf8");
+        let carry = "";
+        // for await 读 stdout 自带背压:查库的时候 pg_restore 停着等
+        for await (const chunk of proc.stdout) {
+            const lines = (carry + decoder.write(chunk)).split("\n");
+            carry = lines.pop();
+            for (const line of lines) {
+                const wait = onLine(line);
+                if (wait)
+                    await wait;
+            }
+        }
+        carry += decoder.end();
+        if (carry)
+            await onLine(carry);
+        for (const scan of scans)
+            await flush(scan);
+    }
+    finally {
+        if (proc.exitCode === null)
+            proc.kill();
+    }
+    const code = await exited;
+    if (code !== 0)
+        throw new Error(`pg_restore exited with code ${code}: ${oneLine(stderr)}`);
+}
+/** 一批键里哪些在被引用表里找不到;返回 1 起的下标。比较方式见 comparisonPlan。 */
+async function missingKeyIndexes(client, fk, comparisons, only, keys) {
+    const aliases = comparisons.map((_, i) => `c${i}`);
+    const sql = `select k.i::int as i from unnest(${comparisons.map((_, i) => `$${i + 1}::text[]`).join(", ")}) ` +
+        `with ordinality as k(${aliases.join(", ")}, i) ` +
+        `where not exists (select 1 from ${only ? "only " : ""}${quoteIdent(fk.references.schema)}.${quoteIdent(fk.references.name)} r where ` +
+        comparisons
+            // 被引用列不做转换(转成 character / bit 这类名字会截断它);运算符写死了 schema,右边的类型也定了
+            .map((c, i) => `r.${quoteIdent(c.referencedColumn)} ${c.operator} k.${aliases[i]}::${c.rightCast}`)
+            .join(" and ") +
+        `)`;
+    const res = await readOnly(client, sql, comparisons.map((_, i) => keys.map((key) => key[i])));
+    return res.rows.map((row) => row.i);
+}
+function oneLine(text) {
+    return text.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)";
+}

package/dist/index.js

@@ -10,6 +10,7 @@ import { Writable } from "node:stream";
 import { runRestore, NO_SOURCE_DATABASE } from "./restore.js";
 import { recordDrillOutcome } from "./drill-record.js";
 import { DEFAULT_EXPORTER_PORT, startExporter } from "./exporter.js";
+import { exitCleanlyOnSignals, interrupted } from "./interrupt.js";
 /** 隐藏式秘密输入(PRD §5.3.1):终端不回显;无 TTY(CI/脚本)时明确要求走环境变量。 */
 async function promptSecret(label) {
     if (!process.stdin.isTTY) {
@@ -119,6 +120,8 @@ program
     .option("--record", "write the outcome as a small JSON file in <prefix>/<project>.drills/, where " +
     "`backupdrill exporter` reads it. Needs write access to the bucket")
     .action(async (opts) => {
+    // Ctrl+C / SIGTERM:删掉沙箱容器、停掉 --check-cmd 和 pg_restore、删下载的 dump,再以 130/143 退出
+    const stopHandlingSignals = exitCleanlyOnSignals("drill");
     const ping = createPinger(await resolvePingUrl({ flag: opts.pingUrl, configPath: opts.config }));
     await ping.start();
     // config 放在 try 外面:出错时 /fail 要用它抹敏感值,--record 要用它记一笔"没通过"
@@ -148,6 +151,9 @@ program
             appCheckCommand: opts.checkCmd,
             keepSandboxOnFailure: opts.keep,
         });
+        // 被打断的演练不出报告、不 ping、不记录:信号处理在收尾,完了会以 130/143 退出
+        if (interrupted())
+            return;
         console.error("");
         for (const c of report.checks) {
             console.error(`  ${c.pass ? "✓" : "✗"} ${c.name} — ${c.detail}`);
@@ -169,6 +175,8 @@ program
         }
     }
     catch (error) {
+        if (interrupted())
+            return;
         const message = error.message;
         log.error(message);
         process.exitCode = 1;
@@ -177,6 +185,9 @@ program
             await recordDrillOutcome(config, null);
         await ping.fail(`backupdrill ${TOOL_VERSION}: drill failed. ${pingMessageOf(error)}`, sensitiveValuesOf(config));
     }
+    finally {
+        stopHandlingSignals();
+    }
 });
 program
     .command("restore")
@@ -188,7 +199,8 @@ program
     .option("--target-supabase-url <url>", "target project URL (https://<ref>.supabase.co) to upload Storage files into; " +
     "service-role key via env BACKUPDRILL_TARGET_SERVICE_ROLE_KEY or a hidden prompt")
     .option("--confirm-target <ref>", "type the TARGET project ref to confirm writing to it")
-    .option("--dry-run", "run every read-only preflight check and write nothing")
+    .option("--dry-run", "run every read-only preflight check and write nothing (downloads the dump to check it, " +
+    "including foreign keys that point outside the backup)")
     .option("--acknowledge-unverified-source", "proceed although the source identity cannot be verified (legacy snapshot without config) — " +
     "same-source protection is inert; double-check the target first")
     .option("--storage-dir <path>", "local directory to write Storage files to (when not uploading)")

package/dist/interrupt.d.ts

@@ -0,0 +1,28 @@
+import type { ChildProcess } from "node:child_process";
+type Cleanup = () => Promise<void> | void;
+/** 收到过信号没有。主流程据此闭嘴:信号处理正在收尾并会自己退出,别再打印报告、发 ping、写记录。 */
+export declare function interrupted(): boolean;
+/**
+ * 收到信号之后不再开始新的一步(起容器、跑 pg_restore、跑检查命令)。清理在跑的时候主流程还活着,
+ * 一个刚返回的探测会接着往下走:不拦的话,清理快照之后才起的沙箱就没人删了(交叉审查)。
+ */
+export declare function throwIfInterrupted(): void;
+/** 登记一个中断时要跑的清理;返回注销函数,正常走完后调用。 */
+export declare function onInterrupt(cleanup: Cleanup): () => void;
+/**
+ * 中断时停掉一个子进程。先 SIGTERM 给它收尾的机会,2 秒后还在就 SIGKILL。
+ * group:子进程自成进程组(detached,如 --check-cmd),按组发信号,连它派生的进程一起停。
+ * 看的是**整组**还在不在,不是组长:shell 收到 SIGTERM 先退了,忽略 SIGTERM 的孙进程还在,
+ * 只盯组长就会跳过 SIGKILL 把它留下(交叉审查复现)。
+ */
+export declare function stopOnInterrupt(child: ChildProcess, opts?: {
+    group?: boolean;
+}): () => void;
+/**
+ * CLI 专用:在 what(比如 "drill")运行期间接管 SIGINT/SIGTERM。第一次收到信号时跑完登记的清理,
+ * 以 130(SIGINT)/ 143(SIGTERM)退出;清理途中再按一次 Ctrl+C 就不等了,直接退出
+ * (1 秒内重复到达的同一个信号不算,见 REPEATED_SIGNAL_GRACE_MS)。
+ * 返回卸载函数。
+ */
+export declare function exitCleanlyOnSignals(what: string): () => void;
+export {};

package/dist/interrupt.js

@@ -0,0 +1,144 @@
+import { log } from "./log.js";
+const pending = new Set();
+let interruptedBy = null;
+let interruptedAt = 0;
+// npx / npm exec 会把自己收到的 SIGINT/SIGTERM 再转发给 CLI(@npmcli/run-script 的 signal-manager)。
+// 终端里的 Ctrl+C 发给整个前台进程组,所以按一次,CLI 几乎同时收到两次:不挡的话第二次会被当成
+// "再按一次跳过清理",沙箱照样留下。离第一次不到这么久的同一个信号算同一次。
+const REPEATED_SIGNAL_GRACE_MS = 1000;
+/** 收到过信号没有。主流程据此闭嘴:信号处理正在收尾并会自己退出,别再打印报告、发 ping、写记录。 */
+export function interrupted() {
+    return interruptedBy !== null;
+}
+/**
+ * 收到信号之后不再开始新的一步(起容器、跑 pg_restore、跑检查命令)。清理在跑的时候主流程还活着,
+ * 一个刚返回的探测会接着往下走:不拦的话,清理快照之后才起的沙箱就没人删了(交叉审查)。
+ */
+export function throwIfInterrupted() {
+    if (interruptedBy)
+        throw new Error(`${interruptedBy} received; stopping`);
+}
+/** 登记一个中断时要跑的清理;返回注销函数,正常走完后调用。 */
+export function onInterrupt(cleanup) {
+    pending.add(cleanup);
+    return () => {
+        pending.delete(cleanup);
+    };
+}
+/**
+ * 中断时停掉一个子进程。先 SIGTERM 给它收尾的机会,2 秒后还在就 SIGKILL。
+ * group:子进程自成进程组(detached,如 --check-cmd),按组发信号,连它派生的进程一起停。
+ * 看的是**整组**还在不在,不是组长:shell 收到 SIGTERM 先退了,忽略 SIGTERM 的孙进程还在,
+ * 只盯组长就会跳过 SIGKILL 把它留下(交叉审查复现)。
+ */
+export function stopOnInterrupt(child, opts = {}) {
+    const pid = child.pid;
+    // Windows 没有负 pid 的进程组信号,process.kill(-pid) 直接报错:那里退回到只看、只停子进程本身
+    // (和 --check-cmd 超时那条路一样),孙进程可能留下。没在 Windows 上测过
+    const byGroup = opts.group && process.platform !== "win32";
+    const alive = () => {
+        if (!pid)
+            return false;
+        if (!byGroup)
+            return child.exitCode === null && child.signalCode === null;
+        try {
+            process.kill(-pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const signal = (sig) => {
+        try {
+            if (byGroup && pid)
+                process.kill(-pid, sig);
+            else
+                child.kill(sig);
+        }
+        catch {
+            // 已经退出
+        }
+    };
+    const forget = onInterrupt(async () => {
+        if (!alive())
+            return;
+        signal("SIGTERM");
+        const deadline = Date.now() + 2_000;
+        while (alive() && Date.now() < deadline)
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        if (alive())
+            signal("SIGKILL");
+    });
+    // 组长退出时组里可能还有进程:那就继续登记着,中断时照样能按组停掉
+    child.once("close", () => {
+        if (!alive())
+            forget();
+    });
+    return forget;
+}
+/**
+ * 每个清理最多等这么久:docker 守护进程卡住时也要能退出。要比沙箱的收尾(等 docker run 落定 20 秒、
+ * docker rm 最多 60 秒)长,不然收尾还没做完就退出了。
+ */
+const CLEANUP_TIMEOUT_MS = 90_000;
+async function runCleanups() {
+    // 一直跑到没有登记为止:清理途中主流程可能还登记了新东西(比如收到信号时正在返回的 docker run)
+    for (let round = 0; pending.size && round < 10; round++) {
+        const tasks = [...pending].reverse();
+        pending.clear();
+        await runTasks(tasks);
+    }
+}
+async function runTasks(tasks) {
+    for (const task of tasks) {
+        let timer;
+        try {
+            const finished = await Promise.race([
+                Promise.resolve()
+                    .then(task)
+                    .then(() => true),
+                new Promise((resolve) => (timer = setTimeout(() => resolve(false), CLEANUP_TIMEOUT_MS))),
+            ]);
+            if (!finished)
+                log.warn(`a cleanup step did not finish within ${CLEANUP_TIMEOUT_MS / 1000}s; check \`docker ps -a\``);
+        }
+        catch {
+            // 清理函数自己报告失败;一个失败不挡后面的
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * CLI 专用:在 what(比如 "drill")运行期间接管 SIGINT/SIGTERM。第一次收到信号时跑完登记的清理,
+ * 以 130(SIGINT)/ 143(SIGTERM)退出;清理途中再按一次 Ctrl+C 就不等了,直接退出
+ * (1 秒内重复到达的同一个信号不算,见 REPEATED_SIGNAL_GRACE_MS)。
+ * 返回卸载函数。
+ */
+export function exitCleanlyOnSignals(what) {
+    const handler = (signal) => {
+        const code = signal === "SIGINT" ? 130 : 143;
+        if (interruptedBy) {
+            if (signal === interruptedBy && performance.now() - interruptedAt < REPEATED_SIGNAL_GRACE_MS)
+                return;
+            log.error(`${signal} again — exiting without finishing the cleanup`);
+            process.exit(code);
+        }
+        interruptedBy = signal;
+        interruptedAt = performance.now();
+        log.warn(`${signal} received — stopping the ${what} and cleaning up` +
+            (signal === "SIGINT" ? " (press Ctrl+C again to skip)…" : "…"));
+        void runCleanups().finally(() => {
+            log.error(`${what} interrupted`);
+            process.exit(code);
+        });
+    };
+    process.on("SIGINT", handler);
+    process.on("SIGTERM", handler);
+    return () => {
+        process.off("SIGINT", handler);
+        process.off("SIGTERM", handler);
+    };
+}