backupdrill 2.2.4 → 2.3.0

package/README.md

@@ -31,6 +31,17 @@ npm install -g backupdrill
 npx backupdrill backup
 ```
 
+## Use it from Claude Code or Cursor
+
+The [`plugin/`](plugin/) folder is a plugin for Claude Code and Cursor. It teaches the agent to run `estimate`, `backup`, `drill` and `restore` for you, keeps your keys in a gitignored `.env.backupdrill` that the agent never opens, and always does a dry run before a restore. In Claude Code:
+
+```
+/plugin marketplace add backupdrill/cli
+/plugin install backupdrill@backupdrill
+```
+
+Details are in [plugin/README.md](plugin/README.md).
+
 ## Usage
 
 Configure via **env vars**, a **config file**, or **flags** (precedence: flags > env > file).
@@ -150,6 +161,8 @@ backupdrill drill --verify-all-files # also checksum every Storage file, not jus
 
 Backups record your installed Postgres extensions in the manifest, and the drill pre-installs them in the sandbox before restoring — including switching to a pgvector-enabled sandbox image when your database uses `vector` columns.
 
+The sandbox restore runs up to 4 parallel `pg_restore` jobs, sized from the CPUs and memory Docker reports, so a 2 vCPU / 8 GB machine gets 2. Table data and index builds run in parallel. Foreign keys, triggers and policies run on a single connection to keep their error messages separate, including errors about Supabase-managed objects such as `auth.users`. `backupdrill restore` into a real Supabase project stays on a single connection.
+
 ### Run your own checks against the restored copy
 
 The drill's structural checks (tables, rows, checksums) can't know what "working" means for *your* app — business invariants only have answers in your code. `--check-cmd` hands you the restored sandbox before it's destroyed:

package/dist/drill.d.ts

@@ -44,8 +44,10 @@ export interface SandboxTuning {
     settings: string[];
     /** docker --shm-size 的值;并行建索引走动态共享内存,要跟 maintenance_work_mem 一起长 */
     shmSize: string;
+    /** pg_restore --jobs;1 = 单连接 */
+    restoreJobs: number;
 }
-export declare function sandboxTuning(totalMemBytes: number): SandboxTuning;
+export declare function sandboxTuning(totalMemBytes: number, cpus?: number): SandboxTuning;
 export declare function sandboxDataVolumeTarget(major: number): string;
 /** post-data 第二遍恢复的结果:用户对象失败 vs Supabase 托管对象的沙箱预期跳过。 */
 interface PostDataResult {

package/dist/drill.js

@@ -60,23 +60,31 @@ const MIB = 1024 * 1024;
 function clampMib(bytes, minMib, maxMib) {
     return Math.min(maxMib, Math.max(minMib, Math.floor(bytes / MIB)));
 }
-/** Docker 引擎可用内存(字节);问不到就返回 0,让 sandboxTuning 落到下限值,宁慢勿炸。 */
-async function dockerMemoryBudget() {
+/** Docker 引擎可用内存(字节)和 CPU 数;问不到就返回 0,让 sandboxTuning 落到下限值、单连接,宁慢勿炸。 */
+async function dockerResources() {
     try {
         // 探测是可选的,绝不能卡住演练:守护进程假死时 5 秒后放弃,落到下限值继续跑
-        const { stdout } = await execFileAsync("docker", ["info", "--format", "{{.MemTotal}}"], {
+        const { stdout } = await execFileAsync("docker", ["info", "--format", "{{.MemTotal}} {{.NCPU}}"], {
             timeout: 5_000,
         });
-        const bytes = Number.parseInt(stdout.trim(), 10);
-        return Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+        const [memoryBytes, cpus] = stdout.trim().split(/\s+/).map((value) => Number.parseInt(value, 10));
+        const positive = (value) => (value !== undefined && Number.isFinite(value) && value > 0 ? value : 0);
+        return { memoryBytes: positive(memoryBytes), cpus: positive(cpus) };
     }
     catch {
-        return 0;
+        return { memoryBytes: 0, cpus: 0 };
     }
 }
-export function sandboxTuning(totalMemBytes) {
+export function sandboxTuning(totalMemBytes, cpus = 1) {
+    const budgetMib = Math.floor(totalMemBytes / MIB);
     const sharedBuffersMib = clampMib(totalMemBytes / 4, 256, 2048);
     const maintenanceWorkMemMib = clampMib(totalMemBytes / 8, 256, 1024);
+    // 并行恢复时每一路都可能同时在建索引,各自吃满 maintenance_work_mem:路数 × maintenance_work_mem
+    // 加上 shared_buffers 不超过预算的一半,另一半留给 pg_restore、Docker 和同机的其他任务
+    // (8 GB 的 worker 正好 2 路,2026-10-17 在它上面实测 -j2 没出内存问题)。
+    // 再封顶 4 路:pg_restore 的并行度受表和索引个数限制,再多收益很小,演练还常跑在用户自己的电脑上。
+    const memoryBoundJobs = Math.floor((budgetMib / 2 - sharedBuffersMib) / maintenanceWorkMemMib);
+    const restoreJobs = Math.max(1, Math.min(cpus, memoryBoundJobs, 4));
     return {
         settings: [
             "fsync=off",
@@ -91,8 +99,9 @@ export function sandboxTuning(totalMemBytes) {
         ],
         // Docker 默认 /dev/shm 只有 64 MB;并行建索引(pgvector 的 HNSW 尤其)走动态共享内存,
         // 64 MB 会撞 "No space left on device" 把好备份误判失败(交叉审查 2026-09-12 复现)。
-        // 给 maintenance_work_mem 的两倍、至少 1 GB;tmpfs 只按实际用量占内存,给大不吃亏。
-        shmSize: `${Math.max(1024, maintenanceWorkMemMib * 2)}m`,
+        // 每一路并行恢复给 maintenance_work_mem 的两倍、至少 1 GB;tmpfs 只按实际用量占内存,给大不吃亏。
+        shmSize: `${Math.max(1024, maintenanceWorkMemMib * 2 * restoreJobs)}m`,
+        restoreJobs,
     };
 }
 function validateSupervision(supervision, appCheckCommand, keepSandboxOnFailure) {
@@ -132,7 +141,8 @@ async function startEphemeralPostgres(image, major, resourceName) {
         }
     }
     log.step(`Starting ephemeral ${image}…`);
-    const tuning = sandboxTuning(await dockerMemoryBudget());
+    const resources = await dockerResources();
+    const tuning = sandboxTuning(resources.memoryBytes, resources.cpus);
     const { stdout } = await execFileAsync("docker", [
         "run",
         "-d",
@@ -187,7 +197,7 @@ async function startEphemeralPostgres(image, major, resourceName) {
                     "postgres",
                     "-q",
                 ]);
-                return { containerId, port, connString, volumeName };
+                return { containerId, port, connString, volumeName, restoreJobs: tuning.restoreJobs };
             }
             catch {
                 await new Promise((r) => setTimeout(r, 500));
@@ -222,8 +232,8 @@ export function postDataResult(code, stderr) {
  * 的托管对象跳过如实返回。pre-data 的 schema 冲突跳过(dump 自带 CREATE SCHEMA,
  * 容器恒有 public)是非事件,不计入报告。
  */
-async function pgRestore(dumpPath, connString, dumpedSchemas) {
-    const result = await restoreDatabaseArtifact({ dumpPath, connString, target: "sandbox", dumpedSchemas });
+async function pgRestore(dumpPath, connString, dumpedSchemas, jobs) {
+    const result = await restoreDatabaseArtifact({ dumpPath, connString, target: "sandbox", dumpedSchemas, jobs });
     if (result.preData.failures.length) {
         throw new Error(`pg_restore failed: ${result.preData.failures.join(" | ")}`);
     }
@@ -478,7 +488,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
         log.step("Restoring into ephemeral Postgres…");
         let postData;
         try {
-            postData = await pgRestore(dumpPath, pg.connString, manifest.database.schemas);
+            postData = await pgRestore(dumpPath, pg.connString, manifest.database.schemas, pg.restoreJobs);
         }
         catch (error) {
             // 沙箱装不上扩展 + 错误特征命中"缺类型/schema/扩展" → 假设式归因到沙箱环境
@@ -491,7 +501,11 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
             throw error;
         }
         const restoreSeconds = Math.round((Date.now() - started) / 100) / 10;
-        checks.push({ name: "pg_restore", pass: true, detail: `completed in ${restoreSeconds}s` });
+        checks.push({
+            name: "pg_restore",
+            pass: true,
+            detail: `completed in ${restoreSeconds}s` + (pg.restoreJobs > 1 ? ` (${pg.restoreJobs} parallel jobs)` : ""),
+        });
         // 用户自己的 post-data 对象(索引/约束/触发器)必须全部恢复;Supabase 托管对象
         // 的沙箱预期跳过如实写进报告(演练不假装它们恢复了)。
         checks.push({

package/dist/restore-engine.d.ts

@@ -91,8 +91,25 @@ export declare function classifyBlocks(stderr: string, allow: RegExp): Classifie
  *    的半截恢复就会被报成功(评审第 7 轮抓出的假成功路径)。
  * 2. 非零退出且零错误块(归档器致命错、非英文 locale…)同样不能谎报成功。
  *    非零退出但每个错误都已分类 = pg_restore 对被忽略错误的正常退出形态,通过。
+ * 3. 并行遍(`parallel`)不能只信切块:多个 worker 进程共用一个 stderr,而 PostgreSQL 一条
+ *    报错分好几次 write(`pg_restore:`、` `、`error: `、正文,见 src/common/logging.c),
+ *    两条同时写会交错,一条真错误的前缀可能被拆散、正文挂到另一条预期跳过的块里——切块
+ *    看不到它,演练照样 PASS。所以并行遍只在两种情况下通过:退出码 0(一个错误都没有),
+ *    或 pg_restore 最后打印的 "errors ignored on restore: N" 恰好等于预期跳过数。
+ *    worker 里出的错 PostgreSQL 会多算一次(17 实测 4 个错报 8,mark_restore_job_done
+ *    又 +1),所以只要 worker 出过错 N 就一定大于预期跳过数——这条规则只放行"所有错误都出在
+ *    fork 之前的单进程阶段"的那种并行遍,调用方要据此安排哪些对象放进并行遍。
+ *    没有这行汇总的非零退出 = 中途致命退出,同样失败。
  */
-export declare function finalizePass(code: number | null, stderr: string, classified: ClassifiedPass): ClassifiedPass;
+export declare function finalizePass(code: number | null, stderr: string, classified: ClassifiedPass, opts?: {
+    parallel?: boolean;
+}): ClassifiedPass;
+/**
+ * pg_restore 正常跑完时打印的错误总数;没跑完(致命退出)或认不出时返回 null。
+ * 只认 stderr 的最后一个非空行、且整行就是这句汇总:这行在所有 worker 退出之后由主进程打印,
+ * 不会和别的输出交错;前面 "Command was:" 里的用户 SQL 就算含同样字样也冒充不了它。
+ */
+export declare function ignoredErrorTotal(stderr: string): number | null;
 /** 标识符转义(内嵌引号翻倍)。导出:任何把目录里读到的名字拼进 SQL 的地方都必须用它。 */
 export declare function quoteIdent(name: string): string;
 /**
@@ -159,10 +176,46 @@ export declare function credentialSafeDbArgs(connString: string): {
  * 目标)的 options 没有租户语义,照常放行。
  */
 export declare function assertNoHostOverride(connString: string): void;
+/**
+ * 把 `pg_restore --list --section=post-data` 的目录拆成两份 -L 清单:
+ * - `indexBuilds`:INDEX 和 CONSTRAINT(主键/唯一/排除约束,本质也是建索引)。恢复里最慢的就是
+ *   它们(2026-10-17 实测 post-data 占 pg_restore 时间的 67–77%,大头是建索引)。并行跑;
+ *   出过错的条目再单连接重跑一遍定结论(见 restoreDatabaseArtifact)。
+ * - `rest`:FK CONSTRAINT、TRIGGER、POLICY、INDEX ATTACH、COMMENT 等。指向 auth.users 的外键
+ *   这类预期跳过全在这里,并行时 worker 报错会交错、计数也不准(见 finalizePass 规则 3),
+ *   所以这份始终单连接跑,保留逐块分类。外键依赖主键/唯一约束,也必须排在 indexBuilds 之后。
+ * 注释行(`;` 开头)和空行丢掉:-L 只按行首的 dumpId 认条目。
+ */
+export declare function splitPostDataList(listing: string): {
+    indexBuilds: string[];
+    rest: string[];
+};
+/**
+ * 并行建索引那遍(带 --verbose)里出过错的条目 dumpId。pg_restore 对每个出错条目先打一行
+ * `from TOC entry <dumpId>; …`(warn_or_exit_horribly,只在 verbose 下输出)。这行正文是一次
+ * write 写完的:并行时它的 `pg_restore: ` 前缀可能被别的 worker 拆开,正文本身不会,
+ * 所以按子串找、不按行首找。
+ */
+export declare function failedTocEntries(stderr: string): Set<string>;
+/**
+ * 两遍恢复(形状见 credentialSafeDbArgs 上方那段"两遍恢复"注释),`jobs` > 1 时按下面的方式并行(2026-10-17 实测:2 核机器上同一份
+ * dump,原生 -j2 比 -j1 在 5 GB 快 14%、10 GB 快 12%):
+ * 1. pre-data+data 一遍加 --jobs。pg_restore 并行时先在主进程里单独跑完 pre-data,fork 之后
+ *    才并行灌数据,所以唯一的预期冲突(schema 已存在)一定出在单进程阶段,finalizePass
+ *    规则 3 的计数核对成立。同一遍里建表再灌数据,pg_restore 才会用 TRUNCATE+COPY,
+ *    wal_level=minimal 的沙箱因此不写这部分 WAL——拆成两遍就没了这个加速。
+ * 2. post-data 拆成两份清单(splitPostDataList):建索引那份并行,退出码 0 即通过,报过错
+ *    的条目单连接重跑定结论;其余单连接、照旧按目标类型分类。
+ *    两遍下来,同一份备份不管几路并行,结论都和 jobs=1 一样。
+ * 真实 Supabase 目标(restore.ts)不传 jobs:每一路都是一条 pooler 连接,小规格项目的连接数
+ * 和算力都紧,并行没测过,保持原来的单连接两遍。
+ */
 export declare function restoreDatabaseArtifact(opts: {
     dumpPath: string;
     connString: string;
     target: RestoreTargetKind;
     /** manifest.database.schemas:沙箱 allowlist 据此剔掉转储自带的托管 schema(见 sandboxManagedError)。 */
     dumpedSchemas?: string[];
+    /** pg_restore 并行路数;不传或 ≤1 = 单连接两遍。 */
+    jobs?: number;
 }): Promise<EngineResult>;

package/dist/restore-engine.js

@@ -9,6 +9,9 @@
 //  3. dump 自带 CREATE SCHEMA,而目标(新容器或 Supabase)恒有同名 schema →
 //     pre-data 阶段的 schema "already exists" 是两类目标共同的预期冲突。
 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 { resolvePgRestoreBin } from "./pgbin.js";
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
 /** 主机名规范化:先按驱动语义百分号解码(pg-connection-string / libpq 都会解码主机名,
@@ -268,8 +271,17 @@ export function classifyBlocks(stderr, allow) {
  *    的半截恢复就会被报成功(评审第 7 轮抓出的假成功路径)。
  * 2. 非零退出且零错误块(归档器致命错、非英文 locale…)同样不能谎报成功。
  *    非零退出但每个错误都已分类 = pg_restore 对被忽略错误的正常退出形态,通过。
+ * 3. 并行遍(`parallel`)不能只信切块:多个 worker 进程共用一个 stderr,而 PostgreSQL 一条
+ *    报错分好几次 write(`pg_restore:`、` `、`error: `、正文,见 src/common/logging.c),
+ *    两条同时写会交错,一条真错误的前缀可能被拆散、正文挂到另一条预期跳过的块里——切块
+ *    看不到它,演练照样 PASS。所以并行遍只在两种情况下通过:退出码 0(一个错误都没有),
+ *    或 pg_restore 最后打印的 "errors ignored on restore: N" 恰好等于预期跳过数。
+ *    worker 里出的错 PostgreSQL 会多算一次(17 实测 4 个错报 8,mark_restore_job_done
+ *    又 +1),所以只要 worker 出过错 N 就一定大于预期跳过数——这条规则只放行"所有错误都出在
+ *    fork 之前的单进程阶段"的那种并行遍,调用方要据此安排哪些对象放进并行遍。
+ *    没有这行汇总的非零退出 = 中途致命退出,同样失败。
  */
-export function finalizePass(code, stderr, classified) {
+export function finalizePass(code, stderr, classified, opts = {}) {
     const detail = stderr.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)";
     if (code === null) {
         return {
@@ -280,8 +292,30 @@ export function finalizePass(code, stderr, classified) {
     if (code !== 0 && classified.expectedSkips === 0 && classified.failures.length === 0) {
         return { ...classified, failures: [`pg_restore exited with code ${code}: ${detail}`] };
     }
+    if (opts.parallel && code !== 0 && classified.failures.length === 0) {
+        const reported = ignoredErrorTotal(stderr);
+        if (reported === null || reported !== classified.expectedSkips) {
+            return {
+                ...classified,
+                failures: [
+                    `parallel pg_restore reported ${reported ?? "an unknown number of"} error(s), ` +
+                        `but only ${classified.expectedSkips} could be attributed to expected skips: ${detail}`,
+                ],
+            };
+        }
+    }
     return classified;
 }
+/**
+ * pg_restore 正常跑完时打印的错误总数;没跑完(致命退出)或认不出时返回 null。
+ * 只认 stderr 的最后一个非空行、且整行就是这句汇总:这行在所有 worker 退出之后由主进程打印,
+ * 不会和别的输出交错;前面 "Command was:" 里的用户 SQL 就算含同样字样也冒充不了它。
+ */
+export function ignoredErrorTotal(stderr) {
+    const lastLine = stderr.trimEnd().split("\n").pop() ?? "";
+    const match = /^pg_restore: warning: errors ignored on restore: (\d+)$/.exec(lastLine);
+    return match ? Number(match[1]) : null;
+}
 /** 标识符转义(内嵌引号翻倍)。导出:任何把目录里读到的名字拼进 SQL 的地方都必须用它。 */
 export function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;
@@ -526,6 +560,76 @@ export function assertNoHostOverride(connString) {
         }
     }
 }
+/**
+ * 把 `pg_restore --list --section=post-data` 的目录拆成两份 -L 清单:
+ * - `indexBuilds`:INDEX 和 CONSTRAINT(主键/唯一/排除约束,本质也是建索引)。恢复里最慢的就是
+ *   它们(2026-10-17 实测 post-data 占 pg_restore 时间的 67–77%,大头是建索引)。并行跑;
+ *   出过错的条目再单连接重跑一遍定结论(见 restoreDatabaseArtifact)。
+ * - `rest`:FK CONSTRAINT、TRIGGER、POLICY、INDEX ATTACH、COMMENT 等。指向 auth.users 的外键
+ *   这类预期跳过全在这里,并行时 worker 报错会交错、计数也不准(见 finalizePass 规则 3),
+ *   所以这份始终单连接跑,保留逐块分类。外键依赖主键/唯一约束,也必须排在 indexBuilds 之后。
+ * 注释行(`;` 开头)和空行丢掉:-L 只按行首的 dumpId 认条目。
+ */
+export function splitPostDataList(listing) {
+    const indexBuilds = [];
+    const rest = [];
+    for (const line of listing.split("\n")) {
+        if (!/^\d+;/.test(line))
+            continue;
+        // 格式:`<dumpId>; <tableoid> <oid> <类型> <schema> <名字> <属主>`,类型可含空格
+        // (FK CONSTRAINT、INDEX ATTACH),所以按类型开头匹配并单独排除 INDEX ATTACH
+        if (/^\d+; \d+ \d+ (INDEX|CONSTRAINT) /.test(line) && !/^\d+; \d+ \d+ INDEX ATTACH /.test(line)) {
+            indexBuilds.push(line);
+        }
+        else {
+            rest.push(line);
+        }
+    }
+    return { indexBuilds, rest };
+}
+function listPostData(bin, dumpPath) {
+    return new Promise((resolve, reject) => {
+        // 只读归档、不连库,但同样钉 C locale,和恢复子进程一致
+        const proc = spawn(bin, ["--list", "--section=post-data", dumpPath], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: libpqChildEnv(),
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (d) => (stdout += d.toString()));
+        proc.stderr.on("data", (d) => (stderr += d.toString()));
+        proc.on("error", (error) => reject(new Error(`${bin} failed to start: ${error.code ?? error.message}`)));
+        proc.on("close", (code) => resolve({ code, stdout, stderr }));
+    });
+}
+/**
+ * 并行建索引那遍(带 --verbose)里出过错的条目 dumpId。pg_restore 对每个出错条目先打一行
+ * `from TOC entry <dumpId>; …`(warn_or_exit_horribly,只在 verbose 下输出)。这行正文是一次
+ * write 写完的:并行时它的 `pg_restore: ` 前缀可能被别的 worker 拆开,正文本身不会,
+ * 所以按子串找、不按行首找。
+ */
+export function failedTocEntries(stderr) {
+    return new Set([...stderr.matchAll(/from TOC entry (\d+);/g)].map((match) => match[1]));
+}
+function mergePasses(passes) {
+    return {
+        expectedSkips: passes.reduce((sum, pass) => sum + pass.expectedSkips, 0),
+        failures: passes.flatMap((pass) => pass.failures),
+    };
+}
+/**
+ * 两遍恢复(形状见 credentialSafeDbArgs 上方那段"两遍恢复"注释),`jobs` > 1 时按下面的方式并行(2026-10-17 实测:2 核机器上同一份
+ * dump,原生 -j2 比 -j1 在 5 GB 快 14%、10 GB 快 12%):
+ * 1. pre-data+data 一遍加 --jobs。pg_restore 并行时先在主进程里单独跑完 pre-data,fork 之后
+ *    才并行灌数据,所以唯一的预期冲突(schema 已存在)一定出在单进程阶段,finalizePass
+ *    规则 3 的计数核对成立。同一遍里建表再灌数据,pg_restore 才会用 TRUNCATE+COPY,
+ *    wal_level=minimal 的沙箱因此不写这部分 WAL——拆成两遍就没了这个加速。
+ * 2. post-data 拆成两份清单(splitPostDataList):建索引那份并行,退出码 0 即通过,报过错
+ *    的条目单连接重跑定结论;其余单连接、照旧按目标类型分类。
+ *    两遍下来,同一份备份不管几路并行,结论都和 jobs=1 一样。
+ * 真实 Supabase 目标(restore.ts)不传 jobs:每一路都是一条 pooler 连接,小规格项目的连接数
+ * 和算力都紧,并行没测过,保持原来的单连接两遍。
+ */
 export async function restoreDatabaseArtifact(opts) {
     const bin = resolvePgRestoreBin();
     // TLS 全链路 verify-full(创始人承诺项):pg_restore 与 pg_dump 同一改写——
@@ -534,12 +638,71 @@ export async function restoreDatabaseArtifact(opts) {
     const { url, env } = credentialSafeDbArgs(dumpUrlFor(opts.connString));
     const common = ["--no-owner", "--no-privileges", "--dbname", url, opts.dumpPath];
     const childOpts = { supabaseHost: isSupabaseHost(opts.connString), urlSslMode: urlSslModeOf(url) };
-    const first = await spawnPgRestore(bin, ["--section=pre-data", "--section=data", ...common], env, childOpts);
-    const preData = finalizePass(first.code, first.stderr, classifyBlocks(first.stderr, SCHEMA_EXISTS_ERROR));
+    const jobs = Math.max(1, Math.floor(opts.jobs ?? 1));
+    const parallel = jobs > 1;
+    const jobsArg = parallel ? [`--jobs=${jobs}`] : [];
+    const first = await spawnPgRestore(bin, ["--section=pre-data", "--section=data", ...jobsArg, ...common], env, childOpts);
+    const preData = finalizePass(first.code, first.stderr, classifyBlocks(first.stderr, SCHEMA_EXISTS_ERROR), { parallel });
     if (preData.failures.length) {
         return { preData, postData: { expectedSkips: 0, failures: [] }, ok: false };
     }
-    const second = await spawnPgRestore(bin, ["--section=post-data", ...common], env, childOpts);
-    const postData = finalizePass(second.code, second.stderr, classifyBlocks(second.stderr, opts.target === "sandbox" ? sandboxManagedError(opts.dumpedSchemas ?? []) : NEVER_MATCH));
-    return { preData, postData, ok: postData.failures.length === 0 };
+    const postDataAllow = opts.target === "sandbox" ? sandboxManagedError(opts.dumpedSchemas ?? []) : NEVER_MATCH;
+    if (!parallel) {
+        const second = await spawnPgRestore(bin, ["--section=post-data", ...common], env, childOpts);
+        const postData = finalizePass(second.code, second.stderr, classifyBlocks(second.stderr, postDataAllow));
+        return { preData, postData, ok: postData.failures.length === 0 };
+    }
+    const listing = await listPostData(bin, opts.dumpPath);
+    if (listing.code !== 0) {
+        const detail = listing.stderr.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)";
+        const postData = { expectedSkips: 0, failures: [`pg_restore --list exited with code ${listing.code}: ${detail}`] };
+        return { preData, postData, ok: false };
+    }
+    const { indexBuilds, rest } = splitPostDataList(listing.stdout);
+    const listDir = await mkdtemp(join(tmpdir(), "backupdrill-restore-"));
+    try {
+        const passes = [];
+        if (indexBuilds.length) {
+            const listFile = join(listDir, "index-builds.list");
+            await writeFile(listFile, indexBuilds.join("\n") + "\n");
+            const run = await spawnPgRestore(bin, ["--section=post-data", `--use-list=${listFile}`, "--verbose", ...jobsArg, ...common], env, childOpts);
+            // 退出码 0 = 一个错都没有。出过错时不读交错的报错正文,只取出错条目的 dumpId,把这些条目
+            // 单连接重跑、照单连接的规则分类:一条 CREATE INDEX / ADD CONSTRAINT 失败不留半成品,
+            // 重跑得到的就是 jobs=1 时的结论(交叉审查:引用托管 schema 函数的索引在单连接时是预期
+            // 跳过,并行时不能因此判失败;也不能靠忽略"已存在"去猜哪些建好了,沙箱里预装的扩展
+            // 对象会和用户索引撞名)。资源原因偶发失败的条目,重跑成功即通过,和单连接本来一样。
+            if (run.code !== 0) {
+                const failedIds = failedTocEntries(run.stderr);
+                const failed = indexBuilds.filter((line) => failedIds.has(line.slice(0, line.indexOf(";"))));
+                // 被信号杀死、没有汇总行(中途致命退出,后面的条目根本没跑)、或认不出任何出错条目:
+                // 都说明这一遍没走完或没法归因,直接失败,不重跑
+                // 出错条目的编号即使被用户 SQL 冒充,也只会多重跑一条、让它报"已存在"而判失败,不会漏掉真错误
+                const finished = run.code !== null && ignoredErrorTotal(run.stderr) !== null && failed.length > 0;
+                if (!finished) {
+                    const detail = run.stderr.trim().replace(/\s+/g, " ").slice(-200) || "(no stderr)";
+                    passes.push({
+                        expectedSkips: 0,
+                        failures: [`parallel index builds did not finish cleanly (exit ${run.code ?? "signal"}): ${detail}`],
+                    });
+                }
+                else {
+                    const rerunFile = join(listDir, "index-builds-rerun.list");
+                    await writeFile(rerunFile, failed.join("\n") + "\n");
+                    const rerun = await spawnPgRestore(bin, ["--section=post-data", `--use-list=${rerunFile}`, ...common], env, childOpts);
+                    passes.push(finalizePass(rerun.code, rerun.stderr, classifyBlocks(rerun.stderr, postDataAllow)));
+                }
+            }
+        }
+        if (rest.length) {
+            const listFile = join(listDir, "rest.list");
+            await writeFile(listFile, rest.join("\n") + "\n");
+            const run = await spawnPgRestore(bin, ["--section=post-data", `--use-list=${listFile}`, ...common], env, childOpts);
+            passes.push(finalizePass(run.code, run.stderr, classifyBlocks(run.stderr, postDataAllow)));
+        }
+        const postData = mergePasses(passes);
+        return { preData, postData, ok: postData.failures.length === 0 };
+    }
+    finally {
+        await rm(listDir, { recursive: true, force: true });
+    }
 }

package/dist/restore.d.ts

@@ -61,6 +61,12 @@ export declare function assertRequestApplies(manifest: Manifest, wantsDatabase:
  * 这道门要求人把目标身份亲手打一遍。
  */
 export declare function assertConfirmedTarget(confirmTarget: string | undefined, targetDatabaseUrl?: string, targetSupabaseUrl?: string): void;
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export declare function nonEmptyTargetMessage(schemas: string[], objectCount: number, alsoRestoringStorage: boolean): string;
 /**
  * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
  * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),

package/dist/restore.js

@@ -155,6 +155,20 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
             `(use --dry-run first to preview all checks without writing).`);
     }
 }
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export function nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage) {
+    const message = `target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
+        `restore only writes into an empty target. Create a fresh Supabase project ` +
+        `(or empty these schemas) and retry.`;
+    if (!alsoRestoringStorage)
+        return message;
+    return (`${message} If a previous run already restored the database and only Storage was ` +
+        `interrupted, re-run WITHOUT the database target to retry Storage alone.`);
+}
 /**
  * 空目标门(PRD §5.3.3 / 决策 D5):目标 schema 里存在任何用户对象即拒绝写入。
  * "空"的定义来自 R0 spike:不是"schema 不存在"(Supabase 恒有 public),而是
@@ -162,7 +176,7 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
  * 全部计入:只查关系时,"目标里只有函数"会放行,然后在 pre-data 中途撞冲突,
  * 留下半截目标(评审第 7 轮)。
  */
-async function assertEmptyTarget(targetUrl, schemas) {
+async function assertEmptyTarget(targetUrl, schemas, alsoRestoringStorage) {
     const client = await connectPg(targetUrl);
     try {
         const res = await client.query(`select
@@ -175,11 +189,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
          as n`, [schemas]);
         const objectCount = Number(res.rows[0].n);
         if (objectCount > 0) {
-            throw new Error(`target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
-                `restore only writes into an empty target. Create a fresh Supabase project ` +
-                `(or empty these schemas) and retry. If a previous run already restored the ` +
-                `database and only Storage was interrupted, re-run WITHOUT the database target ` +
-                `to retry Storage alone.`);
+            throw new Error(nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage));
         }
     }
     finally {
@@ -190,7 +200,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
  * dry-run 只读预检(PRD §5.3.2):零写入,把正式执行会撞的墙全部提前撞一遍。
  * 逐项打印,任何 blocker 汇总后抛出(退出码非零 = "现在执行不会成功")。
  */
-async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
+async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoRestoringStorage) {
     const blockers = [];
     const db = manifest.database;
     const mb = (n) => (n / 1024 / 1024).toFixed(1);
@@ -221,7 +231,7 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
             log.ok("target identity: distinct from source");
         }
         try {
-            await assertEmptyTarget(targetUrl, db.schemas);
+            await assertEmptyTarget(targetUrl, db.schemas, alsoRestoringStorage);
             log.ok(`target schemas (${db.schemas.join(", ")}) are empty`);
         }
         catch (error) {
@@ -376,10 +386,13 @@ export async function runRestore(config, opts) {
         storageFilesWritten: 0,
     };
     assertRequestApplies(manifest, !!opts.targetDatabaseUrl, !!storageTarget);
+    // 这次运行会不会碰 Storage(回传到目标,或下载到本地)。只有会碰时,空目标门才该
+    // 提示"库已恢复、只重试 Storage";skipStorage 的纯数据库运行(托管恢复)不该看到这句。
+    const alsoRestoringStorage = !!manifest.storage && !opts.skipStorage;
     // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
     if (opts.dryRun) {
         log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
-        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget);
+        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget, alsoRestoringStorage);
         result.dryRun = true;
         return result;
     }
@@ -408,7 +421,7 @@ export async function runRestore(config, opts) {
                     "at a fresh Supabase project.");
             }
             log.step("Checking target is empty…");
-            await assertEmptyTarget(targetUrl, manifest.database.schemas);
+            await assertEmptyTarget(targetUrl, manifest.database.schemas, alsoRestoringStorage);
             // 版本预检不只属于 dry-run:跳过 dry-run 直接执行时,目标比源旧照样会
             // 半途炸掉或部分恢复(评审第 8 轮)——写入前必须拦住
             const versionClient = await connectPg(targetUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "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": {