backupdrill 2.6.0 → 2.7.0

package/README.md

@@ -59,7 +59,7 @@ Configure via **env vars**, a **config file**, or **flags** (precedence: flags >
 ### Env vars
 
 ```bash
-export BACKUPDRILL_DATABASE_URL="postgresql://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com:5432/postgres"
+export BACKUPDRILL_DATABASE_URL="postgresql://postgres.<ref>:<pw>@<pooler-host>:5432/postgres"
 export BACKUPDRILL_PROJECT_NAME="my-app"
 export BACKUPDRILL_S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com"  # omit for AWS S3
 export BACKUPDRILL_S3_REGION="auto"
@@ -98,7 +98,7 @@ backupdrill backup --config backupdrill.config.json
 
 ## Get the connection string
 
-Use the **Session Pooler** string from your Supabase dashboard (Project Settings → Database → Connection string → Session pooler). The default `postgres` user works as-is — it owns your tables, so `pg_dump` passes row-level security.
+Use the **Session pooler** string: in the Supabase dashboard, open your project, click **Connect** at the top of the page and pick **Session pooler**. Copy the whole string rather than typing the host yourself, because the pooler host can't be worked out from the region. Replace `[YOUR-PASSWORD]` with the database password (percent-encode characters like `@` or `#`). The default `postgres` user works as-is — it owns your tables, so `pg_dump` passes row-level security.
 
 **Least-privilege role (advanced, usually not viable on Supabase):** `pg_dump` needs `select` on *sequences* too, and it **errors on any RLS-enabled table the role can't bypass** — and most Supabase tables have RLS on, while `bypassrls` can't be granted without superuser. Only use a dedicated role if your schema has no RLS tables:
 
@@ -176,6 +176,8 @@ Backups record your installed Postgres extensions in the manifest, and the drill
 
 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.
 
+Ctrl+C (or a SIGTERM from whatever runs the drill) stops it and cleans up: the CLI stops a running `--check-cmd` and `pg_restore`, removes the sandbox container and its volume, deletes the downloaded dump, and exits with 130 (143 for SIGTERM). `--keep` doesn't apply to an interrupted drill. Press Ctrl+C a second time to exit without waiting for the cleanup.
+
 ### 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:
@@ -186,7 +188,7 @@ backupdrill drill --check-cmd "npm run smoke"   # BACKUPDRILL_SANDBOX_URL points
 
 Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_URL` set to the sandbox's connection string. Exit 0 means pass; the result shows up in the report as an `app checks` line, and a non-zero exit fails the drill (the report keeps structural and app-level failures clearly separate). Entirely optional — without the flag, nothing changes and the report has no `app checks` line. There's a 10-minute timeout (the whole process tree is killed), and `--keep` leaves the sandbox container running when a drill fails so you can inspect it — the report JSON then includes a `keptSandbox` object with the container id and connection string (`docker rm -f <id>` when done).
 
-**What this can and cannot verify, honestly:** `BACKUPDRILL_SANDBOX_URL` connects as the sandbox **superuser**, and superusers bypass row-level security. The sandbox does carry a stub of the Supabase runtime — an `auth` schema whose `uid()`/`jwt()`/`role()`/`email()` return null, and the `anon`/`authenticated`/`service_role` roles — so functions, column defaults and policies that reference them restore instead of being skipped. The sandbox deliberately does not create Supabase-managed *tables* such as `auth.users`: an index, constraint or policy that points at one is reported as a skipped managed object (these are restored in a second, post-data pass where that exemption applies), while a *view* over one is created in the strict first pass and fails the drill — a real gap in what a public-only backup can rebuild, shown rather than hidden. A function *body* that selects from `auth.users` is different: PostgreSQL does not validate string-literal bodies (`AS $$ … $$`) during a restore (`check_function_bodies` is off in every dump), so such a function is recreated and the drill passes — it would only fail when called. The exception is an SQL-standard `BEGIN ATOMIC … END` body, which is parsed and dependency-checked at creation regardless of that setting, so one of those referencing a managed table fails the drill like a view does. That is exactly what `--check-cmd` is for: if your application depends on such a function, call it there. So use `--check-cmd` for data and business invariants ("orders reference existing users", "the row count I care about is sane"). It is **not** an RLS behavior test — `auth.uid()` is a stub and you are a superuser; verifying RLS takes an authenticated client stack with real JWTs, which no restore sandbox can fake generically.
+**What this can and cannot verify, honestly:** `BACKUPDRILL_SANDBOX_URL` connects as the sandbox **superuser**, and superusers bypass row-level security. The sandbox does carry a stub of the Supabase runtime — an `auth` schema whose `uid()`/`jwt()`/`role()`/`email()` return null, and the `anon`/`authenticated`/`service_role` roles — so functions, column defaults and policies that reference them restore instead of being skipped. The sandbox deliberately does not create Supabase-managed *tables* such as `auth.users`: an index, constraint or policy that points at one is reported as a skipped managed object (these are restored in a second, post-data pass where that exemption applies). A skipped foreign key into `auth.users` still matters for a real restore, see [Tables that reference auth.users](#tables-that-reference-authusers). A *view* over one is created in the strict first pass instead, and fails the drill — a real gap in what a public-only backup can rebuild, shown rather than hidden. A function *body* that selects from `auth.users` is different: PostgreSQL does not validate string-literal bodies (`AS $$ … $$`) during a restore (`check_function_bodies` is off in every dump), so such a function is recreated and the drill passes — it would only fail when called. The exception is an SQL-standard `BEGIN ATOMIC … END` body, which is parsed and dependency-checked at creation regardless of that setting, so one of those referencing a managed table fails the drill like a view does. That is exactly what `--check-cmd` is for: if your application depends on such a function, call it there. So use `--check-cmd` for data and business invariants ("orders reference existing users", "the row count I care about is sane"). It is **not** an RLS behavior test — `auth.uid()` is a stub and you are a superuser; verifying RLS takes an authenticated client stack with real JWTs, which no restore sandbox can fake generically.
 
 When you actually need to recover, `restore` puts the database back into a fresh
 target project (through the same engine the drills use, with verification) and
@@ -202,6 +204,8 @@ backupdrill restore --database --target-supabase-url https://<ref>.supabase.co -
 
 Prefer files on disk instead? Skip the Storage target and pass `--storage-dir ./recovered`.
 
+`--dry-run` writes nothing to the target. Besides checking the target (not the source project, schemas empty, Postgres and `pg_restore` versions, extensions available), it downloads the dump to a temporary directory, checks its sha256 and looks for foreign keys that point outside the backup (see [Tables that reference auth.users](#tables-that-reference-authusers)). The real run repeats those checks before it writes anything; a foreign key into a table that one of the recorded extensions creates is checked again once the extensions are installed. The database restore then runs in a single transaction: if any statement fails, nothing from the snapshot stays on the target, and you can run it again on the same project once you've fixed the cause. (If the connection drops while it commits, the error says so and asks you to check the target first.) Extensions the run installed stay installed, since the next run needs them too, and the empty-target check doesn't count objects that belong to an extension (except an extension's configuration tables, whose rows a dump can carry). One transaction holds a lock on every table, index and sequence until it commits, so a very large schema can run out of lock slots: on Supabase's smallest compute size, about a thousand tables (partitions count as tables). The restore then stops with nothing written and tells you how to raise `max_locks_per_transaction`.
+
 Or restore the dump by hand — into an **empty** database, without `--clean`:
 
 ```bash
@@ -211,8 +215,35 @@ pg_restore --no-owner --no-privileges --dbname "<target-connection-string>" dump
 Don't use `--clean` against a Supabase project: dropping and recreating the `public`
 schema silently wipes Supabase's default grants for `anon`/`authenticated` (the dump
 carries no ACLs), leaving the restored API returning 401s. One error is expected and
-harmless: `schema "public" already exists` — the target always has it. The
-`backupdrill restore` command above handles all of this (plus verification) for you.
+harmless: `schema "public" already exists` — the target always has it. An error
+on a foreign key into `auth.users` means the users have to be copied in first (see
+the next section). The `backupdrill restore` command above handles all of this (plus
+verification) for you.
+
+### Tables that reference auth.users
+
+By default a backup covers the `public` schema only, so your Auth users are not in it. Plenty of Supabase apps have a table like `profiles` whose `id` is a foreign key to `auth.users(id)`. When the restore recreates that key in a new project, Postgres checks every `profiles` row against `auth.users`, and in a new project that table is empty, so the restore fails.
+
+A drill can't catch this. Its sandbox has no `auth.users` at all, so the drill reports that foreign key as a skipped Supabase-managed object and passes. `restore --dry-run` checks it against the real target and tells you how many rows have nothing to point at:
+
+```
+✗ references outside the backup: public.profiles → auth.users (profiles_id_fkey): 200 of 200 row(s) point at auth.users rows the target doesn't have
+```
+
+While that check fails, no snapshot data is written. Copy the users into the new project first, then run the restore. While the old project is still reachable, the Postgres tools can do it. Use the Session pooler string of each project, and type the passwords at hidden prompts so they stay out of your shell history:
+
+```bash
+read -rs OLD_PW; read -rs NEW_PW
+PGPASSWORD="$OLD_PW" pg_dump --data-only --table=auth.users --table=auth.identities \
+  "postgresql://postgres.<old-ref>@<old-pooler-host>:5432/postgres" |
+  PGPASSWORD="$NEW_PW" psql -v ON_ERROR_STOP=1 \
+  "postgresql://postgres.<new-ref>@<new-pooler-host>:5432/postgres"
+unset OLD_PW NEW_PW
+```
+
+`auth.identities` holds each user's sign-in methods; users copied with it can sign in to the new project with their old password. If the old project is gone, the users can only come from a backup that includes the `auth` schema, such as Supabase's own daily backups on a paid plan. A backupdrill snapshot of `public` doesn't have them.
+
+Triggers you created on `auth.users`, such as the common one that inserts a `profiles` row on sign-up, belong to that table, so they aren't in the backup either. Create them again after the restore.
 
 ## 2.0 migration — `restore` flags changed
 

package/dist/drill.js

@@ -1,4 +1,5 @@
 import { execFile, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -10,6 +11,7 @@ import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions,
 import { connectPg } from "./supabase-ca.js";
 import { localPgRestoreMajor, restoreToolBreaksOnTarget, sandboxMajorFor } from "./pgbin.js";
 import { log } from "./log.js";
+import { onInterrupt, stopOnInterrupt, throwIfInterrupted } from "./interrupt.js";
 const execFileAsync = promisify(execFile);
 // Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
 const STORAGE_SAMPLE_CAP = 100;
@@ -133,6 +135,26 @@ export function sandboxDataVolumeTarget(major) {
     // PG18 将镜像的 VOLUME 上移一层;挂错路径会额外生成无法按名字回收的匿名卷。
     return major >= 18 ? "/var/lib/postgresql" : "/var/lib/postgresql/data";
 }
+/**
+ * 沙箱镜像先单独拉好。让 docker run 自己拉的话,拉取和建容器在同一个命令里:中断落在拉取中途,
+ * 停掉命令也说不准守护进程之后还会不会把容器建出来(交叉审查)。拆开之后,慢的那一步(第一次拉镜像
+ * 可能好几分钟)什么都不建,中断时直接停掉;docker run 只剩建容器和启动。
+ */
+async function ensureImage(image) {
+    const present = await execFileAsync("docker", ["image", "inspect", "--format", "{{.Id}}", image]).then(() => true, () => false);
+    if (present)
+        return;
+    throwIfInterrupted();
+    log.step(`Pulling ${image}…`);
+    const pull = execFileAsync("docker", ["pull", "--quiet", image]);
+    const forget = pull.child ? stopOnInterrupt(pull.child) : () => { };
+    try {
+        await pull;
+    }
+    finally {
+        forget();
+    }
+}
 async function startEphemeralPostgres(image, major, resourceName) {
     const dataVolumeTarget = sandboxDataVolumeTarget(major);
     if (resourceName) {
@@ -144,12 +166,17 @@ async function startEphemeralPostgres(image, major, resourceName) {
     log.step(`Starting ephemeral ${image}…`);
     const resources = await dockerResources();
     const tuning = sandboxTuning(resources.memoryBytes, resources.cpus);
-    const { stdout } = await execFileAsync("docker", [
+    await ensureImage(image);
+    // 名字先定好:Ctrl+C 可能落在 docker run 还没返回 ID 的时候,按名字才删得掉
+    const name = resourceName ?? `backupdrill-drill-${randomBytes(6).toString("hex")}`;
+    throwIfInterrupted();
+    const started = execFileAsync("docker", [
         "run",
         "-d",
         "--rm",
-        ...(resourceName ? ["--name", resourceName, "--mount",
-            `type=volume,source=${resourceName},target=${dataVolumeTarget}`] : []),
+        "--name",
+        name,
+        ...(resourceName ? ["--mount", `type=volume,source=${resourceName},target=${dataVolumeTarget}`] : []),
         "-e",
         "POSTGRES_PASSWORD=drill",
         "-e",
@@ -161,10 +188,59 @@ async function startEphemeralPostgres(image, major, resourceName) {
         "postgres",
         ...tuning.settings.flatMap((kv) => ["-c", kv]),
     ]);
+    // 删容器只有一份:正常收尾(drillDump 的 finally)和中断收尾(interrupt.ts)等的是同一个 promise。
+    // 两边各发一次 docker rm 会撞上 "removal already in progress",后到的那个报删除失败,
+    // 进程又在真正删完之前就退出了(信号测试抓到的竞争)。
+    let volumeName = resourceName ?? null;
+    let runSettled = false;
+    started.then(() => (runSettled = true), () => (runSettled = true));
+    const removeByName = async () => {
+        try {
+            // -v 连匿名卷一起删:中断可能落在下面查卷名之前
+            await execFileAsync("docker", ["rm", "-fv", name], { timeout: 60_000 });
+        }
+        catch (error) {
+            if (!/No such container/i.test(String(error.stderr ?? error))) {
+                log.warn(`could not remove the drill sandbox; remove it with: docker rm -fv ${name}`);
+            }
+        }
+    };
+    let teardownRun = null;
+    const teardown = () => (teardownRun ??= (async () => {
+        if (!runSettled) {
+            // 中断落在 docker run 还没返回的时候。镜像已经在本地(ensureImage),它只剩建容器和启动,
+            // 等它落定再按名字删:中途停掉命令说不准守护进程会不会稍后把容器建出来(交叉审查复现)。
+            // Docker 迟迟不回话就不等了,把容器名告诉用户
+            let timer;
+            const settled = await Promise.race([
+                started.then(() => true, () => true),
+                new Promise((resolve) => (timer = setTimeout(() => resolve(false), 20_000))),
+            ]);
+            clearTimeout(timer);
+            if (!settled) {
+                started.child?.kill("SIGKILL");
+                log.warn(`docker run did not finish within 20s; if a container named ${name} shows up later, ` +
+                    `remove it with: docker rm -fv ${name}`);
+            }
+        }
+        await removeByName();
+        // 显式删卷(--rm 不可靠,见下);幂等,已经没了也不报错
+        if (volumeName)
+            await execFileAsync("docker", ["volume", "rm", "-f", volumeName]).catch(() => { });
+    })());
+    const forgetInterruptCleanup = onInterrupt(teardown);
+    let stdout;
+    try {
+        ({ stdout } = await started);
+    }
+    catch (error) {
+        forgetInterruptCleanup();
+        throw error;
+    }
     const containerId = stdout.trim();
     // postgres 镜像把数据目录声明成 VOLUME → 每次 run 都建一个匿名卷。生产实测 `--rm` **没有**把它
     // 带走(一次演练遗留 37.6 GB,三次失败把 59 GB 根盘灌满),所以记下卷名,销毁容器后显式删。
-    const volumeName = resourceName ?? await execFileAsync("docker", [
+    volumeName = resourceName ?? await execFileAsync("docker", [
         "inspect",
         "-f",
         '{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}',
@@ -198,7 +274,7 @@ async function startEphemeralPostgres(image, major, resourceName) {
                     "postgres",
                     "-q",
                 ]);
-                return { containerId, port, connString, volumeName, restoreJobs: tuning.restoreJobs };
+                return { containerId, port, connString, restoreJobs: tuning.restoreJobs, teardown, forgetInterruptCleanup };
             }
             catch {
                 await new Promise((r) => setTimeout(r, 500));
@@ -207,9 +283,8 @@ async function startEphemeralPostgres(image, major, resourceName) {
         throw new Error("ephemeral Postgres did not become ready within 30s");
     }
     catch (error) {
-        await execFileAsync("docker", ["rm", "-f", containerId]).catch(() => { });
-        if (volumeName)
-            await execFileAsync("docker", ["volume", "rm", "-f", volumeName]).catch(() => { });
+        await teardown();
+        forgetInterruptCleanup();
         throw error;
     }
 }
@@ -381,6 +456,8 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
             // 孙进程会在沙箱销毁后继续跑(xreview 抓出的资源泄漏)。
             detached: true,
         });
+        // 也因为自成一组,终端的 Ctrl+C 到不了它:中断时由我们按组停掉
+        stopOnInterrupt(proc, { group: true });
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
@@ -484,6 +561,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
             });
         }
         await opts.supervision?.observe({ phase: "restore" });
+        throwIfInterrupted();
         const started = Date.now();
         log.step("Restoring into ephemeral Postgres…");
         let postData;
@@ -514,7 +592,11 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
             detail: postData.failures.length > 0
                 ? `${postData.failures.length} failed: ${postData.failures[0]}`
                 : postData.supabaseSkipped > 0
-                    ? `user objects restored; ${postData.supabaseSkipped} Supabase-managed object(s) skipped (Supabase-managed tables such as auth.users do not exist in the drill sandbox)`
+                    ? // 说清跳过的是什么,以及它对真实恢复意味着什么:2026-10-22 实验里演练 PASS,
+                        // 恢复却死在被跳过的那条 FK → auth.users 上,因为新项目的 auth.users 是空的
+                        `user objects restored; ${postData.supabaseSkipped} Supabase-managed object(s) skipped ` +
+                            `(they reference tables such as auth.users, which the drill sandbox doesn't have; ` +
+                            `restoring into a new project needs the rows they point at to be there first)`
                     : "all post-data objects restored",
         });
         await opts.supervision?.observe({ phase: "verify" });
@@ -523,6 +605,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
         // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
         // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。
         if (appCheckCommand && checks.every((c) => c.pass)) {
+            throwIfInterrupted();
             log.step("Running app checks…");
             checks.push(await runAppCheck(appCheckCommand, pg.connString));
         }
@@ -559,11 +642,10 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
         else {
             await observeCleanup(opts.supervision);
             log.step("Tearing down ephemeral Postgres…");
-            await execFileAsync("docker", ["rm", "-f", pg.containerId]).catch(() => { });
-            // 显式删匿名卷(--rm 不可靠,见 startEphemeralPostgres);幂等,已被 --rm 带走也不报错
-            if (pg.volumeName)
-                await execFileAsync("docker", ["volume", "rm", "-f", pg.volumeName]).catch(() => { });
+            await pg.teardown();
         }
+        // 删完了,或者按 --keep 有意留着:之后再收到信号都不该再动它
+        pg.forgetInterruptCleanup();
     }
 }
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
@@ -576,6 +658,10 @@ export async function runDrill(config, opts = {}) {
     const manifest = parseManifest(await reader.readManifest());
     const workdir = opts.supervision?.workdir ?? await mkdtemp(join(tmpdir(), "backupdrill-"));
     const dumpPath = join(workdir, "dump.pgcustom");
+    // 下载的 dump 在这里;托管模式的目录归 supervisor 管
+    const forgetWorkdir = opts.supervision
+        ? () => { }
+        : onInterrupt(() => rm(workdir, { recursive: true, force: true }).catch(() => { }));
     try {
         await opts.supervision?.observe({ phase: "download", dumpBytes: manifest.dump.bytes });
         log.step("Downloading dump…");
@@ -623,5 +709,6 @@ export async function runDrill(config, opts = {}) {
     finally {
         if (!opts.supervision)
             await rm(workdir, { recursive: true, force: true }).catch(() => { });
+        forgetWorkdir();
     }
 }

package/dist/dump-sql.d.ts

@@ -0,0 +1,52 @@
+export interface QualifiedName {
+    schema: string;
+    name: string;
+}
+export declare function unquoteIdent(ident: string): string;
+export declare function formatQualified(name: QualifiedName): string;
+/** `pg_restore -f - -L <只含 SCHEMA 条目的清单>` 的输出 → 按出现顺序的 schema 名。 */
+export declare function parseCreateSchemas(sql: string): string[];
+export interface ForeignKeyDef {
+    constraint: string;
+    table: QualifiedName;
+    columns: string[];
+    references: QualifiedName;
+    referencedColumns: string[];
+    /**
+     * ADD CONSTRAINT 时会不会校验已有的行。NOT VALID(源库就没校验过)和 PG18 的 NOT ENFORCED
+     * 都不校验,恢复不会因为缺行而失败,所以不用查。
+     */
+    validatesRows: boolean;
+}
+/**
+ * pg_dump 的外键语句(dumpConstraint):
+ *   ALTER [FOREIGN ]TABLE [ONLY ]<表>\n    ADD CONSTRAINT <名> FOREIGN KEY (<列>) REFERENCES <表>(<列>)<选项>;
+ * 分区父表上的外键没有 ONLY。认不出的形态(如 PG18 的 PERIOD 时态外键)不返回,
+ * 调用方拿条目数对账,差多少就如实报多少条没检查。
+ */
+export declare function parseForeignKeys(sql: string): ForeignKeyDef[];
+/** pg_dump 的挂分区语句(dumpTableAttach):ALTER TABLE ONLY <父> ATTACH PARTITION <子> <边界>; */
+export declare function parsePartitionAttachments(sql: string): Array<{
+    parent: QualifiedName;
+    child: QualifiedName;
+}>;
+/**
+ * pg_dump 的建表语句(dumpTableSchema)里每列的类型,按表(schema\0name)→ 列 → 类型。
+ *   CREATE [UNLOGGED ]TABLE <表> (\n    <列> <类型>[ COLLATE …][ DEFAULT …][ NOT NULL],\n    CONSTRAINT …\n)…;
+ * 类型是 format_type 的输出,本身不含 COLLATE/DEFAULT/NOT NULL/GENERATED 这些词,读到它们为止。
+ * 带引号的列名可以跨行,所以按位置往下读,不按行切。
+ */
+export declare function parseTableColumns(sql: string): Map<string, Map<string, string>>;
+/**
+ * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
+ * 所以那一行中间是两个空格,返回空列表。
+ */
+export declare function parseCopyHeader(line: string): {
+    table: QualifiedName;
+    columns: string[];
+} | null;
+/**
+ * COPY 文本格式的一个字段 → 值(\N = NULL)。转义规则照 PostgreSQL 文档 "COPY / Text Format":
+ * \b \f \n \r \t \v \\,\ 加 1–3 位八进制,\x 加 1–2 位十六进制,其余 \c 就是 c 本身。
+ */
+export declare function decodeCopyField(field: string): string | null;

package/dist/dump-sql.js

@@ -0,0 +1,112 @@
+// 读 pg_restore 吐出来的 SQL(纯函数,可单测)。只认 pg_dump 自己的输出格式:
+// 名字一律由 fmtId / quote_identifier 生成——[a-z_][a-z0-9_]* 原样,其余加双引号、内嵌引号翻倍,
+// dump 头部把 search_path 设成空串,所以引用的表总是 schema.name 全限定。
+// 不是通用 SQL 解析器,也不需要是:认不出的语句由调用方如实报"没法检查",不猜。
+const QUOTED_IDENT = String.raw `"(?:[^"]|"")+"`;
+const IDENT = String.raw `(?:${QUOTED_IDENT}|[a-z_][a-z0-9_]*)`;
+const QUALIFIED = String.raw `(${IDENT})\.(${IDENT})`;
+const COLUMNS = String.raw `(${IDENT}(?:\s*,\s*${IDENT})*)`;
+export function unquoteIdent(ident) {
+    return ident.startsWith('"') ? ident.slice(1, -1).replace(/""/g, '"') : ident;
+}
+function splitColumns(list) {
+    return [...list.matchAll(new RegExp(IDENT, "g"))].map((match) => unquoteIdent(match[0]));
+}
+export function formatQualified(name) {
+    const show = (part) => (/^[a-z_][a-z0-9_]*$/.test(part) ? part : `"${part.replace(/"/g, '""')}"`);
+    return `${show(name.schema)}.${show(name.name)}`;
+}
+/** `pg_restore -f - -L <只含 SCHEMA 条目的清单>` 的输出 → 按出现顺序的 schema 名。 */
+export function parseCreateSchemas(sql) {
+    return [...sql.matchAll(new RegExp(String.raw `^CREATE SCHEMA (${IDENT});$`, "gm"))].map((match) => unquoteIdent(match[1]));
+}
+/**
+ * pg_dump 的外键语句(dumpConstraint):
+ *   ALTER [FOREIGN ]TABLE [ONLY ]<表>\n    ADD CONSTRAINT <名> FOREIGN KEY (<列>) REFERENCES <表>(<列>)<选项>;
+ * 分区父表上的外键没有 ONLY。认不出的形态(如 PG18 的 PERIOD 时态外键)不返回,
+ * 调用方拿条目数对账,差多少就如实报多少条没检查。
+ */
+export function parseForeignKeys(sql) {
+    const pattern = new RegExp(String.raw `^ALTER (?:FOREIGN )?TABLE (?:ONLY )?${QUALIFIED}\n {4}ADD CONSTRAINT (${IDENT}) ` +
+        String.raw `FOREIGN KEY \(${COLUMNS}\) REFERENCES ${QUALIFIED}\s*\(${COLUMNS}\)(.*);$`, "gm");
+    return [...sql.matchAll(pattern)].map((match) => {
+        // 选项里可能有带引号的列名(ON DELETE SET NULL ("x")),先去掉再找关键字
+        const options = match[8].replace(new RegExp(QUOTED_IDENT, "g"), "");
+        return {
+            constraint: unquoteIdent(match[3]),
+            table: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+            columns: splitColumns(match[4]),
+            references: { schema: unquoteIdent(match[5]), name: unquoteIdent(match[6]) },
+            referencedColumns: splitColumns(match[7]),
+            validatesRows: !/\bNOT (?:VALID|ENFORCED)\b/.test(options),
+        };
+    });
+}
+/** pg_dump 的挂分区语句(dumpTableAttach):ALTER TABLE ONLY <父> ATTACH PARTITION <子> <边界>; */
+export function parsePartitionAttachments(sql) {
+    const pattern = new RegExp(String.raw `^ALTER TABLE ONLY ${QUALIFIED} ATTACH PARTITION ${QUALIFIED} `, "gm");
+    return [...sql.matchAll(pattern)].map((match) => ({
+        parent: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+        child: { schema: unquoteIdent(match[3]), name: unquoteIdent(match[4]) },
+    }));
+}
+/**
+ * pg_dump 的建表语句(dumpTableSchema)里每列的类型,按表(schema\0name)→ 列 → 类型。
+ *   CREATE [UNLOGGED ]TABLE <表> (\n    <列> <类型>[ COLLATE …][ DEFAULT …][ NOT NULL],\n    CONSTRAINT …\n)…;
+ * 类型是 format_type 的输出,本身不含 COLLATE/DEFAULT/NOT NULL/GENERATED 这些词,读到它们为止。
+ * 带引号的列名可以跨行,所以按位置往下读,不按行切。
+ */
+export function parseTableColumns(sql) {
+    const tables = new Map();
+    const header = new RegExp(String.raw `^CREATE (?:UNLOGGED )?TABLE ${QUALIFIED} \(\n`, "gm");
+    for (const match of sql.matchAll(header)) {
+        const columns = new Map();
+        tables.set(`${unquoteIdent(match[1])}\u0000${unquoteIdent(match[2])}`, columns);
+        let at = match.index + match[0].length;
+        const column = new RegExp(String.raw ` {4}(${IDENT}) (.+?)(?= COLLATE | DEFAULT | NOT NULL| GENERATED |,?\n)`, "y");
+        while (at < sql.length && !sql.startsWith(")", at)) {
+            if (sql.startsWith("    CONSTRAINT ", at)) {
+                at = sql.indexOf("\n", at) + 1 || sql.length;
+                continue;
+            }
+            column.lastIndex = at;
+            const found = column.exec(sql);
+            if (!found)
+                break;
+            columns.set(unquoteIdent(found[1]), found[2]);
+            at = sql.indexOf("\n", column.lastIndex) + 1 || sql.length;
+        }
+    }
+    return tables;
+}
+/**
+ * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
+ * 所以那一行中间是两个空格,返回空列表。
+ */
+export function parseCopyHeader(line) {
+    const match = new RegExp(String.raw `^COPY ${QUALIFIED} (?:\(${COLUMNS}\))? FROM stdin;$`).exec(line);
+    if (!match)
+        return null;
+    return {
+        table: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+        columns: match[3] ? splitColumns(match[3]) : [],
+    };
+}
+/**
+ * COPY 文本格式的一个字段 → 值(\N = NULL)。转义规则照 PostgreSQL 文档 "COPY / Text Format":
+ * \b \f \n \r \t \v \\,\ 加 1–3 位八进制,\x 加 1–2 位十六进制,其余 \c 就是 c 本身。
+ */
+export function decodeCopyField(field) {
+    if (field === "\\N")
+        return null;
+    if (!field.includes("\\"))
+        return field;
+    return field.replace(/\\(?:([0-7]{1,3})|x([0-9a-fA-F]{1,2})|(.))/g, (_, octal, hex, char) => {
+        if (octal)
+            return String.fromCharCode(parseInt(octal, 8));
+        if (hex)
+            return String.fromCharCode(parseInt(hex, 16));
+        const named = { b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v" };
+        return named[char] ?? char;
+    });
+}

package/dist/external-refs.d.ts

@@ -0,0 +1,40 @@
+import type pg from "pg";
+import { type ForeignKeyDef } from "./dump-sql.js";
+export interface CheckedForeignKey {
+    fk: ForeignKeyDef;
+    /** 引用列全非空的行数(MATCH SIMPLE:有一列为空就不校验) */
+    rows: number;
+    /** 其中在目标库找不到被引用行的 */
+    missingRows: number;
+}
+export interface ExternalReferenceCheck {
+    checked: CheckedForeignKey[];
+    /** 恢复一定会失败的原因,一条一句 */
+    problems: string[];
+    /** 没能检查的,一条一句。恢复在一个事务里跑,这些真出问题也会整体回滚,所以只提示不拦 */
+    unchecked: string[];
+    /** 有外键要等扩展装上之后才查得了(见 pendingExtensions) */
+    waitingForExtensions: boolean;
+}
+/**
+ * 读 dump,找出指向 dumpedSchemas 之外的外键,逐条拿目标库对行。只读:目标库上只跑 select。
+ * pg_restore 起不来、归档读不了时抛错,由调用方当成 blocker。单条外键查不成(目标端报错、
+ * 数据块读不了)只影响它自己,记进 unchecked,不拖累别的外键的结论。
+ */
+export declare function checkExternalReferences(opts: {
+    dumpPath: string;
+    dumpedSchemas: string[];
+    targetUrl: string;
+    /**
+     * manifest 里记着、目标上还没装的扩展。有它们在,被引用的表不在、引用方列的类型不在,都可能是
+     * 扩展装上之后才有的(扩展可以往别的 schema 里建表,只看它登记的 schema 不够,交叉审查复现),
+     * 这时报"装完扩展再查",不当成 blocker;正式恢复装完扩展会再查一遍。
+     */
+    pendingExtensions?: string[];
+    /**
+     * 调用方开着的事务(正式恢复里"先装扩展再复查"的那个):在它里面查,看得到还没提交的扩展。
+     * 每条查询包在一个保存点里、查完就回滚到保存点,检查本身留不下任何东西。
+     */
+    inTransaction?: pg.Client;
+}): Promise<ExternalReferenceCheck>;
+export declare function describe(fk: ForeignKeyDef): string;