backupdrill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BackupDrill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# backupdrill
+
+Open-source CLI to back up a **Supabase** project to **your own** S3/R2/B2 bucket — the Postgres database now, Storage files next — with a checksummed `manifest.json` so you can prove what was captured.
+
+Backups stream through the CLI on your machine (or your CI) straight to your bucket. **Your data never touches our servers, because there are none — this is just a CLI.**
+
+> Want this on a schedule, with **restore drills that prove your backup actually restores**, plus Storage-file backup and alerts? That's the hosted service → **[backupdrill.com](https://backupdrill.com)**. This CLI is the DIY layer; the cloud adds scheduling, drills, alerting, and reports on top.
+
+## Why
+
+- Supabase's own database restore only brings back `storage.objects` **metadata**, not your actual Storage files.
+- Pro-plan backups keep 7 days and can't be pulled into your own infrastructure; PITR is $100/mo per project.
+- A `pg_dump` you've never restored is a guess.
+
+This CLI gets your database into a bucket **you** control, with a manifest you can check.
+
+## Requirements
+
+- Node.js ≥ 20
+- `pg_dump` whose **major version ≥ your Supabase Postgres version** (Supabase runs PG 15–17). On macOS: `brew install libpq` then add it to `PATH`, or point `BACKUPDRILL_PG_DUMP` at the binary. The CLI checks this and refuses to run a mismatched dump.
+
+## Install
+
+```bash
+npm install -g backupdrill
+# or run without installing:
+npx backupdrill backup
+```
+
+## Usage
+
+Configure via **env vars**, a **config file**, or **flags** (precedence: flags > env > file).
+
+### Env vars
+
+```bash
+export BACKUPDRILL_DATABASE_URL="postgresql://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com: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"
+export BACKUPDRILL_S3_BUCKET="my-backups"
+export BACKUPDRILL_S3_ACCESS_KEY_ID="…"
+export BACKUPDRILL_S3_SECRET_ACCESS_KEY="…"
+
+backupdrill backup
+```
+
+### Config file
+
+Copy `backupdrill.config.example.json` → `backupdrill.config.json` (it's gitignored) and fill it in. Keep secrets in env vars even when using a file.
+
+```bash
+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.
+
+**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:
+
+```sql
+-- replace <generate-a-strong-password> before running
+create role backup_reader with login password '<generate-a-strong-password>';
+grant usage on schema public to backup_reader;
+grant select on all tables in schema public to backup_reader;
+grant select on all sequences in schema public to backup_reader;
+alter default privileges in schema public grant select on tables to backup_reader;
+alter default privileges in schema public grant select on sequences to backup_reader;
+```
+
+## Backing up Storage files too
+
+Supabase's own database restore only brings back `storage.objects` **metadata** — not the files. To capture the actual files, give the CLI read access to your project's Storage via its S3-compatible endpoint:
+
+1. Dashboard → Project → **Storage → Settings → S3 Access Keys** → enable the S3 connection and generate an **Access Key ID + Secret Access Key** (these bypass RLS; keep them server-side).
+2. Copy the **endpoint** and **region** from the same page.
+3. Provide them (env shown; config-file keys are `supabaseStorage.*`):
+
+```bash
+export BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT="https://<ref>.storage.supabase.co/storage/v1/s3"
+export BACKUPDRILL_SUPABASE_STORAGE_REGION="<project-region>"
+export BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID="…"
+export BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY="…"
+# optional: only specific buckets — BACKUPDRILL_SUPABASE_STORAGE_BUCKETS="avatars,uploads"
+```
+
+With those set, `backupdrill backup` also copies every Storage file into your bucket and records each file's checksum in the manifest. Omit them to back up the database only.
+
+## Egress & cost — read this before scheduling daily backups
+
+A backup pulls data **out** of Supabase, which counts as **egress on your Supabase bill**. Verified rates (2026-07-04, [egress docs](https://supabase.com/docs/guides/platform/manage-your-usage/egress) + [pricing](https://supabase.com/pricing)):
+
+- Backup traffic (pg_dump + first-time file downloads) is **uncached egress: $0.09/GB** above your plan's included allowance.
+- Included uncached egress: **Free 5 GB · Pro 250 GB · Team 250 GB** per month.
+- **Spend Cap is ON by default (Pro/Team).** If a backup pushes you past the quota, Supabase **throttles your whole project's egress** for the rest of the month and the backup fails — turn Spend Cap OFF to be billed the overage instead.
+- **Free is a hard cap:** exceed 5 GB and the project is restricted (never billed). A large daily backup can't complete on Free.
+
+Rough cost (Pro, Spend Cap OFF, backups = your only egress):
+
+| DB + Storage | Weekly | Daily |
+|---|---|---|
+| 10 GB | $0/mo (within 250 GB) | ~$4.50/mo |
+| 50 GB | ~$0/mo | **~$112/mo** ⚠ |
+
+Cost scales with **size × frequency**. Run `backupdrill estimate` to project it for *your* project, and prefer weekly (or a smaller scope) once your data is large. The compressed dump is smaller than raw DB size, so real DB egress is below the `estimate` upper bound; Storage egress is exact.
+
+```bash
+backupdrill estimate --plan pro   # measures your DB + Storage, prints the projection + warnings
+```
+
+## What lands in your bucket
+
+```
+<prefix>/<project>/<timestamp>/
+  ├── dump.pgcustom              # pg_dump --format=custom (public schema by default)
+  ├── storage/<bucket>/<key>     # your Storage files (if configured)
+  └── manifest.json              # schemas, tables, row counts, file list, sizes + sha256
+```
+
+## Restoring & drilling
+
+Prove a backup is restorable, without touching anything real — `drill` restores the latest snapshot into a throwaway Postgres (needs Docker) and checks it:
+
+```bash
+backupdrill drill                    # latest snapshot; add --snapshot <timestamp> to pick one
+backupdrill drill --verify-all-files # also checksum every Storage file, not just a sample
+```
+
+When you actually need to recover, `restore` puts the database back into a target you name and pulls the Storage files down to a local folder:
+
+```bash
+backupdrill restore \
+  --target-database-url "postgresql://…/postgres" \
+  --storage-dir ./recovered
+```
+
+Or restore the dump by hand:
+
+```bash
+pg_restore --clean --if-exists --no-owner --dbname "<target-connection-string>" dump.pgcustom
+```
+
+## GitHub Action / scheduled backups
+
+Want this running on a schedule without paying for a server? Run it in GitHub Actions.
+
+1. Copy [`examples/scheduled-backup.yml`](examples/scheduled-backup.yml) into **your own** repo at `.github/workflows/scheduled-backup.yml`. (It lives under `examples/` here so GitHub doesn't try to run it in this repo — it's a template.) It runs daily and can also be triggered by hand from the Actions tab. The workflow installs `postgresql-client-17` from the PGDG apt repo (so `pg_dump`'s major version matches Supabase) and points the CLI at it via `BACKUPDRILL_PG_DUMP`.
+2. Add these repo secrets (Settings → Secrets and variables → Actions):
+   - **Required:** `BACKUPDRILL_DATABASE_URL`, `BACKUPDRILL_S3_BUCKET`, `BACKUPDRILL_S3_ACCESS_KEY_ID`, `BACKUPDRILL_S3_SECRET_ACCESS_KEY`
+   - **Optional (destination):** `BACKUPDRILL_S3_ENDPOINT` (for R2/B2), `BACKUPDRILL_S3_REGION`, `BACKUPDRILL_PROJECT_NAME`
+   - **Optional (Storage files):** set all four of `BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT`, `BACKUPDRILL_SUPABASE_STORAGE_REGION`, `BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID`, `BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY` to also back up Storage files; leave them unset to back up the database only.
+
+Before switching to a **daily** schedule, read the egress-cost section above — every run is egress on your Supabase bill.
+
+## Roadmap
+
+- [x] Database backup → your bucket, with checksummed manifest
+- [x] **Storage file sync** (the files Supabase restores leave behind)
+- [x] `estimate` — project your monthly Supabase egress cost before you schedule
+- [x] `drill` — restore a snapshot into an ephemeral Postgres and prove it comes back
+- [x] Storage-file integrity check inside the drill (checksums, sampled by default)
+- [x] `restore` — recover a snapshot into a target DB + pull Storage files down
+- [x] GitHub Action wrapper
+
+For scheduling, automated restore drills, and alerting, use the hosted service at [backupdrill.com](https://backupdrill.com).
+
+## License
+
+MIT

package/dist/backup.d.ts

@@ -0,0 +1,13 @@
+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;
+export declare function runBackup(config: BackupConfig): Promise<Manifest>;

package/dist/backup.js

@@ -0,0 +1,195 @@
+import { spawn, execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { Transform } from "node:stream";
+import { promisify } from "node:util";
+import { Client } from "pg";
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { syncStorage } from "./storage.js";
+import { log } from "./log.js";
+const execFileAsync = promisify(execFile);
+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"]);
+        const raw = stdout.trim();
+        const major = parsePgDumpMajor(raw);
+        if (major === null)
+            throw new Error(`Unrecognized pg_dump version string: ${raw}`);
+        return { raw, major };
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            throw new Error(`pg_dump not found (looked for "${bin}"). Install the PostgreSQL client ` +
+                `matching your server's major version, or set BACKUPDRILL_PG_DUMP to its path.`);
+        }
+        throw error;
+    }
+}
+async function inspectDatabase(databaseUrl, schemas) {
+    const client = new Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        const version = await client.query("show server_version");
+        const versionNum = await client.query("show server_version_num");
+        // 只统计将被 dump 的 schema,manifest 才与转储内容一致
+        const tables = await client.query(`select schemaname as schema, relname as name, n_live_tup as estimated_rows
+         from pg_stat_user_tables
+        where schemaname = any($1::text[])
+        order by schemaname, relname`, [schemas]);
+        return {
+            serverVersion: version.rows[0].server_version,
+            serverVersionNum: Number(versionNum.rows[0].server_version_num),
+            tables: tables.rows.map((r) => ({
+                schema: r.schema,
+                name: r.name,
+                estimatedRows: Number(r.estimated_rows),
+            })),
+        };
+    }
+    finally {
+        await client.end();
+    }
+}
+/** 流式跑 pg_dump,边写 S3 边算 sha256 与字节数。返回校验和与大小。 */
+async function dumpToS3(config, s3, key, pgDumpBin) {
+    const hash = createHash("sha256");
+    let bytes = 0;
+    const meter = new Transform({
+        transform(chunk, _enc, cb) {
+            hash.update(chunk);
+            bytes += chunk.length;
+            cb(null, chunk);
+        },
+    });
+    const schemaArgs = config.schemas.map((s) => `--schema=${s}`);
+    const dump = spawn(pgDumpBin, [
+        "--format=custom",
+        "--no-owner",
+        "--no-privileges",
+        ...schemaArgs,
+        "--dbname",
+        config.databaseUrl,
+    ], { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    dump.stderr.on("data", (d) => {
+        stderr += d.toString();
+    });
+    dump.stdout.pipe(meter);
+    const dumpDone = new Promise((resolve, reject) => {
+        dump.on("error", reject); // 启动失败(如 ENOENT)
+        dump.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`pg_dump exited with code ${code}: ${stderr.trim()}`)));
+    });
+    const upload = new Upload({
+        client: s3,
+        params: {
+            Bucket: config.storage.bucket,
+            Key: key,
+            Body: meter,
+            ContentType: "application/octet-stream",
+        },
+    });
+    const uploadDone = upload.done();
+    // 正确性以 pg_dump 退出码为准:dump 失败则中止上传,绝不把半截转储当成功
+    try {
+        await dumpDone;
+    }
+    catch (error) {
+        meter.destroy(error);
+        await upload.abort().catch(() => { });
+        throw error;
+    }
+    await uploadDone;
+    return { bytes, sha256: hash.digest("hex") };
+}
+export async function runBackup(config) {
+    const pgDumpBin = process.env.BACKUPDRILL_PG_DUMP || "pg_dump";
+    log.step("Inspecting database…");
+    const db = await inspectDatabase(config.databaseUrl, config.schemas);
+    const serverMajor = majorOf(db.serverVersionNum);
+    log.ok(`Postgres ${db.serverVersion} — schema(s) ${config.schemas.join(", ")}: ` +
+        `${db.tables.length} tables, ` +
+        `~${db.tables.reduce((n, t) => n + t.estimatedRows, 0).toLocaleString()} rows`);
+    // pg_dump 主版本必须 ≥ 服务端,否则转储会失败或不完整(PRD §4.2)
+    const pgd = await pgDumpVersion(pgDumpBin);
+    if (pgd.major < serverMajor) {
+        throw new Error(`pg_dump is v${pgd.major} but the server is v${serverMajor}. ` +
+            `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 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);
+    log.ok(`Database dumped (${(bytes / 1024 / 1024).toFixed(1)} MB, sha256 ${sha256.slice(0, 12)}…)`);
+    // Storage 文件同步(源配置存在才做;否则只备数据库)
+    let storageResult = null;
+    if (config.supabaseStorage) {
+        log.step("Syncing Storage files…");
+        const synced = await syncStorage(config.supabaseStorage, {
+            client: s3,
+            bucket: config.storage.bucket,
+            base, // syncStorage 内部会加 /storage/<bucket>/<key>
+        });
+        storageResult = {
+            fileCount: synced.fileCount,
+            totalBytes: synced.totalBytes,
+            files: synced.files,
+        };
+        log.ok(`Storage synced (${synced.fileCount} files, ` +
+            `${(synced.totalBytes / 1024 / 1024).toFixed(1)} MB)`);
+    }
+    const manifest = {
+        tool: "backupdrill-cli",
+        toolVersion: process.env.npm_package_version || "0.1.0",
+        createdAt: new Date().toISOString(),
+        projectName: config.projectName,
+        database: {
+            serverVersion: db.serverVersion,
+            pgDumpVersion: pgd.raw,
+            schemas: config.schemas,
+            tableCount: db.tables.length,
+            estimatedRowTotal: db.tables.reduce((n, t) => n + t.estimatedRows, 0),
+            tables: db.tables,
+        },
+        dump: { key: dumpKey, format: "custom", bytes, sha256 },
+        storage: storageResult,
+    };
+    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`);
+    return manifest;
+}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 目标对象存储(S3 兼容:AWS S3 / Cloudflare R2 / Backblaze B2 / Supabase Storage 的 S3 端点均可)。
+ * 凭据永远来自用户自己的环境 —— CLI 不托管任何密钥,这是"数据不落我们盘"叙事在开源侧的兑现。
+ */
+export interface StorageConfig {
+    endpoint?: string;
+    region: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    prefix: string;
+    forcePathStyle: boolean;
+}
+/**
+ * 备份"源":Supabase Storage 的 S3 兼容端点。存在则一并同步 Storage 文件;
+ * 缺省则只备数据库。密钥在 Supabase 控制台 Storage → S3 Access Keys 生成。
+ */
+export interface SupabaseStorageConfig {
+    endpoint: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    buckets?: string[];
+}
+export interface BackupConfig {
+    databaseUrl: string;
+    projectName: string;
+    schemas: string[];
+    storage: StorageConfig;
+    supabaseStorage?: SupabaseStorageConfig;
+}
+interface RawConfig {
+    databaseUrl?: string;
+    projectName?: string;
+    schemas?: string[];
+    storage?: Partial<StorageConfig>;
+    supabaseStorage?: Partial<SupabaseStorageConfig>;
+}
+/** 合并优先级:显式 flag > 环境变量 > 配置文件。 */
+export declare function loadConfig(opts: {
+    configPath: string;
+    overrides: RawConfig;
+}): Promise<BackupConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,116 @@
+import { readFile } from "node:fs/promises";
+function fromEnv() {
+    const env = process.env;
+    const storage = {};
+    if (env.BACKUPDRILL_S3_ENDPOINT)
+        storage.endpoint = env.BACKUPDRILL_S3_ENDPOINT;
+    if (env.BACKUPDRILL_S3_REGION)
+        storage.region = env.BACKUPDRILL_S3_REGION;
+    if (env.BACKUPDRILL_S3_BUCKET)
+        storage.bucket = env.BACKUPDRILL_S3_BUCKET;
+    if (env.BACKUPDRILL_S3_ACCESS_KEY_ID)
+        storage.accessKeyId = env.BACKUPDRILL_S3_ACCESS_KEY_ID;
+    if (env.BACKUPDRILL_S3_SECRET_ACCESS_KEY)
+        storage.secretAccessKey = env.BACKUPDRILL_S3_SECRET_ACCESS_KEY;
+    if (env.BACKUPDRILL_S3_PREFIX)
+        storage.prefix = env.BACKUPDRILL_S3_PREFIX;
+    if (env.BACKUPDRILL_S3_FORCE_PATH_STYLE)
+        storage.forcePathStyle = env.BACKUPDRILL_S3_FORCE_PATH_STYLE === "true";
+    const supabaseStorage = {};
+    if (env.BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT)
+        supabaseStorage.endpoint = env.BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT;
+    if (env.BACKUPDRILL_SUPABASE_STORAGE_REGION)
+        supabaseStorage.region = env.BACKUPDRILL_SUPABASE_STORAGE_REGION;
+    if (env.BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID)
+        supabaseStorage.accessKeyId = env.BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID;
+    if (env.BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY)
+        supabaseStorage.secretAccessKey =
+            env.BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY;
+    if (env.BACKUPDRILL_SUPABASE_STORAGE_BUCKETS)
+        supabaseStorage.buckets = env.BACKUPDRILL_SUPABASE_STORAGE_BUCKETS.split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return {
+        databaseUrl: env.BACKUPDRILL_DATABASE_URL || env.DATABASE_URL,
+        projectName: env.BACKUPDRILL_PROJECT_NAME,
+        schemas: env.BACKUPDRILL_SCHEMAS
+            ? env.BACKUPDRILL_SCHEMAS.split(",").map((s) => s.trim()).filter(Boolean)
+            : undefined,
+        storage,
+        supabaseStorage,
+    };
+}
+async function fromFile(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw new Error(`Could not read config file ${path}: ${error.message}`);
+    }
+}
+/** 合并优先级:显式 flag > 环境变量 > 配置文件。 */
+export async function loadConfig(opts) {
+    const file = await fromFile(opts.configPath);
+    const env = fromEnv();
+    const o = opts.overrides;
+    const databaseUrl = o.databaseUrl ?? env.databaseUrl ?? file.databaseUrl;
+    const projectName = o.projectName ?? env.projectName ?? file.projectName ?? "supabase";
+    const schemas = o.schemas ?? env.schemas ?? file.schemas ?? ["public"];
+    const storage = {
+        ...file.storage,
+        ...env.storage,
+        ...o.storage,
+    };
+    const src = {
+        ...file.supabaseStorage,
+        ...env.supabaseStorage,
+        ...o.supabaseStorage,
+    };
+    const missing = [];
+    if (!databaseUrl)
+        missing.push("databaseUrl (BACKUPDRILL_DATABASE_URL)");
+    if (!storage.bucket)
+        missing.push("storage.bucket (BACKUPDRILL_S3_BUCKET)");
+    if (!storage.accessKeyId)
+        missing.push("storage.accessKeyId (BACKUPDRILL_S3_ACCESS_KEY_ID)");
+    if (!storage.secretAccessKey)
+        missing.push("storage.secretAccessKey (BACKUPDRILL_S3_SECRET_ACCESS_KEY)");
+    if (missing.length) {
+        throw new Error(`Missing required config:\n  - ${missing.join("\n  - ")}\nSet them via env vars, a config file (--config), or flags. See README.`);
+    }
+    // Storage 源是可选的;但若给了任何一项,就必须给全,否则静默跳过 Storage 是陷阱
+    const srcFields = [src.endpoint, src.accessKeyId, src.secretAccessKey];
+    const srcGiven = srcFields.filter(Boolean).length;
+    let supabaseStorage;
+    if (srcGiven > 0 && srcGiven < 3) {
+        throw new Error("Incomplete Supabase Storage source config: set endpoint + accessKeyId + " +
+            "secretAccessKey together (or none, to back up the database only).");
+    }
+    if (srcGiven === 3) {
+        supabaseStorage = {
+            endpoint: src.endpoint,
+            region: src.region ?? "auto",
+            accessKeyId: src.accessKeyId,
+            secretAccessKey: src.secretAccessKey,
+            buckets: src.buckets,
+        };
+    }
+    return {
+        databaseUrl: databaseUrl,
+        projectName,
+        schemas: schemas.length ? schemas : ["public"],
+        storage: {
+            endpoint: storage.endpoint,
+            region: storage.region ?? "auto",
+            bucket: storage.bucket,
+            accessKeyId: storage.accessKeyId,
+            secretAccessKey: storage.secretAccessKey,
+            prefix: storage.prefix ?? "backupdrill",
+            // R2/自建默认 path-style 更省心;显式给了就尊重
+            forcePathStyle: storage.forcePathStyle ?? Boolean(storage.endpoint),
+        },
+        supabaseStorage,
+    };
+}

package/dist/drill.d.ts

@@ -0,0 +1,38 @@
+import type { BackupConfig } from "./config.js";
+import type { Manifest } from "./manifest.js";
+export interface DrillCheck {
+    name: string;
+    pass: boolean;
+    detail: string;
+}
+export interface DrillReport {
+    snapshot: string;
+    pass: boolean;
+    checks: DrillCheck[];
+    restoreSeconds: number;
+    restoredTableCount: number;
+    restoredRowTotal: number;
+}
+/** post-data 第二遍恢复的结果:用户对象失败 vs Supabase 托管对象的沙箱预期跳过。 */
+interface PostDataResult {
+    supabaseSkipped: number;
+    failures: string[];
+}
+/** 把 pg_restore 的 stderr 拆成单个错误块并分类(Supabase 托管 vs 用户对象)。 */
+export declare function classifyPostDataErrors(stderr: string): PostDataResult;
+/**
+ * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
+ * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
+ */
+export declare function postDataResult(code: number | null, stderr: string): PostDataResult;
+/**
+ * 演练核心:把一份本地 dump 恢复进临时 Postgres 并对照 manifest 校验,然后销毁容器。
+ * 与 S3 解耦,便于离线测试。`preChecks` 用于把下载阶段的校验(如归档校验和)带进报告。
+ */
+export declare function drillDump(dumpPath: string, manifest: Manifest, snapshot: string, preChecks?: DrillCheck[]): Promise<DrillReport>;
+/** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
+export declare function runDrill(config: BackupConfig, opts?: {
+    snapshot?: string;
+    verifyAllFiles?: boolean;
+}): Promise<DrillReport>;
+export {};