backupdrill 2.3.0 → 2.5.0

package/README.md

@@ -42,6 +42,16 @@ The [`plugin/`](plugin/) folder is a plugin for Claude Code and Cursor. It teach
 
 Details are in [plugin/README.md](plugin/README.md).
 
+## Use it from Pi
+
+This npm package is also a Pi package. Installing it gives Pi the same skill the Claude Code plugin uses:
+
+```sh
+pi install npm:backupdrill
+```
+
+Start a new Pi session and ask it to back up your Supabase project or run a restore drill. The skill runs the CLI through `npx`, so Node.js 20 or newer has to be on your `PATH`. Everything else it needs, and where your keys go, is in [plugin/README.md](plugin/README.md).
+
 ## Usage
 
 Configure via **env vars**, a **config file**, or **flags** (precedence: flags > env > file).
@@ -76,6 +86,7 @@ All recognized variables:
 | `BACKUPDRILL_SUPABASE_STORAGE_*` | Storage-file source (endpoint/region/keys/buckets) — see [Backing up Storage files](#backing-up-storage-files-too) | — |
 | `BACKUPDRILL_PG_DUMP` | Path to the `pg_dump` binary to use | `pg_dump` on `PATH` |
 | `BACKUPDRILL_PG_RESTORE` | Path to `pg_restore` (used by `drill` and `restore`) | next to `BACKUPDRILL_PG_DUMP`, else `pg_restore` on `PATH` |
+| `BACKUPDRILL_PING_URL` | Healthchecks.io ping URL for `backup` and `drill` — see [Alerts with Healthchecks.io](#alerts-with-healthchecksio) | — |
 
 ### Config file
 
@@ -224,10 +235,32 @@ Want this running on a schedule without paying for a server? Run it in GitHub Ac
 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 (alerts):** `BACKUPDRILL_PING_URL` — see [Alerts with Healthchecks.io](#alerts-with-healthchecksio)
    - **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.
 
+## Alerts with Healthchecks.io
+
+A scheduled backup can fail quietly, or not run at all: a cron entry that never fires, a runner that dies, a workflow GitHub disabled. `backup` and `drill` can report every run to a [Healthchecks.io](https://healthchecks.io) check (a self-hosted Healthchecks works the same), and Healthchecks alerts you when a run fails or a success ping doesn't arrive on time.
+
+Create a check whose schedule and grace time match your job, copy its ping URL, then:
+
+```bash
+export BACKUPDRILL_PING_URL="https://hc-ping.com/<uuid>"
+backupdrill backup
+```
+
+`--ping-url <url>` and a `"pingUrl"` key in the config file work too (same precedence as everything else). Each run sends a start ping, then either a success or a failure ping:
+
+- `<url>/start` before it begins, so Healthchecks shows how long the run took and alerts if it runs past the grace time;
+- `<url>` when it succeeds, with a one-line summary in the body (tables, Storage files and the snapshot name; for `drill`, rows restored and restore time);
+- `<url>/fail` when it fails, with the error in the body. For a drill that ran but didn't pass, that's the failed checks. Before it's sent, the CLI filters out the connection strings, passwords, hostnames, IP addresses, project refs and bucket keys it can recognise, plus the parts of Postgres errors that usually quote row values or SQL (`DETAIL`, `CONTEXT`, `Command was`). It's a filter, not a guarantee: a sensitive value it doesn't recognise can still reach Healthchecks. The full error stays in the job's own output.
+
+Both pings of a run carry the same `rid`, so Healthchecks pairs them even if two runs overlap. If you schedule both `backup` and `drill`, give each its own check: on a shared check, the daily backup's success pings would keep it up while a weekly drill that stopped running went unnoticed.
+
+A ping never changes the result of a run. Each request times out after 10 seconds and is retried twice on network errors and 5xx responses; if it still fails, the CLI prints a warning and carries on, with the same exit code it would have had without a ping URL.
+
 ## Roadmap
 
 - [x] Database backup → your bucket, with checksummed manifest

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,19 +26,35 @@ 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;
     schemas?: string[];
     storage?: Partial<StorageConfig>;
     supabaseStorage?: Partial<SupabaseStorageConfig>;
+    pingUrl?: string;
 }
+/**
+ * 监控 ping 网址(Healthchecks.io 那种):flag > 环境变量 > 配置文件,空串算没配
+ * (GitHub Actions 里没设的 secret 展开就是空串)。不放进 loadConfig:配置缺项时
+ * loadConfig 直接抛错,而这恰恰是要报 /fail 的情况,所以网址得先单独读出来。
+ */
+export declare function resolvePingUrl(opts: {
+    flag?: string;
+    configPath: string;
+}): Promise<string | undefined>;
 /** 合并优先级:显式 flag > 环境变量 > 配置文件。 */
 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 = {};
@@ -47,8 +54,29 @@ async function fromFile(path) {
     catch (error) {
         if (error.code === "ENOENT")
             return {};
-        throw new Error(`Could not read config file ${path}: ${error.message}`);
+        // JSON.parse 的报错会引用出错位置附近的原文,里面可能正好是密钥。本机日志里留着它方便排错;
+        // 发给监控(Healthchecks 会把它放进告警邮件)的只用 pingMessage 这句不带原文的
+        throw Object.assign(new Error(`Could not read config file ${path}: ${error.message}`), { pingMessage: `Could not read config file ${path}. The job's log has the details.` });
+    }
+}
+/**
+ * 监控 ping 网址(Healthchecks.io 那种):flag > 环境变量 > 配置文件,空串算没配
+ * (GitHub Actions 里没设的 secret 展开就是空串)。不放进 loadConfig:配置缺项时
+ * loadConfig 直接抛错,而这恰恰是要报 /fail 的情况,所以网址得先单独读出来。
+ */
+export async function resolvePingUrl(opts) {
+    let file = {};
+    try {
+        file = await fromFile(opts.configPath);
+    }
+    catch {
+        // 配置文件读不了时由 loadConfig 报错,这里只是拿不到文件里的网址
     }
+    // 文件内容可能是 null、数组这类非对象的合法 JSON:那是 loadConfig 要报的错,这里只是拿不到网址
+    const filePingUrl = file && typeof file === "object" ? file.pingUrl : undefined;
+    return [opts.flag, process.env.BACKUPDRILL_PING_URL, filePingUrl]
+        .map((value) => (typeof value === "string" ? value.trim() : undefined))
+        .find(Boolean);
 }
 // spread 里显式的 undefined 会覆盖前一层的值(CLI 未传的 flag 正是 undefined),
 // 合并前必须剔除,否则 env/配置文件里的 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 的项目里排序靠后的文件永远不被校验;
@@ -92,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";
@@ -329,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}`);
         }
@@ -569,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 = [
             {
@@ -605,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/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolvePingUrl } from "./config.js";
+import { backupSummary, createPinger, drillOutcome, pingMessageOf, sensitiveValuesOf } from "./ping.js";
 import { runBackup } from "./backup.js";
 import { runEstimate } from "./estimate.js";
 import { runDrill } from "./drill.js";
@@ -37,6 +38,10 @@ const EGRESS_PRICING = {
     pro: { planLabel: "Pro", includedGb: 250, pricePerGb: 0.09, hardCap: false },
     team: { planLabel: "Team", includedGb: 250, pricePerGb: 0.09, hardCap: false },
 };
+// backup 和 drill 共用:按 Healthchecks.io 的约定报告开始、成功、失败
+const PING_FLAG = "--ping-url <url>";
+const PING_HELP = "Healthchecks.io ping URL (or BACKUPDRILL_PING_URL): pings <url>/start, then <url> on " +
+    "success or <url>/fail on failure. A ping that fails only prints a warning";
 const program = new Command();
 program
     .name("backupdrill")
@@ -55,9 +60,13 @@ program
     .option("--endpoint <url>", "S3-compatible endpoint (required for R2/B2; omit for AWS S3)")
     .option("--region <region>", "bucket region (default: auto)")
     .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .option(PING_FLAG, PING_HELP)
     .action(async (opts) => {
+    const ping = createPinger(await resolvePingUrl({ flag: opts.pingUrl, configPath: opts.config }));
+    await ping.start();
+    let config;
     try {
-        const config = await loadConfig({
+        config = await loadConfig({
             configPath: opts.config,
             overrides: {
                 databaseUrl: opts.databaseUrl,
@@ -79,10 +88,13 @@ program
             `${storageNote}.`);
         // stdout 输出机器可读结果,便于在 CI / GitHub Action 里消费
         process.stdout.write(JSON.stringify({ ok: true, manifest }) + "\n");
+        await ping.success(backupSummary(manifest));
     }
     catch (error) {
-        log.error(error.message);
+        const message = error.message;
+        log.error(message);
         process.exitCode = 1;
+        await ping.fail(`backupdrill ${TOOL_VERSION}: backup failed. ${pingMessageOf(error)}`, sensitiveValuesOf(config, opts.databaseUrl));
     }
 });
 program
@@ -101,13 +113,17 @@ program
     "Note: connects as the sandbox superuser, so RLS policies are NOT enforced — " +
     "verify data and business invariants here, not RLS behavior")
     .option("--keep", "if the drill fails, keep the sandbox container running for inspection")
+    .option(PING_FLAG, PING_HELP)
     .action(async (opts) => {
+    const ping = createPinger(await resolvePingUrl({ flag: opts.pingUrl, configPath: opts.config }));
+    await ping.start();
+    let config;
     try {
         if (opts.checkCmd !== undefined && !String(opts.checkCmd).trim()) {
             throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to run a drill " +
                 "that would report a check that never executes");
         }
-        const config = await loadConfig({
+        config = await loadConfig({
             configPath: opts.config,
             overrides: {
                 projectName: opts.projectName,
@@ -136,12 +152,20 @@ program
             `${report.restoredTableCount} tables / ${report.restoredRowTotal.toLocaleString()} rows ` +
             `restored in ${report.restoreSeconds}s`);
         process.stdout.write(JSON.stringify({ ok: report.pass, report }) + "\n");
-        if (!report.pass)
+        const outcome = drillOutcome(report);
+        if (outcome.pass) {
+            await ping.success(outcome.text);
+        }
+        else {
             process.exitCode = 1;
+            await ping.fail(outcome.text, sensitiveValuesOf(config));
+        }
     }
     catch (error) {
-        log.error(error.message);
+        const message = error.message;
+        log.error(message);
         process.exitCode = 1;
+        await ping.fail(`backupdrill ${TOOL_VERSION}: drill failed. ${pingMessageOf(error)}`, sensitiveValuesOf(config));
     }
 });
 program

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/ping.d.ts

@@ -0,0 +1,31 @@
+import type { BackupConfig } from "./config.js";
+import type { DrillReport } from "./drill.js";
+import type { Manifest } from "./manifest.js";
+export interface Pinger {
+    start(): Promise<void>;
+    success(summary: string): Promise<void>;
+    /** sensitive:这次运行用到的连接串、密钥等,发出去之前从 reason 里抹掉 */
+    fail(reason: string, sensitive?: string[]): Promise<void>;
+}
+export declare function createPinger(rawUrl: string | undefined, opts?: {
+    timeoutMs?: number;
+    attempts?: number;
+    retryDelayMs?: number;
+}): Pinger;
+/** backup 成功时发给监控的一行。快照名取对象键里的目录名(和 drill --snapshot 认的是同一个) */
+export declare function backupSummary(manifest: Manifest): string;
+/** drill 跑完(没抛错)后发哪种 ping、带什么:通过 = 成功;没通过 = 失败,列出没过的检查 */
+export declare function drillOutcome(report: DrillReport): {
+    pass: boolean;
+    text: string;
+};
+/** 报错可以自带一句发给监控用的说法(pingMessage),比如不能复述配置文件原文的那种 */
+export declare function pingMessageOf(error: unknown): string;
+/**
+ * 失败原因发出去之前抹掉连接信息。先按值抹(这次运行确实用到的连接串、密码、主机、密钥),
+ * 再按形状兜底:pg / S3 的报错会带主机名、IP、整条连接串,配置文件解析失败时 JSON.parse
+ * 的报错还会带一截文件原文,这些都不是事先知道的值。
+ */
+export declare function scrubForPing(text: string, sensitive: string[]): string;
+/** 这次运行里不该出现在 ping 里的值:连接串、密码、主机、项目 ref、桶和 Storage 的密钥。 */
+export declare function sensitiveValuesOf(config: BackupConfig | undefined, extraDatabaseUrl?: string): string[];