backupdrill 2.1.8 → 2.2.1

package/dist/backup.d.ts

@@ -1,13 +1,5 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
-/**
- * Parse the major version out of `pg_dump --version` output.
- *
- * MUST tolerate a trailing vendor suffix: Homebrew/macOS prints `pg_dump (PostgreSQL) 17.2`, but
- * Debian/PGDG (what the deployed worker image uses) prints
- * `pg_dump (PostgreSQL) 17.10 (Debian 17.10-1.pgdg120+1)`. Anchoring the match to end-of-string
- * therefore breaks in production while passing on a dev Mac. Anchor on the `(PostgreSQL)` marker
- * instead, falling back to the first dotted version token for non-standard builds.
- */
-export declare function parsePgDumpMajor(raw: string): number | null;
+import { parsePgDumpMajor } from "./pgbin.js";
+export { parsePgDumpMajor };
 export declare function runBackup(config: BackupConfig): Promise<Manifest>;

package/dist/backup.js

@@ -11,6 +11,9 @@ import { renderRecoveryDoc } from "./recovery-doc.js";
 import { projectRefOf, refFromStorageEndpoint, assertNoHostOverride } from "./restore-engine.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
+import { parsePgDumpMajor } from "./pgbin.js";
+// 解析函数搬到了 pgbin(演练与恢复都要读 pg_restore 版本,放这里会成环);保留旧出口
+export { parsePgDumpMajor };
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
 import { libpqChildEnv, urlSslModeOf } from "./restore-engine.js";
 const execFileAsync = promisify(execFile);
@@ -18,19 +21,6 @@ function majorOf(serverVersionNum) {
     // server_version_num: 150004 → 15,  170002 → 17
     return Math.floor(serverVersionNum / 10000);
 }
-/**
- * Parse the major version out of `pg_dump --version` output.
- *
- * MUST tolerate a trailing vendor suffix: Homebrew/macOS prints `pg_dump (PostgreSQL) 17.2`, but
- * Debian/PGDG (what the deployed worker image uses) prints
- * `pg_dump (PostgreSQL) 17.10 (Debian 17.10-1.pgdg120+1)`. Anchoring the match to end-of-string
- * therefore breaks in production while passing on a dev Mac. Anchor on the `(PostgreSQL)` marker
- * instead, falling back to the first dotted version token for non-standard builds.
- */
-export function parsePgDumpMajor(raw) {
-    const match = raw.match(/\(PostgreSQL\)\s+(\d+)/) ?? raw.match(/(\d+)(?:\.\d+)+/);
-    return match ? Number(match[1]) : null;
-}
 async function pgDumpVersion(bin) {
     try {
         const { stdout } = await execFileAsync(bin, ["--version"]);

package/dist/drill.d.ts

@@ -8,6 +8,20 @@ import type { Manifest } from "./manifest.js";
  * 会原样列进报告,定位问题不依赖重放同一批样本。
  */
 export declare function sampleStorageFiles<T>(files: T[], n: number): T[];
+/** @internal 托管 worker 专用钩子;事件不携带客户数据或凭据,不属于稳定 CLI 契约。 */
+export type DrillPhase = "download" | "storage" | "sandbox" | "restore" | "verify" | "cleanup";
+export interface DrillSupervision {
+    /** 仅 runDrill 使用:supervisor 独占的空临时目录,由 supervisor 清理。 */
+    workdir: string;
+    /** 每次尝试唯一;即使 docker run 被中断,supervisor 也能按名字清理。 */
+    resourceName: string;
+    /** 非 cleanup 阶段抛错 = 主动中止并清理;上报失败应由调用方自行吞掉,回调须自带超时(托管 worker 另有进程级执行上限)。
+     * cleanup 阶段同步/异步错误均忽略,最多等待 5 秒,绝不阻止 teardown。 */
+    observe: (event: {
+        phase: DrillPhase;
+        dumpBytes?: number;
+    }) => Promise<void>;
+}
 export interface DrillCheck {
     name: string;
     pass: boolean;
@@ -32,6 +46,7 @@ export interface SandboxTuning {
     shmSize: string;
 }
 export declare function sandboxTuning(totalMemBytes: number): SandboxTuning;
+export declare function sandboxDataVolumeTarget(major: number): string;
 /** post-data 第二遍恢复的结果:用户对象失败 vs Supabase 托管对象的沙箱预期跳过。 */
 interface PostDataResult {
     supabaseSkipped: number;
@@ -65,6 +80,7 @@ export declare function runAppCheck(command: string, connString: string, timeout
 export declare function drillDump(dumpPath: string, manifest: Manifest, snapshot: string, preChecks?: DrillCheck[], opts?: {
     appCheckCommand?: string;
     keepSandboxOnFailure?: boolean;
+    supervision?: DrillSupervision;
 }): Promise<DrillReport>;
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
 export declare function runDrill(config: BackupConfig, opts?: {
@@ -73,5 +89,6 @@ export declare function runDrill(config: BackupConfig, opts?: {
     /** CLI 专用。红线:托管 worker 绝不能传入(在 worker 上执行用户命令 = RCE)。 */
     appCheckCommand?: string;
     keepSandboxOnFailure?: boolean;
+    supervision?: DrillSupervision;
 }): Promise<DrillReport>;
 export {};

package/dist/drill.js

@@ -7,6 +7,7 @@ import { parseManifest } from "./manifest.js";
 import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
 import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, installSandboxShim, } from "./restore-engine.js";
 import { connectPg } from "./supabase-ca.js";
+import { localPgRestoreMajor, restoreToolBreaksOnTarget, sandboxMajorFor } from "./pgbin.js";
 import { log } from "./log.js";
 const execFileAsync = promisify(execFile);
 // Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
@@ -31,10 +32,10 @@ export function sampleStorageFiles(files, n) {
 /**
  * 沙箱镜像选择:alpine 镜像只带 contrib 扩展,装不了 pgvector——含 vector 列的
  * 备份在裸镜像里恢复必然硬崩("type vector does not exist")。manifest 记录了
- * vector 时换用 pgvector 官方镜像(同 major),其余维持轻量 alpine。
+ * vector 时换用 pgvector 官方镜像(同 major),其余维持轻量 alpine。major 由调用方给出
+ * (sandboxMajorFor:源库与本机 pg_restore 取大者),不一定等于源库版本。
  */
-function sandboxImage(manifest) {
-    const major = parseInt(manifest.database.serverVersion, 10);
+function sandboxImage(manifest, major) {
     const hasVector = (manifest.database.extensions ?? []).some((e) => e.name === "vector");
     return hasVector ? `pgvector/pgvector:pg${major}` : `postgres:${major}-alpine`;
 }
@@ -94,13 +95,50 @@ export function sandboxTuning(totalMemBytes) {
         shmSize: `${Math.max(1024, maintenanceWorkMemMib * 2)}m`,
     };
 }
-async function startEphemeralPostgres(image) {
+function validateSupervision(supervision, appCheckCommand, keepSandboxOnFailure) {
+    if (supervision && (appCheckCommand !== undefined || keepSandboxOnFailure)) {
+        throw new Error("Supervised drills cannot execute app commands or keep sandboxes");
+    }
+    if (supervision && !/^bd-drill-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(supervision.resourceName)) {
+        throw new Error("Invalid supervised drill resource name");
+    }
+}
+async function observeCleanup(supervision) {
+    if (!supervision)
+        return;
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(() => supervision.observe({ phase: "cleanup" })),
+            new Promise(resolve => { timer = setTimeout(resolve, 5_000); }),
+        ]);
+    }
+    catch { /* 清理的优先级高于监控,同步抛错也不能挡住 teardown。 */ }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export function sandboxDataVolumeTarget(major) {
+    // PG18 将镜像的 VOLUME 上移一层;挂错路径会额外生成无法按名字回收的匿名卷。
+    return major >= 18 ? "/var/lib/postgresql" : "/var/lib/postgresql/data";
+}
+async function startEphemeralPostgres(image, major, resourceName) {
+    const dataVolumeTarget = sandboxDataVolumeTarget(major);
+    if (resourceName) {
+        const existing = await execFileAsync("docker", ["volume", "ls", "--format", "{{.Name}}", "--filter", `name=^${resourceName}$`], { timeout: 10_000 });
+        if (existing.stdout.trim().split("\n").includes(resourceName)) {
+            throw new Error("Supervised drill volume already exists; refusing to restore into a reused sandbox");
+        }
+    }
     log.step(`Starting ephemeral ${image}…`);
     const tuning = sandboxTuning(await dockerMemoryBudget());
     const { stdout } = await execFileAsync("docker", [
         "run",
         "-d",
         "--rm",
+        ...(resourceName ? ["--name", resourceName, "--mount",
+            `type=volume,source=${resourceName},target=${dataVolumeTarget}`] : []),
         "-e",
         "POSTGRES_PASSWORD=drill",
         "-e",
@@ -115,7 +153,7 @@ async function startEphemeralPostgres(image) {
     const containerId = stdout.trim();
     // postgres 镜像把数据目录声明成 VOLUME → 每次 run 都建一个匿名卷。生产实测 `--rm` **没有**把它
     // 带走(一次演练遗留 37.6 GB,三次失败把 59 GB 根盘灌满),所以记下卷名,销毁容器后显式删。
-    const volumeName = await execFileAsync("docker", [
+    const volumeName = resourceName ?? await execFileAsync("docker", [
         "inspect",
         "-f",
         '{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}',
@@ -388,14 +426,32 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
 export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], opts = {}) {
     // 空/纯空白命令 = 危险的假配置(CI 里变量没展开的典型形态):跑了会以 exit 0
     // 假通过,忽略会让用户以为检查在跑。拒绝,且要在起沙箱之前拒绝。
+    validateSupervision(opts.supervision, opts.appCheckCommand, opts.keepSandboxOnFailure);
     const appCheckCommand = opts.appCheckCommand?.trim();
     if (opts.appCheckCommand !== undefined && !appCheckCommand) {
         throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to report a check that would never run");
     }
     const checks = [...preChecks];
-    const pg = await startEphemeralPostgres(sandboxImage(manifest));
+    await opts.supervision?.observe({ phase: "sandbox" });
+    const sourceMajor = parseInt(manifest.database.serverVersion, 10);
+    const toolMajor = await localPgRestoreMajor();
+    const sandboxMajor = sandboxMajorFor(sourceMajor, toolMajor);
+    const pg = await startEphemeralPostgres(sandboxImage(manifest, sandboxMajor), sandboxMajor, opts.supervision?.resourceName);
     let pass = false; // 异常路径视为失败,供 finally 决定 --keep 是否保留沙箱
     try {
+        if (sandboxMajor !== sourceMajor) {
+            // 报告里写明沙箱比源库新以及原因:读报告的人要知道这次证明的是
+            // "能恢复进 PostgreSQL N",而不是同版本
+            checks.push({
+                name: "sandbox version",
+                pass: true,
+                detail: `restored into PostgreSQL ${sandboxMajor} (source is ${sourceMajor}): ` +
+                    (toolMajor !== null && restoreToolBreaksOnTarget(toolMajor, sourceMajor)
+                        ? `pg_restore ${toolMajor} sends SET transaction_timeout, which PostgreSQL ${sourceMajor} rejects`
+                        : `output of pg_restore ${toolMajor} is only guaranteed to load into PostgreSQL ${toolMajor} or newer`) +
+                    `; restoring into a newer major version is supported`,
+            });
+        }
         // 旧 manifest(≤0.1.1)没有 extensions 字段 → 不装任何扩展,行为与从前一致
         const extensions = manifest.database.extensions ?? [];
         const unavailable = await installExtensions(pg.connString, extensions);
@@ -417,6 +473,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
                     : `installed ${extensions.map((e) => e.name).join(", ")}`,
             });
         }
+        await opts.supervision?.observe({ phase: "restore" });
         const started = Date.now();
         log.step("Restoring into ephemeral Postgres…");
         let postData;
@@ -446,6 +503,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
                     ? `user objects restored; ${postData.supabaseSkipped} Supabase-managed object(s) skipped (Supabase-managed tables such as auth.users do not exist in the drill sandbox)`
                     : "all post-data objects restored",
         });
+        await opts.supervision?.observe({ phase: "verify" });
         const verify = await verifyRestored(pg.connString, manifest);
         checks.push(...verify.checks);
         // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
@@ -485,6 +543,7 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
                 `(remove with: docker rm -f ${pg.containerId.slice(0, 12)})`);
         }
         else {
+            await observeCleanup(opts.supervision);
             log.step("Tearing down ephemeral Postgres…");
             await execFileAsync("docker", ["rm", "-f", pg.containerId]).catch(() => { });
             // 显式删匿名卷(--rm 不可靠,见 startEphemeralPostgres);幂等,已被 --rm 带走也不报错
@@ -495,14 +554,16 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
 }
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
 export async function runDrill(config, opts = {}) {
+    validateSupervision(opts.supervision, opts.appCheckCommand, opts.keepSandboxOnFailure);
     const s3 = targetClient(config);
     const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
     const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
     log.step(`Drilling snapshot ${snapshot}`);
     const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
-    const workdir = await mkdtemp(join(tmpdir(), "backupdrill-"));
+    const workdir = opts.supervision?.workdir ?? await mkdtemp(join(tmpdir(), "backupdrill-"));
     const dumpPath = join(workdir, "dump.pgcustom");
     try {
+        await opts.supervision?.observe({ phase: "download", dumpBytes: manifest.dump.bytes });
         log.step("Downloading dump…");
         const { sha256: sha } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
         const integrityPass = sha === manifest.dump.sha256;
@@ -528,15 +589,18 @@ export async function runDrill(config, opts = {}) {
         }
         // Storage 文件完整性(备份含 Storage 时才校验)
         if (manifest.storage && manifest.storage.files.length) {
+            await opts.supervision?.observe({ phase: "storage" });
             log.step("Verifying Storage files…");
             preChecks.push(await verifyStorage(s3, config, manifest, opts.verifyAllFiles ?? false));
         }
         return await drillDump(dumpPath, manifest, snapshot, preChecks, {
             appCheckCommand: opts.appCheckCommand,
             keepSandboxOnFailure: opts.keepSandboxOnFailure,
+            supervision: opts.supervision,
         });
     }
     finally {
-        await rm(workdir, { recursive: true, force: true }).catch(() => { });
+        if (!opts.supervision)
+            await rm(workdir, { recursive: true, force: true }).catch(() => { });
     }
 }

package/dist/lib.d.ts

@@ -9,6 +9,6 @@ export { loadConfig } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
 export type { BackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
 export type { BucketAttrs, ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
-export type { DrillReport, DrillCheck } from "./drill.js";
+export type { DrillReport, DrillCheck, DrillSupervision, DrillPhase } from "./drill.js";
 export type { RestoreResult } from "./restore.js";
 export type { EgressPricing, EgressProjection } from "./estimate.js";

package/dist/pgbin.d.ts

@@ -5,3 +5,36 @@
  * 绝不能把 pg_dump 当恢复器执行。
  */
 export declare function resolvePgRestoreBin(): string;
+/**
+ * Parse the major version out of `pg_dump --version` output.
+ *
+ * MUST tolerate a trailing vendor suffix: Homebrew/macOS prints `pg_dump (PostgreSQL) 17.2`, but
+ * Debian/PGDG (what the deployed worker image uses) prints
+ * `pg_dump (PostgreSQL) 17.10 (Debian 17.10-1.pgdg120+1)`. Anchoring the match to end-of-string
+ * therefore breaks in production while passing on a dev Mac. Anchor on the `(PostgreSQL)` marker
+ * instead, falling back to the first dotted version token for non-standard builds.
+ */
+export declare function parsePgDumpMajor(raw: string): number | null;
+/** 本地 pg_restore 主版本(拿不到 → null,由调用方决定 fail-open 还是 fail-closed)。 */
+export declare function localPgRestoreMajor(): Promise<number | null>;
+/**
+ * pg_restore 17 起每次恢复都先发 `SET transaction_timeout = 0`,这个参数 PostgreSQL 17
+ * 才有,恢复进 16 及更老的服务端第一句就报 unrecognized configuration parameter。
+ * 上游定性为设计如此(pgsql-bugs 2024-10),不会修,只能绕开。
+ */
+export declare function restoreToolBreaksOnTarget(toolMajor: number, targetMajor: number): boolean;
+/**
+ * 恢复前的工具/目标版本闸:返回拒绝理由,可放行时返回 null。dry-run 与正式恢复共用,
+ * 保证两条路径的判定和给用户的出路一字不差。出路有两条:目标升到 17+;或当归档
+ * 本身只需要 ≤16 的 pg_restore(旧版 pg_dump 写的)时,换一个与目标同版本的旧客户端。
+ */
+export declare function restoreToolTargetBlocker(toolMajor: number, targetMajor: number, requiredMajor: number): string | null;
+/**
+ * 演练沙箱的主版本:源库与本机 pg_restore 取大者。pg_dump/pg_restore 的输出只保证能进
+ * 与工具同版本或更新的服务端(官方文档原话:不保证能载入更老的主版本)——除了
+ * restoreToolBreaksOnTarget 这条已知的,还有新版 pg_dump 生成旧服务端不认识的语法
+ * (交叉审查实测:pg_dump 18 导 PG17 的继承表)。往更新的主版本恢复是官方支持的方向,
+ * 反过来要求用户装与源库同版本的旧工具行不通(旧 pg_restore 读不了新 pg_dump 的归档)。
+ * 拿不到工具版本时退回源版本。
+ */
+export declare function sandboxMajorFor(sourceMajor: number, toolMajor: number | null): number;

package/dist/pgbin.js

@@ -1,3 +1,6 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
 /**
  * pg_restore 二进制解析:显式 BACKUPDRILL_PG_RESTORE 最高优先;否则从
  * BACKUPDRILL_PG_DUMP 同目录推导。推导未命中(结果仍含 pg_dump 或与原值相同,
@@ -15,3 +18,60 @@ export function resolvePgRestoreBin() {
     }
     return "pg_restore";
 }
+/**
+ * Parse the major version out of `pg_dump --version` output.
+ *
+ * MUST tolerate a trailing vendor suffix: Homebrew/macOS prints `pg_dump (PostgreSQL) 17.2`, but
+ * Debian/PGDG (what the deployed worker image uses) prints
+ * `pg_dump (PostgreSQL) 17.10 (Debian 17.10-1.pgdg120+1)`. Anchoring the match to end-of-string
+ * therefore breaks in production while passing on a dev Mac. Anchor on the `(PostgreSQL)` marker
+ * instead, falling back to the first dotted version token for non-standard builds.
+ */
+export function parsePgDumpMajor(raw) {
+    const match = raw.match(/\(PostgreSQL\)\s+(\d+)/) ?? raw.match(/(\d+)(?:\.\d+)+/);
+    return match ? Number(match[1]) : null;
+}
+/** 本地 pg_restore 主版本(拿不到 → null,由调用方决定 fail-open 还是 fail-closed)。 */
+export async function localPgRestoreMajor() {
+    try {
+        const { stdout } = await execFileAsync(resolvePgRestoreBin(), ["--version"]);
+        return parsePgDumpMajor(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * pg_restore 17 起每次恢复都先发 `SET transaction_timeout = 0`,这个参数 PostgreSQL 17
+ * 才有,恢复进 16 及更老的服务端第一句就报 unrecognized configuration parameter。
+ * 上游定性为设计如此(pgsql-bugs 2024-10),不会修,只能绕开。
+ */
+export function restoreToolBreaksOnTarget(toolMajor, targetMajor) {
+    return toolMajor >= 17 && targetMajor < 17;
+}
+/**
+ * 恢复前的工具/目标版本闸:返回拒绝理由,可放行时返回 null。dry-run 与正式恢复共用,
+ * 保证两条路径的判定和给用户的出路一字不差。出路有两条:目标升到 17+;或当归档
+ * 本身只需要 ≤16 的 pg_restore(旧版 pg_dump 写的)时,换一个与目标同版本的旧客户端。
+ */
+export function restoreToolTargetBlocker(toolMajor, targetMajor, requiredMajor) {
+    if (!restoreToolBreaksOnTarget(toolMajor, targetMajor))
+        return null;
+    const olderClient = requiredMajor <= targetMajor
+        ? ` or point BACKUPDRILL_PG_RESTORE at a pg_restore ${targetMajor} (this archive only needs v${requiredMajor})`
+        : "";
+    return (`local pg_restore is v${toolMajor}, which sends SET transaction_timeout — a setting PostgreSQL ` +
+        `${targetMajor} does not have, so the restore would fail on its first statement. ` +
+        `Create the target on PostgreSQL 17 or newer${olderClient}.`);
+}
+/**
+ * 演练沙箱的主版本:源库与本机 pg_restore 取大者。pg_dump/pg_restore 的输出只保证能进
+ * 与工具同版本或更新的服务端(官方文档原话:不保证能载入更老的主版本)——除了
+ * restoreToolBreaksOnTarget 这条已知的,还有新版 pg_dump 生成旧服务端不认识的语法
+ * (交叉审查实测:pg_dump 18 导 PG17 的继承表)。往更新的主版本恢复是官方支持的方向,
+ * 反过来要求用户装与源库同版本的旧工具行不通(旧 pg_restore 读不了新 pg_dump 的归档)。
+ * 拿不到工具版本时退回源版本。
+ */
+export function sandboxMajorFor(sourceMajor, toolMajor) {
+    return toolMajor === null ? sourceMajor : Math.max(sourceMajor, toolMajor);
+}

package/dist/restore.js

@@ -10,22 +10,9 @@ import { restoreDatabaseArtifact, installExtensions, projectRefOf, refFromStorag
 import { verifyRestored } from "./drill.js";
 import { restoreStorage, planStorageRestore, } from "./storage-restore.js";
 import { connectPg } from "./supabase-ca.js";
-import { resolvePgRestoreBin } from "./pgbin.js";
+import { localPgRestoreMajor, restoreToolTargetBlocker } from "./pgbin.js";
 import { parsePgDumpMajor } from "./backup.js";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { log } from "./log.js";
-const execFileAsync = promisify(execFile);
-/** 本地 pg_restore 主版本(拿不到 → null,由引擎自己的报错兜底)。 */
-async function localPgRestoreMajor() {
-    try {
-        const { stdout } = await execFileAsync(resolvePgRestoreBin(), ["--version"]);
-        return parsePgDumpMajor(stdout.trim());
-    }
-    catch {
-        return null;
-    }
-}
 /** 归档可读性要求:pg_restore 必须 ≥ max(写入工具版本, 源服务端版本)——格式跟随写入工具。 */
 export function requiredRestoreToolMajor(manifest) {
     return Math.max(parsePgDumpMajor(manifest.database.pgDumpVersion) ?? 0, parseInt(manifest.database.serverVersion, 10) || 0);
@@ -272,6 +259,13 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
             else {
                 log.ok(`pg_restore tool: local v${toolMajor} ≥ archive requirement v${requiredMajor}`);
             }
+            const toolTargetBlocker = toolMajor !== null && Number.isFinite(targetMajor)
+                ? restoreToolTargetBlocker(toolMajor, targetMajor, requiredMajor)
+                : null;
+            if (toolTargetBlocker) {
+                blockers.push(`local pg_restore v${toolMajor} cannot restore into PostgreSQL ${targetMajor}`);
+                log.error(`pg_restore tool: ${toolTargetBlocker}`);
+            }
             const extensions = db.extensions ?? [];
             if (extensions.length) {
                 const available = await client.query(`select name from pg_available_extensions where name = any($1::text[])`, [extensions.map((e) => e.name)]);
@@ -447,6 +441,11 @@ export async function runRestore(config, opts) {
                     `(archive format follows the writing tool). Install postgresql client ${requiredMajor}+ ` +
                     `and/or point BACKUPDRILL_PG_RESTORE at it.`);
             }
+            // 工具/目标版本闸:pg_restore 17+ 恢复进 ≤16 的目标第一句就失败。在下载与装扩展
+            // 之前拦下,别等恢复到一半才炸;旧 pg_restore 又读不了新归档,所以唯一出路是新目标
+            const toolTargetBlocker = restoreToolTargetBlocker(toolMajor, targetMajor, requiredMajor);
+            if (toolTargetBlocker)
+                throw new Error(toolTargetBlocker);
             log.step("Downloading dump…");
             const dumpPath = join(workdir, "dump.pgcustom");
             const { sha256 } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "2.1.8",
+  "version": "2.2.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": {