backupdrill 2.7.0 → 2.7.1

package/dist/drill.d.ts

@@ -60,7 +60,9 @@ export declare function classifyPostDataErrors(stderr: string): PostDataResult;
 /** 兼容层:见 restore-engine.ts finalizePass(非零退出且零错误块 = 通用失败)。 */
 export declare function postDataResult(code: number | null, stderr: string): PostDataResult;
 /** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
-export declare function verifyRestored(connString: string, manifest: Manifest): Promise<{
+export declare function verifyRestored(connString: string, manifest: Manifest, 
+/** 恢复用的那份 dump:恢复出空表时回查它,见第 3 项检查 */
+dumpPath?: string): Promise<{
     checks: DrillCheck[];
     tableCount: number;
     rowTotal: number;

package/dist/drill.js

@@ -7,7 +7,7 @@ import { promisify } from "node:util";
 import { parseManifest } from "./manifest.js";
 import { hashObject } from "./snapshots.js";
 import { s3SnapshotStore } from "./snapshot-store.js";
-import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, installSandboxShim, } from "./restore-engine.js";
+import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, installSandboxShim, tableDataInDump, } from "./restore-engine.js";
 import { connectPg } from "./supabase-ca.js";
 import { localPgRestoreMajor, restoreToolBreaksOnTarget, sandboxMajorFor } from "./pgbin.js";
 import { log } from "./log.js";
@@ -320,7 +320,9 @@ async function pgRestore(dumpPath, connString, dumpedSchemas, jobs) {
 }
 // ── 校验 ────────────────────────────────────────────────────────────
 /** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
-export async function verifyRestored(connString, manifest) {
+export async function verifyRestored(connString, manifest, 
+/** 恢复用的那份 dump:恢复出空表时回查它,见第 3 项检查 */
+dumpPath) {
     // pgConnectOptions:真实 Supabase 目标(restore 复用本函数)需要打包根 CA;
     // 沙箱的 docker 连接串非 Supabase 主机,原样透传,行为不变
     const client = await connectPg(connString);
@@ -383,17 +385,28 @@ export async function verifyRestored(connString, manifest) {
         // 未填充的 matview 豁免:REFRESH 失败已由 post-data 检查裁决(用户对象失败
         // = 演练失败,Supabase 托管依赖 = 预期跳过),这里再报一次会把环境预期
         // 误标成备份损坏。
-        const emptied = manifest.database.tables.filter((t) => t.estimatedRows > 0 &&
+        const restoredEmpty = manifest.database.tables.filter((t) => t.estimatedRows > 0 &&
             !unpopulatedMatviews.has(`${t.schema}.${t.name}`) &&
             (counts.get(`${t.schema}.${t.name}`) ?? 0) === 0);
+        // manifest 的行数是 pg_dump 之前另开连接取的 n_live_tup(统计估算),和 dump 不是同一个快照。
+        // 队列、会话、一次性密钥这类表,取统计时有行、dump 时已经删光,恢复出 0 行是对的
+        // (2026-10-24 生产演练:recovery_job_secrets)。所以拿 dump 本身作证:dump 里也是 0 行才放过,
+        // dump 有行或查不清,照样判失败。
+        const emptyInBackup = [];
+        const emptied = [];
+        for (const t of restoredEmpty) {
+            const inDump = dumpPath ? await tableDataInDump(dumpPath, t.schema, t.name) : "unknown";
+            (inDump === "empty" ? emptyInBackup : emptied).push(t);
+        }
+        const names = (tables) => tables.map((t) => `${t.schema}.${t.name}`).join(", ");
         checks.push({
             name: "populated tables came back",
             pass: emptied.length === 0,
-            detail: emptied.length === 0
-                ? "no populated table restored empty"
-                : `restored empty despite manifest rows: ${emptied
-                    .map((t) => `${t.schema}.${t.name}`)
-                    .join(", ")}`,
+            detail: emptied.length > 0
+                ? `restored empty despite manifest rows: ${names(emptied)}`
+                : emptyInBackup.length > 0
+                    ? `no populated table restored empty (already empty in the backup: ${names(emptyInBackup)})`
+                    : "no populated table restored empty",
         });
         return { checks, tableCount: restoredTables.length, rowTotal };
     }
@@ -600,7 +613,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
                     : "all post-data objects restored",
         });
         await opts.supervision?.observe({ phase: "verify" });
-        const verify = await verifyRestored(pg.connString, manifest);
+        const verify = await verifyRestored(pg.connString, manifest, dumpPath);
         checks.push(...verify.checks);
         // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
         // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。

package/dist/dump-sql.d.ts

@@ -37,6 +37,8 @@ export declare function parsePartitionAttachments(sql: string): Array<{
  * 带引号的列名可以跨行,所以按位置往下读,不按行切。
  */
 export declare function parseTableColumns(sql: string): Map<string, Map<string, string>>;
+/** 一个 COPY 头最长读这么多字符;超过就当作读不了,免得坏归档把内存吃满。 */
+export declare const MAX_COPY_HEADER = 100000;
 /**
  * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
  * 所以那一行中间是两个空格,返回空列表。

package/dist/dump-sql.js

@@ -79,6 +79,8 @@ export function parseTableColumns(sql) {
     }
     return tables;
 }
+/** 一个 COPY 头最长读这么多字符;超过就当作读不了,免得坏归档把内存吃满。 */
+export const MAX_COPY_HEADER = 100_000;
 /**
  * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
  * 所以那一行中间是两个空格,返回空列表。

package/dist/external-refs.js

@@ -12,15 +12,13 @@ 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 { decodeCopyField, formatQualified, parseCopyHeader, parseForeignKeys, parsePartitionAttachments, parseTableColumns, } from "./dump-sql.js";
+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}`;
-/** 一个 COPY 头最长读这么多字符;超过就当作读不了,免得坏归档把内存吃满。 */
-const MAX_COPY_HEADER = 100_000;
 /**
  * 读 dump,找出指向 dumpedSchemas 之外的外键,逐条拿目标库对行。只读:目标库上只跑 select。
  * pg_restore 起不来、归档读不了时抛错,由调用方当成 blocker。单条外键查不成(目标端报错、

package/dist/interrupt.d.ts

@@ -20,7 +20,8 @@ export declare function stopOnInterrupt(child: ChildProcess, opts?: {
 }): () => void;
 /**
  * CLI 专用:在 what(比如 "drill")运行期间接管 SIGINT/SIGTERM。第一次收到信号时跑完登记的清理,
- * 以 130(SIGINT)/ 143(SIGTERM)退出;清理途中再按一次 Ctrl+C 就不等了,直接退出。
+ * 以 130(SIGINT)/ 143(SIGTERM)退出;清理途中再按一次 Ctrl+C 就不等了,直接退出
+ * (1 秒内重复到达的同一个信号不算,见 REPEATED_SIGNAL_GRACE_MS)。
  * 返回卸载函数。
  */
 export declare function exitCleanlyOnSignals(what: string): () => void;

package/dist/interrupt.js

@@ -1,6 +1,11 @@
 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;
@@ -108,17 +113,21 @@ async function runTasks(tasks) {
 }
 /**
  * CLI 专用:在 what(比如 "drill")运行期间接管 SIGINT/SIGTERM。第一次收到信号时跑完登记的清理,
- * 以 130(SIGINT)/ 143(SIGTERM)退出;清理途中再按一次 Ctrl+C 就不等了,直接退出。
+ * 以 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(() => {

package/dist/restore-engine.d.ts

@@ -233,3 +233,20 @@ export declare function restoreDatabaseArtifact(opts: {
     /** pg_restore 并行路数;不传或 ≤1 = 单连接两遍。 */
     jobs?: number;
 }): Promise<EngineResult>;
+/**
+ * 逐块读 `pg_restore --data-only -f -` 的输出,判断某张表的 COPY 段有没有数据行。
+ * 返回一个喂数据的函数:能下结论时返回 "rows" / "empty",确定查不清返回 "unknown",
+ * 还要更多输出返回 null。纯函数,方便单测。
+ *
+ * 只按 \n 切行,不用 readline:readline 把 \r 也当换行(引号名里可以有 \r),还会把一整行数据
+ * 读进内存(大 bytea 行能有几百 MB)。COPY 头之后只看紧跟着的几个字符。
+ * 带引号的名字里还可以有换行(列名里甚至能写 FROM stdin; 和 \.),COPY 头就会跨行:攒到引号配平、
+ * 以 FROM stdin; 结尾为止,再按 COPY 头的语法解析、核对是不是这张表(同 scanDumpData)。
+ */
+export declare function copyDataProbe(schema: string, table: string): (chunk: string) => "rows" | "empty" | "unknown" | null;
+/**
+ * 这张表在 dump 里有没有数据行(判断见 copyDataProbe)。拿到答案就停掉 pg_restore,不读完整份 dump。
+ * 没有 COPY 段(matview 的数据是 REFRESH)、COPY 头读不懂或不是这张表、pg_restore 起不来或出错,
+ * 都返回 "unknown",由调用方按"查不清"处理。
+ */
+export declare function tableDataInDump(dumpPath: string, schema: string, table: string): Promise<"rows" | "empty" | "unknown">;

package/dist/restore-engine.js

@@ -16,7 +16,7 @@ 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 { parseCreateSchemas } from "./dump-sql.js";
+import { MAX_COPY_HEADER, parseCopyHeader, parseCreateSchemas } from "./dump-sql.js";
 import { resolvePgRestoreBin } from "./pgbin.js";
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
 import { interrupted, onInterrupt, stopOnInterrupt } from "./interrupt.js";
@@ -822,3 +822,85 @@ export async function restoreDatabaseArtifact(opts) {
         forgetListDir();
     }
 }
+/**
+ * 逐块读 `pg_restore --data-only -f -` 的输出,判断某张表的 COPY 段有没有数据行。
+ * 返回一个喂数据的函数:能下结论时返回 "rows" / "empty",确定查不清返回 "unknown",
+ * 还要更多输出返回 null。纯函数,方便单测。
+ *
+ * 只按 \n 切行,不用 readline:readline 把 \r 也当换行(引号名里可以有 \r),还会把一整行数据
+ * 读进内存(大 bytea 行能有几百 MB)。COPY 头之后只看紧跟着的几个字符。
+ * 带引号的名字里还可以有换行(列名里甚至能写 FROM stdin; 和 \.),COPY 头就会跨行:攒到引号配平、
+ * 以 FROM stdin; 结尾为止,再按 COPY 头的语法解析、核对是不是这张表(同 scanDumpData)。
+ */
+export function copyDataProbe(schema, table) {
+    let buffer = "";
+    let header = null;
+    let inData = false;
+    return (chunk) => {
+        buffer += chunk;
+        for (;;) {
+            if (inData) {
+                // 结束符一行只有 \.;数据里以 \. 开头的值会被转义成 \\.,不会混淆
+                if (buffer.startsWith("\\.\n"))
+                    return "empty";
+                if (!"\\.\n".startsWith(buffer))
+                    return "rows";
+                return null; // 字符还不够判断
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return buffer.length + (header?.length ?? 0) > MAX_COPY_HEADER ? "unknown" : null;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (header === null && !line.startsWith("COPY "))
+                continue;
+            header = header === null ? line : `${header}\n${line}`;
+            const balanced = (header.split('"').length - 1) % 2 === 0;
+            if (!(balanced && header.endsWith(" FROM stdin;"))) {
+                if (header.length > MAX_COPY_HEADER)
+                    return "unknown";
+                continue;
+            }
+            const parsed = parseCopyHeader(header);
+            header = null;
+            if (!parsed || parsed.table.schema !== schema || parsed.table.name !== table)
+                return "unknown";
+            inData = true;
+        }
+    };
+}
+/**
+ * 这张表在 dump 里有没有数据行(判断见 copyDataProbe)。拿到答案就停掉 pg_restore,不读完整份 dump。
+ * 没有 COPY 段(matview 的数据是 REFRESH)、COPY 头读不懂或不是这张表、pg_restore 起不来或出错,
+ * 都返回 "unknown",由调用方按"查不清"处理。
+ */
+export function tableDataInDump(dumpPath, schema, table) {
+    if (interrupted())
+        return Promise.resolve("unknown");
+    return new Promise((resolve) => {
+        // -n/-t 在 pg_restore 里是精确名,不是 pg_dump 那种模式;不连库,只往 stdout 出 SQL。
+        // 和 pgRestoreOutput 一样钉 C locale
+        const proc = spawn(resolvePgRestoreBin(), ["--data-only", `--schema=${schema}`, `--table=${table}`, "--file=-", dumpPath], { stdio: ["ignore", "pipe", "ignore"], env: libpqChildEnv() });
+        const forget = stopOnInterrupt(proc);
+        const probe = copyDataProbe(schema, table);
+        let answer = null;
+        // 按流解码:多字节字符可能被拆在两块里
+        proc.stdout.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => {
+            if (answer !== null)
+                return;
+            answer = probe(chunk);
+            if (answer !== null)
+                proc.kill("SIGTERM");
+        });
+        proc.on("error", () => {
+            forget();
+            resolve("unknown");
+        });
+        // 拿到答案后是我们自己停的,退出码不看;没拿到答案就退出(出错或没有 COPY 段)= 查不清
+        proc.on("close", () => {
+            forget();
+            resolve(answer ?? "unknown");
+        });
+    });
+}

package/dist/restore.js

@@ -697,7 +697,7 @@ export async function runRestore(config, opts) {
             result.restoredToDatabase = true;
             // 与演练同一套表级验证:两条路径对同一快照必须同一结论(PRD §5.2 验收)
             log.step("Verifying restored tables…");
-            const verified = await verifyRestored(targetUrl, manifest);
+            const verified = await verifyRestored(targetUrl, manifest, dumpPath);
             result.databaseChecks = verified.checks;
             result.databaseVerified = verified.checks.every((c) => c.pass);
             for (const check of verified.checks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "description": "Open-source CLI to back up a Supabase project — Postgres database and Storage files — to your own S3/R2/B2 bucket, with a checksummed manifest.",
   "type": "module",
   "bin": {

package/plugin/README.md

@@ -7,7 +7,7 @@ Back up a Supabase project to a bucket you own and prove the backup restores, by
 - `drill` restores a snapshot into a throwaway Postgres in Docker, checks that the tables and their data came back, and checksums a sample of the Storage files.
 - `restore` puts a snapshot into a new, empty Supabase project, after a dry run and only once you confirm the target.
 
-The agent runs every command as `npx -y backupdrill@2.5.0`, so the CLI version stays fixed.
+The agent runs every command as `npx -y backupdrill@2.7.0`, so the CLI version stays fixed.
 
 ## What you need
 

package/plugin/skills/supabase-backup/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user wants to back up a Supabase project to their own
 
 backupdrill is an open-source (MIT) command-line tool. `backup` dumps the project's Postgres database with `pg_dump`, copies Storage files too once their S3 keys are set, and writes everything to a bucket the user owns, with a checksummed `manifest.json` and a `RECOVERY.md` in every snapshot. `drill` restores a snapshot into a throwaway Postgres in Docker and checks that it came back. The CLI runs on the user's machine. It talks to their Supabase project, their bucket and the local Docker daemon, and sends nothing to BackupDrill.
 
-Always run it as `npx -y backupdrill@2.5.0 <command>`, so every run uses the same version.
+Always run it as `npx -y backupdrill@2.7.0 <command>`, so every run uses the same version.
 
 You need a shell on the user's machine for this. If you don't have one, walk the user through the same commands instead of running them.
 
@@ -69,7 +69,7 @@ Every backup reads the whole database, and every configured Storage file, out of
 ```sh
 ( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
   set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
-  npx -y backupdrill@2.5.0 estimate --plan pro )
+  npx -y backupdrill@2.7.0 estimate --plan pro )
 ```
 
 Use `--plan free`, `pro` or `team` to match their Supabase plan, and read the projection back before suggesting a daily schedule. On a large database, suggest weekly.
@@ -80,7 +80,7 @@ Use `--plan free`, `pro` or `team` to match their Supabase plan, and read the pr
 report="$(mktemp "${TMPDIR:-/tmp}/backupdrill-backup.XXXXXX")" || exit 1; echo "stdout → $report"
 ( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
   set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
-  npx -y backupdrill@2.5.0 backup ) > "$report"
+  npx -y backupdrill@2.7.0 backup ) > "$report"
 ```
 
 - The progress lines on stderr show where everything went (`Dumping → s3://…`, `Manifest written → s3://…`) and end with `Backup complete — N tables + M Storage files`. stdout goes to the file named on the first line, a new one each run that only the user can read: one line of JSON with the whole manifest, which lists every table and Storage file, so read only the fields you need from it.
@@ -93,7 +93,7 @@ report="$(mktemp "${TMPDIR:-/tmp}/backupdrill-backup.XXXXXX")" || exit 1; echo "
 ```sh
 ( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
   set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
-  npx -y backupdrill@2.5.0 drill )
+  npx -y backupdrill@2.7.0 drill )
 ```
 
 - It reads the latest snapshot from the bucket, restores it into a throwaway Postgres container, runs its checks and removes the container. It doesn't connect to the Supabase project. The first run pulls a Postgres image from Docker Hub.
@@ -112,7 +112,7 @@ A restore writes data, so go step by step and let the user drive.
    ```sh
    ( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
      set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
-     npx -y backupdrill@2.5.0 restore --database --target-supabase-url https://<target-ref>.supabase.co --dry-run )
+     npx -y backupdrill@2.7.0 restore --database --target-supabase-url https://<target-ref>.supabase.co --dry-run )
    ```
 
    Leave out `--target-supabase-url` when the snapshot is database only. To write Storage files to a local folder instead of the new project, use `--storage-dir ./recovered`.

package/plugin/skills/supabase-backup/assets/scheduled-backup.yml

@@ -95,7 +95,7 @@ jobs:
 
       - name: Run backupdrill
         # Pinned so every run uses the same CLI. Raise it on purpose when you upgrade.
-        run: npx -y backupdrill@2.5.0 backup
+        run: npx -y backupdrill@2.7.0 backup
         env:
           # --- required ---
           BACKUPDRILL_DATABASE_URL: ${{ secrets.BACKUPDRILL_DATABASE_URL }}