backupdrill 2.2.5 → 2.4.0

package/README.md

@@ -161,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/backup.d.ts

@@ -1,5 +1,9 @@
 import type { BackupConfig } from "./config.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 import type { Manifest } from "./manifest.js";
 import { parsePgDumpMajor } from "./pgbin.js";
 export { parsePgDumpMajor };
-export declare function runBackup(config: BackupConfig): Promise<Manifest>;
+export declare function runBackup(config: BackupConfig, opts?: {
+    /** 快照写到哪;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
+}): Promise<Manifest>;

package/dist/backup.js

@@ -2,18 +2,15 @@ import { spawn, execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { Transform } from "node:stream";
 import { promisify } from "node:util";
-import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
-import { Upload } from "@aws-sdk/lib-storage";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 import { syncStorage } from "./storage.js";
 import { inspectBucketAttrs } from "./storage-catalog.js";
-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";
 import { relationBytes } from "./estimate.js";
-import { dumpPartSizeFor } from "./part-size.js";
 // 解析函数搬到了 pgbin(演练与恢复都要读 pg_restore 版本,放这里会成环);保留旧出口
 export { parsePgDumpMajor };
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
@@ -93,8 +90,8 @@ async function inspectDatabase(databaseUrl, schemas) {
         await client.end();
     }
 }
-/** 流式跑 pg_dump,边写 S3 边算 sha256 与字节数。返回校验和与大小。 */
-async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
+/** 流式跑 pg_dump,边写快照边算 sha256 与字节数。返回校验和与大小。 */
+async function dumpToSnapshot(config, writer, pgDumpBin, dumpRelationBytes) {
     const hash = createHash("sha256");
     let bytes = 0;
     const meter = new Transform({
@@ -136,33 +133,26 @@ async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
             ? resolve()
             : reject(new Error(`pg_dump exited with code ${code}: ${stderr.trim()}`)));
     });
-    const upload = new Upload({
-        client: s3,
-        partSize,
-        params: {
-            Bucket: config.storage.bucket,
-            Key: key,
-            Body: meter,
-            ContentType: "application/octet-stream",
-        },
-    });
-    const uploadDone = upload.done();
     // 失败双向联动:dump 失败要中止上传(绝不把半截转储当成功);上传失败也必须
     // 杀掉 pg_dump —— 否则上传侧停止消费后,背压会让 pg_dump 永远阻塞在 stdout
     // 写入上,调用方(worker 的串行队列)随之永久挂起。Promise.all 会订阅两侧,
     // 先失败的一方抛出后,另一方稍后的 rejection 也已被视为 handled。
+    // 开始上传也放进 try:实现可能在建上传时就同步抛错,那时 pg_dump 已经在跑,同样要杀掉。
+    let upload = null;
     try {
-        await Promise.all([dumpDone, uploadDone]);
+        upload = writer.uploadDump(meter, dumpRelationBytes);
+        await Promise.all([dumpDone, upload.done]);
     }
     catch (error) {
+        dumpDone.catch(() => { }); // 没走到 Promise.all 时,被杀的 pg_dump 的退出也得有人接住
         dump.kill("SIGKILL");
         meter.destroy();
-        await upload.abort().catch(() => { });
+        await upload?.abort().catch(() => { });
         throw error;
     }
     return { bytes, sha256: hash.digest("hex") };
 }
-export async function runBackup(config) {
+export async function runBackup(config, opts = {}) {
     // 源身份先于一切传输(评审第 12 轮):①连接串不许带 ?host=/user= 覆盖——否则
     // 快照记的 ref 与实际读取对象脱节,恢复端的同源保护随之失真;②库与 Storage
     // 跨项目 = 配置错误,全量 dump+同步之后才发现会白烧 egress 还留下半截快照前缀
@@ -190,29 +180,26 @@ export async function runBackup(config) {
             `pg_dump must be >= the server major version. Install postgresql-client-${serverMajor} ` +
             `(or newer) and/or point BACKUPDRILL_PG_DUMP at it.`);
     }
-    const s3 = new S3Client({
-        region: config.storage.region,
-        endpoint: config.storage.endpoint,
-        forcePathStyle: config.storage.forcePathStyle,
-        credentials: {
-            accessKeyId: config.storage.accessKeyId,
-            secretAccessKey: config.storage.secretAccessKey,
-        },
-    });
+    const store = opts.store ?? s3SnapshotStore(config);
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const base = `${config.storage.prefix}/${config.projectName}/${timestamp}`;
-    const dumpKey = `${base}/dump.pgcustom`;
-    log.step(`Dumping → s3://${config.storage.bucket}/${dumpKey}`);
-    const { bytes, sha256 } = await dumpToS3(config, s3, dumpKey, pgDumpBin, dumpPartSizeFor(db.relationBytes));
+    const writer = await store.createSnapshot(timestamp);
+    const storageFiles = writer.storageFiles;
+    // 在转储之前拦下:目标放不了 Storage 文件却配了 Storage,转储完才发现等于白跑一遍
+    if (config.supabaseStorage && !storageFiles) {
+        throw new Error("Storage file backup needs an S3-compatible bucket; this backup destination only holds the database.");
+    }
+    const dumpKey = writer.dumpKey;
+    log.step(`Dumping → ${writer.describe("dump.pgcustom")}`);
+    const { bytes, sha256 } = await dumpToSnapshot(config, writer, pgDumpBin, db.relationBytes);
     log.ok(`Database dumped (${(bytes / 1024 / 1024).toFixed(1)} MB, sha256 ${sha256.slice(0, 12)}…)`);
     // Storage 文件同步(源配置存在才做;否则只备数据库)
     let storageResult = null;
-    if (config.supabaseStorage) {
+    if (config.supabaseStorage && storageFiles) {
         log.step("Syncing Storage files…");
         const synced = await syncStorage(config.supabaseStorage, {
-            client: s3,
-            bucket: config.storage.bucket,
-            base, // syncStorage 内部会加 /storage/<bucket>/<key>
+            client: storageFiles.s3,
+            bucket: storageFiles.bucket,
+            base: storageFiles.base, // syncStorage 内部会加 /storage/<bucket>/<key>
         });
         // v2 bucket 属性采集,通道 = 已有的只读库连接(per-file 元数据已随 GetObject
         // 响应在 syncStorage 内原子捕获)。失败只降级不报错:storage schema 读不到
@@ -257,26 +244,9 @@ export async function runBackup(config) {
     // RECOVERY.md(PRD §5.9.2.1)先于 manifest 落桶:manifest 是快照的"完成标记"
     // (演练/恢复按它找快照)——先写手册再写标记,"快照完成"就蕴含"手册在场";
     // 手册写失败 = 备份失败(同桶同权限,与 manifest 自身的写入风险一致)。
-    await s3.send(new PutObjectCommand({
-        Bucket: config.storage.bucket,
-        Key: `${base}/RECOVERY.md`,
-        Body: renderRecoveryDoc(manifest, {
-            snapshot: timestamp,
-            bucket: config.storage.bucket,
-            endpoint: config.storage.endpoint,
-            region: config.storage.region,
-            prefix: config.storage.prefix,
-            projectName: config.projectName,
-        }),
-        ContentType: "text/markdown",
-    }));
-    log.ok(`Recovery runbook written → s3://${config.storage.bucket}/${base}/RECOVERY.md`);
-    await s3.send(new PutObjectCommand({
-        Bucket: config.storage.bucket,
-        Key: `${base}/manifest.json`,
-        Body: JSON.stringify(manifest, null, 2),
-        ContentType: "application/json",
-    }));
-    log.ok(`Manifest written → s3://${config.storage.bucket}/${base}/manifest.json`);
+    await writer.writeRecoveryDoc(manifest);
+    log.ok(`Recovery runbook written → ${writer.describe("RECOVERY.md")}`);
+    await writer.writeManifest(manifest);
+    log.ok(`Manifest written → ${writer.describe("manifest.json")}`);
     return manifest;
 }

package/dist/config.d.ts

@@ -26,9 +26,15 @@ export interface BackupConfig {
     databaseUrl: string;
     projectName: string;
     schemas: string[];
-    storage: StorageConfig;
+    storage?: StorageConfig;
     supabaseStorage?: SupabaseStorageConfig;
 }
+/** CLI 读出来的配置一定带桶:loadConfig 缺了桶直接报错,所以返回类型里 storage 是必填 */
+export type LoadedBackupConfig = BackupConfig & {
+    storage: StorageConfig;
+};
+/** 需要桶的地方先过这一道:没配桶时给一句能看懂的报错,而不是读 undefined 的属性。 */
+export declare function requireBucket(config: BackupConfig): StorageConfig;
 interface RawConfig {
     databaseUrl?: string;
     projectName?: string;
@@ -40,5 +46,5 @@ interface RawConfig {
 export declare function loadConfig(opts: {
     configPath: string;
     overrides: RawConfig;
-}): Promise<BackupConfig>;
+}): Promise<LoadedBackupConfig>;
 export {};

package/dist/config.js

@@ -1,4 +1,11 @@
 import { readFile } from "node:fs/promises";
+/** 需要桶的地方先过这一道:没配桶时给一句能看懂的报错,而不是读 undefined 的属性。 */
+export function requireBucket(config) {
+    if (!config.storage) {
+        throw new Error("No S3-compatible bucket configured (storage) — set storage.bucket and its keys.");
+    }
+    return config.storage;
+}
 function fromEnv() {
     const env = process.env;
     const storage = {};

package/dist/drill.d.ts

@@ -1,5 +1,6 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 /**
  * 无放回随机抽样:部分 Fisher-Yates,只洗出前 n 位(O(n) 次交换,不必全 shuffle)。
  * 此前恒取 manifest 顺序的前 CAP 个 → 超过 CAP 的项目里排序靠后的文件永远不被校验;
@@ -44,8 +45,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 {
@@ -90,5 +93,7 @@ export declare function runDrill(config: BackupConfig, opts?: {
     appCheckCommand?: string;
     keepSandboxOnFailure?: boolean;
     supervision?: DrillSupervision;
+    /** 快照从哪读;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
 }): Promise<DrillReport>;
 export {};

package/dist/drill.js

@@ -4,7 +4,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { parseManifest } from "./manifest.js";
-import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+import { hashObject } from "./snapshots.js";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, installSandboxShim, } from "./restore-engine.js";
 import { connectPg } from "./supabase-ca.js";
 import { localPgRestoreMajor, restoreToolBreaksOnTarget, sandboxMajorFor } from "./pgbin.js";
@@ -60,23 +61,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 +100,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 +142,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 +198,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 +233,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(" | ")}`);
     }
@@ -319,16 +330,15 @@ export async function verifyRestored(connString, manifest) {
  * Storage 完整性校验:从备份桶重新读回文件、比对 manifest 里记录的 sha256,
  * 证明备份的文件副本真实存在且未损坏。文件多时抽样(默认上限),避免大量 egress。
  */
-async function verifyStorage(s3, config, manifest, verifyAll) {
+async function verifyStorage(location, manifest, verifyAll) {
     const files = manifest.storage.files;
     const sample = verifyAll ? files : sampleStorageFiles(files, STORAGE_SAMPLE_CAP);
-    // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>,base 从 dump.key 反推
-    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>
     const mismatches = [];
     for (const f of sample) {
-        const objectKey = `${base}/storage/${f.bucket}/${f.key}`;
+        const objectKey = `${location.base}/storage/${f.bucket}/${f.key}`;
         try {
-            const { sha256 } = await hashObject(s3, config.storage.bucket, objectKey);
+            const { sha256 } = await hashObject(location.s3, location.bucket, objectKey);
             if (sha256 !== f.sha256)
                 mismatches.push(`${f.bucket}/${f.key}`);
         }
@@ -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({
@@ -555,17 +569,17 @@ 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();
+    const store = opts.store ?? s3SnapshotStore(config);
+    const reader = await store.openSnapshot(opts.snapshot);
+    const snapshot = reader.name;
     log.step(`Drilling snapshot ${snapshot}`);
-    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
+    const manifest = parseManifest(await reader.readManifest());
     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 { sha256: sha } = await reader.downloadDump(manifest, dumpPath);
         const integrityPass = sha === manifest.dump.sha256;
         const preChecks = [
             {
@@ -591,7 +605,14 @@ export async function runDrill(config, opts = {}) {
         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));
+            const location = reader.storageFiles(manifest);
+            preChecks.push(location
+                ? await verifyStorage(location, manifest, opts.verifyAllFiles ?? false)
+                : {
+                    name: "storage file integrity",
+                    pass: false,
+                    detail: "the manifest lists Storage files, but this snapshot location cannot hold them",
+                });
         }
         return await drillDump(dumpPath, manifest, snapshot, preChecks, {
             appCheckCommand: opts.appCheckCommand,

package/dist/lib.d.ts

@@ -5,9 +5,11 @@ export { runRestore } from "./restore.js";
 export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
-export { loadConfig } from "./config.js";
+export { loadConfig, requireBucket } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
-export type { BackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
+export { s3SnapshotStore } from "./snapshot-store.js";
+export type { SnapshotStore, SnapshotWriter, SnapshotReader, DumpUpload, StorageFilesLocation, } from "./snapshot-store.js";
+export type { BackupConfig, LoadedBackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
 export type { BucketAttrs, ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
 export type { DrillReport, DrillCheck, DrillSupervision, DrillPhase } from "./drill.js";
 export type { RestoreResult } from "./restore.js";

package/dist/lib.js

@@ -10,5 +10,7 @@ export { runRestore } from "./restore.js";
 export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
-export { loadConfig } from "./config.js";
+export { loadConfig, requireBucket } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+// 快照位置接口:备份、演练、恢复都可以传入自己的实现(托管 worker 的 Google Drive 目标)
+export { s3SnapshotStore } from "./snapshot-store.js";

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

@@ -1,5 +1,6 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 import { type DrillCheck } from "./drill.js";
 import { type StorageRestoreSummary } from "./storage-restore.js";
 /** 归档可读性要求:pg_restore 必须 ≥ max(写入工具版本, 源服务端版本)——格式跟随写入工具。 */
@@ -88,4 +89,6 @@ export declare function runRestore(config: BackupConfig, opts: {
     skipStorage?: boolean;
     snapshot?: string;
     storageDir?: string;
+    /** 快照从哪读;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
 }): Promise<RestoreResult>;

package/dist/restore.js

@@ -5,7 +5,7 @@ import { join, dirname, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { parseManifest } from "./manifest.js";
-import { targetClient, resolveSnapshot, getObjectText, downloadToFile, } from "./snapshots.js";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { restoreDatabaseArtifact, installExtensions, projectRefOf, refFromStorageEndpoint, assertNoHostOverride, normalizeHost, } from "./restore-engine.js";
 import { verifyRestored } from "./drill.js";
 import { restoreStorage, planStorageRestore, } from "./storage-restore.js";
@@ -335,11 +335,10 @@ export async function runRestore(config, opts) {
         assertNoHostOverride(config.databaseUrl);
     if (opts.targetDatabaseUrl)
         assertNoHostOverride(opts.targetDatabaseUrl);
-    const s3 = targetClient(config);
-    const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
-    const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
-    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
-    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    const store = opts.store ?? s3SnapshotStore(config);
+    const reader = await store.openSnapshot(opts.snapshot);
+    const snapshot = reader.name;
+    const manifest = parseManifest(await reader.readManifest());
     // Storage 目标构造即校验(https + 恰为 <ref>.supabase.co):service key 只发往
     // 已验证的 Supabase 项目源;目标库连接串拒绝 host 覆盖(身份判定=实际写入目标)
     // 两个字段必须成对:只给其一时静默退回"本地下载"会让库级调用方把受保护文件
@@ -389,6 +388,11 @@ export async function runRestore(config, opts) {
     // 这次运行会不会碰 Storage(回传到目标,或下载到本地)。只有会碰时,空目标门才该
     // 提示"库已恢复、只重试 Storage";skipStorage 的纯数据库运行(托管恢复)不该看到这句。
     const alsoRestoringStorage = !!manifest.storage && !opts.skipStorage;
+    const storageSource = manifest.storage ? reader.storageFiles(manifest) : null;
+    if (alsoRestoringStorage && !storageSource) {
+        throw new Error("the manifest lists Storage files, but this snapshot location cannot hold them — " +
+            "restore the database only (skip Storage).");
+    }
     // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
     if (opts.dryRun) {
         log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
@@ -461,7 +465,7 @@ export async function runRestore(config, opts) {
                 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);
+            const { sha256 } = await reader.downloadDump(manifest, dumpPath);
             // 归档完整性是恢复的前提:哈希不符还继续,只会把"备份坏了"变成一堆误导性
             // 恢复错误(演练侧同一裁决:integrity FAIL 即短路)
             if (sha256 !== manifest.dump.sha256) {
@@ -505,7 +509,7 @@ export async function runRestore(config, opts) {
             // DB-only 阶段(hosted 检查点重试):既不回传也不本地下载,Storage 单独一段跑
         }
         else if (manifest.storage && storageTarget) {
-            const summary = await restoreStorage({ s3, bucket: config.storage.bucket, base }, storageTarget, manifest);
+            const summary = await restoreStorage(storageSource, storageTarget, manifest);
             result.storageSummary = summary;
             result.storageFilesWritten = summary.filesUploaded;
             log.ok(`Storage restored: ${summary.filesUploaded}/${manifest.storage.files.length} files uploaded` +
@@ -568,9 +572,9 @@ export async function runRestore(config, opts) {
                     throw new Error(`unsafe storage path escapes output directory: ${f.bucket}/${f.key}`);
                 }
                 await mkdir(dirname(dest), { recursive: true });
-                const res = await s3.send(new GetObjectCommand({
-                    Bucket: config.storage.bucket,
-                    Key: `${base}/storage/${f.bucket}/${f.key}`,
+                const res = await storageSource.s3.send(new GetObjectCommand({
+                    Bucket: storageSource.bucket,
+                    Key: `${storageSource.base}/storage/${f.bucket}/${f.key}`,
                 }));
                 await pipeline(res.Body, createWriteStream(dest));
                 result.storageFilesWritten += 1;

package/dist/snapshot-store.d.ts

@@ -0,0 +1,54 @@
+import type { Readable } from "node:stream";
+import { type S3Client } from "@aws-sdk/client-s3";
+import { type BackupConfig } from "./config.js";
+import type { Manifest } from "./manifest.js";
+/**
+ * 快照放在哪里,对引擎来说只是这几个动作:建一份新快照往里写、打开一份已有快照往外读。
+ * 备份、演练、恢复都只经这层读写快照。CLI 只用 S3 兼容桶(s3SnapshotStore);托管服务
+ * 的 worker 可以传入自己的实现(Google Drive 目标,实现不进公开包)。
+ */
+export interface SnapshotStore {
+    /** name = 快照名(备份开始时的 UTC 时间戳) */
+    createSnapshot(name: string): Promise<SnapshotWriter>;
+    /** name 省略 = 最新一份 */
+    openSnapshot(name?: string): Promise<SnapshotReader>;
+}
+/** 快照里 Storage 文件的位置(<base>/storage/<bucket>/<key>)。只有 S3 兼容目标能放 Storage 文件。 */
+export interface StorageFilesLocation {
+    s3: S3Client;
+    bucket: string;
+    base: string;
+}
+export interface DumpUpload {
+    /** 转储全部写完才 resolve;任何失败都 reject */
+    done: Promise<void>;
+    /** 中止写入,尽量不留下半截文件 */
+    abort(): Promise<void>;
+}
+export interface SnapshotWriter {
+    /** 记进 manifest.dump.key 的值 */
+    readonly dumpKey: string;
+    /** 这份快照能不能放 Storage 文件;不能时为 null */
+    readonly storageFiles: StorageFilesLocation | null;
+    /** 日志里显示的位置 */
+    describe(file: string): string;
+    /** relationBytes = 要转储的表的磁盘占用(量不出为 null),实现可据此决定分块 */
+    uploadDump(body: Readable, relationBytes: number | null): DumpUpload;
+    /** RECOVERY.md 写的是"从这个位置怎么恢复",所以由各实现自己渲染 */
+    writeRecoveryDoc(manifest: Manifest): Promise<void>;
+    /** manifest 是快照的"完成标记",调用方保证最后写 */
+    writeManifest(manifest: Manifest): Promise<void>;
+}
+export interface SnapshotReader {
+    readonly name: string;
+    readManifest(): Promise<string>;
+    /** 断点续传下载转储到本地文件,返回实际落盘的字节数与 sha256 */
+    downloadDump(manifest: Manifest, dest: string): Promise<{
+        bytes: number;
+        sha256: string;
+    }>;
+    /** 这份快照的 Storage 文件从哪读;实现不支持 Storage 文件时为 null */
+    storageFiles(manifest: Manifest): StorageFilesLocation | null;
+}
+/** S3 兼容桶(S3 / R2 / B2 / Wasabi)。行为与抽出这层之前逐字一致。 */
+export declare function s3SnapshotStore(config: BackupConfig): SnapshotStore;

package/dist/snapshot-store.js

@@ -0,0 +1,76 @@
+import { PutObjectCommand } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { requireBucket } from "./config.js";
+import { targetClient, resolveSnapshot, getObjectText, downloadToFile } from "./snapshots.js";
+import { renderRecoveryDoc } from "./recovery-doc.js";
+import { dumpPartSizeFor } from "./part-size.js";
+/** 写入时的键都在 <prefix>/<projectName>/<快照名>/ 下;读取时 Storage 文件的 base 从 dump.key 反推。 */
+function storageBaseOf(manifest) {
+    return manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+}
+/** S3 兼容桶(S3 / R2 / B2 / Wasabi)。行为与抽出这层之前逐字一致。 */
+export function s3SnapshotStore(config) {
+    const storage = requireBucket(config);
+    let client = null;
+    // 客户端推迟到第一次真正读写时才建:与抽层之前一致,配置错误先由前面的检查报出来
+    const s3 = () => (client ??= targetClient(config));
+    return {
+        async createSnapshot(name) {
+            const base = `${storage.prefix}/${config.projectName}/${name}`;
+            const location = (file) => `s3://${storage.bucket}/${base}/${file}`;
+            return {
+                dumpKey: `${base}/dump.pgcustom`,
+                storageFiles: { s3: s3(), bucket: storage.bucket, base },
+                describe: location,
+                uploadDump(body, relationBytes) {
+                    const upload = new Upload({
+                        client: s3(),
+                        partSize: dumpPartSizeFor(relationBytes),
+                        params: {
+                            Bucket: storage.bucket,
+                            Key: `${base}/dump.pgcustom`,
+                            Body: body,
+                            ContentType: "application/octet-stream",
+                        },
+                    });
+                    return {
+                        done: upload.done().then(() => { }),
+                        abort: () => upload.abort(),
+                    };
+                },
+                async writeRecoveryDoc(manifest) {
+                    await s3().send(new PutObjectCommand({
+                        Bucket: storage.bucket,
+                        Key: `${base}/RECOVERY.md`,
+                        Body: renderRecoveryDoc(manifest, {
+                            snapshot: name,
+                            bucket: storage.bucket,
+                            endpoint: storage.endpoint,
+                            region: storage.region,
+                            prefix: storage.prefix,
+                            projectName: config.projectName,
+                        }),
+                        ContentType: "text/markdown",
+                    }));
+                },
+                async writeManifest(manifest) {
+                    await s3().send(new PutObjectCommand({
+                        Bucket: storage.bucket,
+                        Key: `${base}/manifest.json`,
+                        Body: JSON.stringify(manifest, null, 2),
+                        ContentType: "application/json",
+                    }));
+                },
+            };
+        },
+        async openSnapshot(name) {
+            const prefix = await resolveSnapshot(s3(), config, name);
+            return {
+                name: prefix.replace(/\/$/, "").split("/").pop(),
+                readManifest: () => getObjectText(s3(), storage.bucket, `${prefix}manifest.json`),
+                downloadDump: (manifest, dest) => downloadToFile(s3(), storage.bucket, manifest.dump.key, dest),
+                storageFiles: (manifest) => ({ s3: s3(), bucket: storage.bucket, base: storageBaseOf(manifest) }),
+            };
+        },
+    };
+}

package/dist/snapshots.d.ts

@@ -1,5 +1,5 @@
 import { S3Client } from "@aws-sdk/client-s3";
-import type { BackupConfig } from "./config.js";
+import { type BackupConfig } from "./config.js";
 /** 读备份桶(用户自己的桶)的 S3 客户端。drill/restore 共用。 */
 export declare function targetClient(config: BackupConfig): S3Client;
 /** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */

package/dist/snapshots.js

@@ -4,28 +4,31 @@ import { pipeline } from "node:stream/promises";
 import { Writable } from "node:stream";
 import { log } from "./log.js";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
+import { requireBucket } from "./config.js";
 /** 读备份桶(用户自己的桶)的 S3 客户端。drill/restore 共用。 */
 export function targetClient(config) {
+    const storage = requireBucket(config);
     return new S3Client({
-        region: config.storage.region,
-        endpoint: config.storage.endpoint,
-        forcePathStyle: config.storage.forcePathStyle,
+        region: storage.region,
+        endpoint: storage.endpoint,
+        forcePathStyle: storage.forcePathStyle,
         credentials: {
-            accessKeyId: config.storage.accessKeyId,
-            secretAccessKey: config.storage.secretAccessKey,
+            accessKeyId: storage.accessKeyId,
+            secretAccessKey: storage.secretAccessKey,
         },
     });
 }
 /** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */
 export async function resolveSnapshot(s3, config, explicit) {
-    const root = `${config.storage.prefix}/${config.projectName}/`;
+    const storage = requireBucket(config);
+    const root = `${storage.prefix}/${config.projectName}/`;
     if (explicit)
         return `${root}${explicit}/`;
     const prefixes = [];
     let token;
     do {
         const res = await s3.send(new ListObjectsV2Command({
-            Bucket: config.storage.bucket,
+            Bucket: storage.bucket,
             Prefix: root,
             Delimiter: "/",
             ContinuationToken: token,
@@ -37,7 +40,7 @@ export async function resolveSnapshot(s3, config, explicit) {
         token = res.IsTruncated ? res.NextContinuationToken : undefined;
     } while (token);
     if (!prefixes.length) {
-        throw new Error(`No snapshots found under s3://${config.storage.bucket}/${root}. Run a backup first.`);
+        throw new Error(`No snapshots found under s3://${storage.bucket}/${root}. Run a backup first.`);
     }
     prefixes.sort();
     return prefixes[prefixes.length - 1];

package/package.json

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