backupdrill 2.6.0 → 2.7.1

package/dist/recovery-doc.js

@@ -66,7 +66,16 @@ ${extensions.length
 Supabase **Auth users/sessions, secret values, Edge Function code and most
 platform settings are NOT in this snapshot**. After restoring, reconfigure them
 by hand. This is a database + Storage snapshot, not a full project image.
-
+${db.schemas.includes("auth")
+        ? ""
+        : `
+If a table in this snapshot has a foreign key into \`auth.users\` (a \`profiles.id\`
+that references it, for example), copy the Auth users into the new project
+**before** restoring, or that foreign key can't be created and the restore fails.
+\`backupdrill restore --dry-run\` checks those keys against the new project and reports
+the rows that have no user, plus any key it couldn't check.
+Triggers on \`auth.users\` aren't in this snapshot either; recreate them afterwards.
+`}
 ## Restore the database (into an EMPTY project)
 
 1. Create a **fresh** Supabase project (never restore onto the source project),
@@ -94,7 +103,8 @@ unset PGPASSWORD
 \`\`\`
 
 One error is expected and harmless: \`schema "public" already exists\` (the
-target always has it). Do **not** use \`--clean\` against a Supabase project —
+target always has it). A foreign key error mentioning \`auth.users\` means the
+Auth users were not copied in first (see "Not covered" above). Do **not** use \`--clean\` against a Supabase project —
 dropping and recreating \`public\` silently wipes Supabase's default grants for
 \`anon\`/\`authenticated\`, and the restored API answers 401.
 
@@ -113,9 +123,12 @@ ${cliRestoreCommand}
 
 Add \`--dry-run\` first to preview every check without writing anything. (Skip the
 \`read\` lines to have the CLI prompt you itself; \`unset\` both variables afterwards.)
-The CLI verifies the archive checksum, refuses non-empty targets, installs the
-extensions, restores through the same engine the weekly drills use, verifies
-table counts and row presence afterwards, then rebuilds buckets, uploads the
+The CLI verifies the archive checksum, refuses non-empty targets, checks that rows
+referenced outside the snapshot (such as \`auth.users\`) are on the target, installs
+the extensions, restores the database in a single transaction through the same
+engine the weekly drills use (an SQL error rolls it back and the extensions stay
+installed; if the connection drops while it commits, check the target before
+retrying), verifies table counts and row presence afterwards, then rebuilds buckets, uploads the
 Storage files back and reconciles every one against the target.
 
 More: https://backupdrill.com/docs/restore

package/dist/restore-engine.d.ts

@@ -1,3 +1,4 @@
+import type { Client } from "pg";
 import type { ExtensionInfo } from "./manifest.js";
 export type RestoreTargetKind = "sandbox" | "supabase";
 /** 主机名规范化:先按驱动语义百分号解码(pg-connection-string / libpq 都会解码主机名,
@@ -118,7 +119,9 @@ export declare function quoteIdent(name: string): string;
  * 装不上的扩展如实收集返回,由调用方按目标类型裁决:沙箱记录后继续(托管扩展
  * 本就装不上,public 转储通常不引用),真实目标应当阻断(用户能在 dashboard 开启)。
  */
-export declare function installExtensions(connString: string, extensions: ExtensionInfo[]): Promise<string[]>;
+export declare function installExtensions(connString: string, extensions: ExtensionInfo[], 
+/** 调用方开着的事务:装在它里面(每个扩展一个保存点,装不上的不连累别的),提交与否由调用方定 */
+inTransaction?: Client): Promise<string[]>;
 /**
  * 沙箱专用:预置 Supabase 的最小运行面,让**引用**它的用户对象能建出来被验证,而不是
  * 被当作"托管对象跳过"。只装桩,不装数据 —— 演练验证的是用户自己的 schema。
@@ -151,10 +154,9 @@ export declare function installSandboxShim(connString: string, opts: {
     authFunctions: boolean;
 }): Promise<void>;
 /**
- * 两遍恢复(真实首演炸出的设计,现为 drill 与真实恢复共用):
+ * 两遍恢复(真实首演炸出的设计;2.7.0 起只用于演练沙箱,真实目标见 restoreInOneTransaction):
  * 1. pre-data+data —— 表结构 + 数据。除 schema 冲突(预期)外任何错误都是硬失败。
- * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;allowlist 按目标类型:
- *    沙箱豁免 Supabase 托管对象引用,真实 Supabase 目标零豁免。
+ * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;沙箱豁免 Supabase 托管对象引用。
  */
 /**
  * 凭据不进 argv(D6 同源要求):连接串里的密码对 `ps` 全程可见——拆出来经
@@ -190,6 +192,12 @@ export declare function splitPostDataList(listing: string): {
     indexBuilds: string[];
     rest: string[];
 };
+/** 不连库的 pg_restore(--list、-f - 出 SQL),整段收集 stdout。只用于目录和 DDL 这类小输出。 */
+export declare function pgRestoreOutput(bin: string, args: string[]): Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * 并行建索引那遍(带 --verbose)里出过错的条目 dumpId。pg_restore 对每个出错条目先打一行
  * `from TOC entry <dumpId>; …`(warn_or_exit_horribly,只在 verbose 下输出)。这行正文是一次
@@ -197,6 +205,12 @@ export declare function splitPostDataList(listing: string): {
  * 所以按子串找、不按行首找。
  */
 export declare function failedTocEntries(stderr: string): Set<string>;
+/**
+ * 单事务恢复只会有一条错误(--exit-on-error)。给人看的形态:主消息 + DETAIL/HINT 全文,再带上出错
+ * 语句的开头,方便认出是哪个对象。不再截成 200 字符——那样会把 "is not present in table" 这半句
+ * 切掉,用户看不出缺的是什么(2026-10-22 实验原样截在 "is no")。
+ */
+export declare function firstRestoreError(stderr: string): string;
 /**
  * 两遍恢复(形状见 credentialSafeDbArgs 上方那段"两遍恢复"注释),`jobs` > 1 时按下面的方式并行(2026-10-17 实测:2 核机器上同一份
  * dump,原生 -j2 比 -j1 在 5 GB 快 14%、10 GB 快 12%):
@@ -207,8 +221,8 @@ export declare function failedTocEntries(stderr: string): Set<string>;
  * 2. post-data 拆成两份清单(splitPostDataList):建索引那份并行,退出码 0 即通过,报过错
  *    的条目单连接重跑定结论;其余单连接、照旧按目标类型分类。
  *    两遍下来,同一份备份不管几路并行,结论都和 jobs=1 一样。
- * 真实 Supabase 目标(restore.ts)不传 jobs:每一路都是一条 pooler 连接,小规格项目的连接数
- * 和算力都紧,并行没测过,保持原来的单连接两遍。
+ * 真实 Supabase 目标(restore.ts)不走这里:单事务恢复(restoreInOneTransaction)不能并行,
+ * 而且每一路都是一条 pooler 连接,小规格项目的连接数和算力都紧。
  */
 export declare function restoreDatabaseArtifact(opts: {
     dumpPath: string;
@@ -219,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

@@ -8,12 +8,18 @@
 //     不会带回来),恢复出的 API 直接 401;
 //  3. dump 自带 CREATE SCHEMA,而目标(新容器或 Supabase)恒有同名 schema →
 //     pre-data 阶段的 schema "already exists" 是两类目标共同的预期冲突。
+//
+// 真实目标(2.7.0 起)整份恢复放在一个事务里:失败就整体回滚,目标还是空的,修好原因可以在同一个
+// 项目上直接重跑。此前两遍恢复各自自动提交,post-data 里一条外键失败,表和数据已经落库,重跑被
+// 空目标门挡住(2026-10-22 实验:profiles → auth.users)。沙箱用完即毁,不需要事务,保留两遍 + 并行。
 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 { 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";
 /** 主机名规范化:先按驱动语义百分号解码(pg-connection-string / libpq 都会解码主机名,
  * `supabase%2Ecom` 在驱动眼里就是 supabase.com),再剥掉合法的 DNS 根点(db.x.supabase.co. ≡
  * db.x.supabase.co)。身份比较不规范化 = 一个尾点或一个 %2E 就能绕过同源阻断(交叉审查)。 */
@@ -168,13 +174,19 @@ export function urlSslModeOf(connString) {
     }
 }
 export function spawnPgRestore(bin, args, extraEnv = {}, opts = { supabaseHost: false }) {
+    // 收到信号之后不再起新的一遍(两遍恢复、并行建索引后的重跑都是一个接一个起的)
+    if (interrupted())
+        return Promise.reject(new Error("interrupted; not starting pg_restore"));
     return new Promise((resolve, reject) => {
         const proc = spawn(bin, args, {
             stdio: ["ignore", "ignore", "pipe"],
             env: libpqChildEnv(extraEnv, process.env, opts),
         });
+        // `kill <pid>` 只发给 node 时 pg_restore 收不到;中断时由我们停掉它
+        stopOnInterrupt(proc);
         let stderr = "";
-        proc.stderr.on("data", (d) => (stderr += d.toString()));
+        proc.stderr.setEncoding("utf8");
+        proc.stderr.on("data", (d) => (stderr += d));
         // 不透传原始 spawn Error:node 会把 spawnargs(含 --dbname 连接串=凭据)挂在
         // 异常对象上,顺着 reject 流进日志/Sentry。只保留启动失败的事实与 bin 名。
         proc.on("error", (error) => reject(new Error(`${bin} failed to start: ${error.code ?? error.message}`)));
@@ -326,27 +338,36 @@ export function quoteIdent(name) {
  * 装不上的扩展如实收集返回,由调用方按目标类型裁决:沙箱记录后继续(托管扩展
  * 本就装不上,public 转储通常不引用),真实目标应当阻断(用户能在 dashboard 开启)。
  */
-export async function installExtensions(connString, extensions) {
+export async function installExtensions(connString, extensions, 
+/** 调用方开着的事务:装在它里面(每个扩展一个保存点,装不上的不连累别的),提交与否由调用方定 */
+inTransaction) {
     if (!extensions.length)
         return [];
     // pgConnectOptions:Supabase 主机自动带打包根 CA(node-pg 把 require 按 verify-full
     // 处理,裸 Client 对 pooler 必报 self-signed chain);沙箱等非 Supabase 目标原样透传
-    const client = await connectPg(connString);
+    const client = inTransaction ?? (await connectPg(connString));
     const unavailable = [];
     try {
         for (const ext of extensions) {
+            if (inTransaction)
+                await client.query("savepoint backupdrill_extension");
             try {
                 await client.query(`create schema if not exists ${quoteIdent(ext.schema)}`);
                 // CASCADE 自动带上依赖扩展,免受 manifest 里的安装顺序摆布
                 await client.query(`create extension if not exists ${quoteIdent(ext.name)} schema ${quoteIdent(ext.schema)} cascade`);
+                if (inTransaction)
+                    await client.query("release savepoint backupdrill_extension");
             }
             catch {
+                if (inTransaction)
+                    await client.query("rollback to savepoint backupdrill_extension");
                 unavailable.push(ext.name);
             }
         }
     }
     finally {
-        await client.end();
+        if (!inTransaction)
+            await client.end();
     }
     return unavailable;
 }
@@ -406,10 +427,9 @@ export async function installSandboxShim(connString, opts) {
     }
 }
 /**
- * 两遍恢复(真实首演炸出的设计,现为 drill 与真实恢复共用):
+ * 两遍恢复(真实首演炸出的设计;2.7.0 起只用于演练沙箱,真实目标见 restoreInOneTransaction):
  * 1. pre-data+data —— 表结构 + 数据。除 schema 冲突(预期)外任何错误都是硬失败。
- * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;allowlist 按目标类型:
- *    沙箱豁免 Supabase 托管对象引用,真实 Supabase 目标零豁免。
+ * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;沙箱豁免 Supabase 托管对象引用。
  */
 /**
  * 凭据不进 argv(D6 同源要求):连接串里的密码对 `ps` 全程可见——拆出来经
@@ -587,17 +607,25 @@ export function splitPostDataList(listing) {
     }
     return { indexBuilds, rest };
 }
-function listPostData(bin, dumpPath) {
+/** 不连库的 pg_restore(--list、-f - 出 SQL),整段收集 stdout。只用于目录和 DDL 这类小输出。 */
+export function pgRestoreOutput(bin, args) {
+    // 和 spawnPgRestore 一样:收到信号之后不再起,起了的中断时停掉(并行演练里读目录的那一步也是它)
+    if (interrupted())
+        return Promise.reject(new Error("interrupted; not starting pg_restore"));
     return new Promise((resolve, reject) => {
         // 只读归档、不连库,但同样钉 C locale,和恢复子进程一致
-        const proc = spawn(bin, ["--list", "--section=post-data", dumpPath], {
+        const proc = spawn(bin, args, {
             stdio: ["ignore", "pipe", "pipe"],
             env: libpqChildEnv(),
         });
+        stopOnInterrupt(proc);
         let stdout = "";
         let stderr = "";
-        proc.stdout.on("data", (d) => (stdout += d.toString()));
-        proc.stderr.on("data", (d) => (stderr += d.toString()));
+        // 按流解码:一个多字节字符可能被拆在两块里,逐块 toString 会把它解坏(schema 名里的中文就会对不上)
+        proc.stdout.setEncoding("utf8");
+        proc.stderr.setEncoding("utf8");
+        proc.stdout.on("data", (d) => (stdout += d));
+        proc.stderr.on("data", (d) => (stderr += d));
         proc.on("error", (error) => reject(new Error(`${bin} failed to start: ${error.code ?? error.message}`)));
         proc.on("close", (code) => resolve({ code, stdout, stderr }));
     });
@@ -617,6 +645,88 @@ function mergePasses(passes) {
         failures: passes.flatMap((pass) => pass.failures),
     };
 }
+/**
+ * 真实目标:整份归档一次 `pg_restore --single-transaction`(隐含 --exit-on-error),任何一条语句失败,
+ * 连接断开,服务端回滚,目标上不留任何东西。Supabase 官方的整库恢复指引(psql --single-transaction
+ * + ON_ERROR_STOP)也是这个做法。
+ *
+ * 唯一的障碍是文件头注 3 的预期冲突:dump 自带 CREATE SCHEMA public,一报错整个事务就没了。所以先用
+ * 目录(-L)把**目标上已经存在**的 schema 条目拿掉,其余照原顺序原样恢复;目标上没有的 schema
+ * (比如 BACKUPDRILL_SCHEMAS 里的自定义 schema)照常 CREATE。拿掉之后就没有任何可以容忍的错误了,
+ * 和两遍恢复时真实目标"除 schema 冲突外零豁免"的口径一致。
+ * 代价是锁:每张表连同索引、序列、TOAST 各占一个锁槽,直到提交。max_connections 60 的目标上实测
+ * 900 张表能过、1200 张表报 out of shared memory(restore.ts restoreFailureAdvice 给出调参办法);
+ * 撞上了也是整体回滚,不会留半截。
+ */
+async function restoreInOneTransaction(bin, dumpPath, connString, common, env, childOpts) {
+    const fail = (failure) => ({ expectedSkips: 0, failures: [failure] });
+    const listing = await pgRestoreOutput(bin, ["--list", dumpPath]);
+    if (listing.code !== 0) {
+        return fail(`pg_restore --list exited with code ${listing.code}: ${listing.stderr.trim().replace(/\s+/g, " ").slice(0, 200)}`);
+    }
+    const entries = listing.stdout.split("\n").filter((line) => /^\d+;/.test(line));
+    const listDir = await mkdtemp(join(tmpdir(), "backupdrill-restore-"));
+    try {
+        // 目录行里的名字和属主之间只隔一个空格,名字本身又可以带空格,拆不准。让 pg_restore 把这几条
+        // 写成 SQL,按顺序读 CREATE SCHEMA 后面的标识符,第 i 条语句就是第 i 行
+        const schemaEntries = entries.filter((line) => /^\d+; \d+ \d+ SCHEMA - /.test(line));
+        const skip = new Set();
+        if (schemaEntries.length) {
+            const schemaList = join(listDir, "schemas.list");
+            await writeFile(schemaList, schemaEntries.join("\n") + "\n");
+            const ddl = await pgRestoreOutput(bin, ["-f", "-", `--use-list=${schemaList}`, dumpPath]);
+            const names = parseCreateSchemas(ddl.stdout);
+            if (ddl.code !== 0 || names.length !== schemaEntries.length) {
+                return fail(`could not read the schema entries in the archive (pg_restore exited with code ${ddl.code})`);
+            }
+            const client = await connectPg(connString);
+            try {
+                const existing = await client.query("select nspname from pg_namespace where nspname = any($1::text[])", [names]);
+                const present = new Set(existing.rows.map((row) => row.nspname));
+                schemaEntries.forEach((line, i) => {
+                    if (present.has(names[i]))
+                        skip.add(line);
+                });
+            }
+            finally {
+                await client.end();
+            }
+        }
+        const listFile = join(listDir, "restore.list");
+        await writeFile(listFile, entries.filter((line) => !skip.has(line)).join("\n") + "\n");
+        const run = await spawnPgRestore(bin, ["--single-transaction", `--use-list=${listFile}`, ...common], env, childOpts);
+        if (run.code === 0)
+            return { expectedSkips: 0, failures: [] };
+        if (run.code === null)
+            return fail(`pg_restore was killed by a signal: ${firstRestoreError(run.stderr)}`);
+        return fail(firstRestoreError(run.stderr));
+    }
+    finally {
+        await rm(listDir, { recursive: true, force: true });
+    }
+}
+/**
+ * 单事务恢复只会有一条错误(--exit-on-error)。给人看的形态:主消息 + DETAIL/HINT 全文,再带上出错
+ * 语句的开头,方便认出是哪个对象。不再截成 200 字符——那样会把 "is not present in table" 这半句
+ * 切掉,用户看不出缺的是什么(2026-10-22 实验原样截在 "is no")。
+ */
+export function firstRestoreError(stderr) {
+    const block = stderr.split(/(?=pg_restore: error:)/).find((b) => b.startsWith("pg_restore: error:"));
+    if (!block)
+        return stderr.trim().replace(/\s+/g, " ").slice(0, 300) || "(no stderr)";
+    const lines = block.split("\n");
+    const message = lines[0]
+        .replace(/^pg_restore: error: (?:could not execute query: )?/, "")
+        .replace(/^ERROR:\s+/, "")
+        .trim();
+    const details = lines.filter((line) => /^(?:DETAIL|HINT):/.test(line)).map((line) => line.replace(/\s+/g, " ").trim());
+    const commandAt = lines.findIndex((line) => line.startsWith("Command was:"));
+    const command = commandAt < 0
+        ? ""
+        : lines.slice(commandAt).join(" ").replace(/^Command was:\s*/, "").replace(/\s+/g, " ").trim();
+    const statement = command ? ` (statement: ${command.length > 160 ? `${command.slice(0, 160)}…` : command})` : "";
+    return [message, ...details].join(" ") + statement;
+}
 /**
  * 两遍恢复(形状见 credentialSafeDbArgs 上方那段"两遍恢复"注释),`jobs` > 1 时按下面的方式并行(2026-10-17 实测:2 核机器上同一份
  * dump,原生 -j2 比 -j1 在 5 GB 快 14%、10 GB 快 12%):
@@ -627,8 +737,8 @@ function mergePasses(passes) {
  * 2. post-data 拆成两份清单(splitPostDataList):建索引那份并行,退出码 0 即通过,报过错
  *    的条目单连接重跑定结论;其余单连接、照旧按目标类型分类。
  *    两遍下来,同一份备份不管几路并行,结论都和 jobs=1 一样。
- * 真实 Supabase 目标(restore.ts)不传 jobs:每一路都是一条 pooler 连接,小规格项目的连接数
- * 和算力都紧,并行没测过,保持原来的单连接两遍。
+ * 真实 Supabase 目标(restore.ts)不走这里:单事务恢复(restoreInOneTransaction)不能并行,
+ * 而且每一路都是一条 pooler 连接,小规格项目的连接数和算力都紧。
  */
 export async function restoreDatabaseArtifact(opts) {
     const bin = resolvePgRestoreBin();
@@ -638,6 +748,10 @@ 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) };
+    if (opts.target === "supabase") {
+        const pass = await restoreInOneTransaction(bin, opts.dumpPath, opts.connString, common, env, childOpts);
+        return { preData: pass, postData: { expectedSkips: 0, failures: [] }, ok: pass.failures.length === 0 };
+    }
     const jobs = Math.max(1, Math.floor(opts.jobs ?? 1));
     const parallel = jobs > 1;
     const jobsArg = parallel ? [`--jobs=${jobs}`] : [];
@@ -652,7 +766,7 @@ export async function restoreDatabaseArtifact(opts) {
         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);
+    const listing = await pgRestoreOutput(bin, ["--list", "--section=post-data", 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}`] };
@@ -660,6 +774,7 @@ export async function restoreDatabaseArtifact(opts) {
     }
     const { indexBuilds, rest } = splitPostDataList(listing.stdout);
     const listDir = await mkdtemp(join(tmpdir(), "backupdrill-restore-"));
+    const forgetListDir = onInterrupt(() => rm(listDir, { recursive: true, force: true }).catch(() => { }));
     try {
         const passes = [];
         if (indexBuilds.length) {
@@ -704,5 +819,88 @@ export async function restoreDatabaseArtifact(opts) {
     }
     finally {
         await rm(listDir, { recursive: true, force: true });
+        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.d.ts

@@ -68,6 +68,13 @@ export declare function assertConfirmedTarget(confirmTarget: string | undefined,
  * 用户会以为自己漏了一步,其实只需要换一个空项目。
  */
 export declare function nonEmptyTargetMessage(schemas: string[], objectCount: number, alsoRestoringStorage: boolean): string;
+/**
+ * 单事务恢复特有的失败:每张表连同它的索引、序列、TOAST 表在提交前都占着一个锁槽。槽数 =
+ * max_locks_per_transaction × (max_connections + …),Supabase 最小规格(max_connections 60)实测
+ * 900 张表能过、1200 张表报 out of shared memory(2026-10-23,PG 17)。分区多的库会撞上。
+ * Supabase 只能用 CLI 调这个参数(会重启数据库),照官方文档的命令给出来。
+ */
+export declare function restoreFailureAdvice(failure: string): string;
 /**
  * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
  * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),