backupdrill 2.3.0 → 2.5.0

package/dist/ping.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { log } from "./log.js";
+import { projectRefOf, refFromStorageEndpoint } from "./restore-engine.js";
+import { TOOL_VERSION } from "./version.js";
+// 按 Healthchecks.io 的 ping 约定报告一次 backup / drill(https://healthchecks.io/docs/http_api/):
+// 开始 <url>/start,成功 <url>,失败 <url>/fail,失败原因放请求体。三次请求带同一个 rid,
+// Healthchecks 才能把开始和结束配成一对算耗时,同一个检查并发跑两次也不会串。
+// 监控是旁路:ping 出任何问题只打警告,绝不改变备份/演练本身的结果和退出码。
+/** 每次请求的上限:Healthchecks 建议必须设超时,卡住的 /start 不能拖住备份本身 */
+const TIMEOUT_MS = 10_000;
+/** 网络错误和 5xx 重试;4xx(404 = 网址写错)重试也没用 */
+const ATTEMPTS = 3;
+const RETRY_DELAY_MS = 1_000;
+/** 失败原因只给个梗概:Healthchecks 会把请求体原样放进告警邮件和事件日志 */
+const BODY_LIMIT = 1_000;
+const NO_PING = {
+    start: async () => { },
+    success: async () => { },
+    fail: async () => { },
+};
+export function createPinger(rawUrl, opts = {}) {
+    if (!rawUrl)
+        return NO_PING;
+    let base;
+    try {
+        base = new URL(rawUrl);
+        if (base.protocol !== "https:" && base.protocol !== "http:")
+            throw new Error("not http(s)");
+    }
+    catch {
+        // 网址本身不对也只是监控没接上:备份照跑,Healthchecks 那边会因为收不到 ping 报警
+        log.warn("The ping URL is not a valid http(s) URL, so no pings will be sent. The run carries on.");
+        return NO_PING;
+    }
+    // fetch 拒绝带用户名密码的网址,而且拒绝时的报错里有整条网址;在这里先拦下,警告里不复述它
+    if (base.username || base.password) {
+        log.warn("The ping URL contains a username or password, which pings can't send, so no pings will be sent. The run carries on.");
+        return NO_PING;
+    }
+    const timeoutMs = opts.timeoutMs ?? TIMEOUT_MS;
+    const attempts = opts.attempts ?? ATTEMPTS;
+    const retryDelayMs = opts.retryDelayMs ?? RETRY_DELAY_MS;
+    const rid = randomUUID();
+    const endpoint = (suffix) => {
+        const url = new URL(base.href);
+        // 改 pathname 而不是拼字符串:slug 网址可能带 ?create=1,后缀要落在问号前面。
+        // 结尾的斜杠三种 ping 都去掉:Healthchecks 的 ping 路由不认带斜杠的网址
+        url.pathname = url.pathname.replace(/\/+$/, "") + suffix;
+        url.searchParams.set("rid", rid);
+        return url.href;
+    };
+    // 日志里只写 start/success/fail,不写网址:网址里的 UUID 谁拿到都能替你报平安
+    const send = async (kind, url, body) => {
+        let lastProblem = "";
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    body,
+                    headers: {
+                        "content-type": "text/plain; charset=utf-8",
+                        "user-agent": `backupdrill/${TOOL_VERSION}`,
+                    },
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                const answer = await readStart(res);
+                if (res.ok) {
+                    // Healthchecks.io 对查无此检查、超频的 ping 也回 200,正文是 "OK (not found)" /
+                    // "OK (rate limited)"(https://healthchecks.io/docs/http_api/);这类 ping 没记上,要提醒
+                    if (!/^OK \(/.test(answer))
+                        return;
+                    lastProblem = `Healthchecks answered "${answer.replace(/[^\x20-\x7e]/g, "").slice(0, 60)}"`;
+                    break;
+                }
+                lastProblem = `HTTP ${res.status}`;
+                if (res.status < 500)
+                    break;
+            }
+            catch (error) {
+                // 只报超时或错误码,不报原始报错:有些报错会把整条网址带出来
+                const err = error;
+                lastProblem =
+                    err.name === "TimeoutError"
+                        ? `no response within ${Math.round(timeoutMs / 1000)}s`
+                        : typeof err.cause?.code === "string"
+                            ? err.cause.code
+                            : "network error";
+            }
+            if (attempt < attempts)
+                await new Promise((r) => setTimeout(r, retryDelayMs * attempt));
+        }
+        log.warn(`Could not send the ${kind} ping (${lastProblem}). The run carries on.`);
+    };
+    return {
+        start: () => send("start", endpoint("/start")),
+        success: (summary) => send("success", endpoint(""), truncate(summary)),
+        fail: (reason, sensitive = []) => send("fail", endpoint("/fail"), truncate(scrubForPing(reason, sensitive))),
+    };
+}
+/** 只读响应开头一小段:Healthchecks 的回答就几个字节,网址填错指到大页面时也不整页下载 */
+async function readStart(res, limit = 256) {
+    if (!res.body)
+        return "";
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (size < limit) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            size += value.length;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return Buffer.concat(chunks).subarray(0, limit).toString("utf8").trim();
+}
+function truncate(text) {
+    return text.length > BODY_LIMIT ? `${text.slice(0, BODY_LIMIT - 1)}…` : text;
+}
+/** backup 成功时发给监控的一行。快照名取对象键里的目录名(和 drill --snapshot 认的是同一个) */
+export function backupSummary(manifest) {
+    return (`backupdrill ${TOOL_VERSION}: backup complete, ${manifest.database.tableCount} tables` +
+        (manifest.storage ? ` + ${manifest.storage.fileCount} Storage files` : " (database only)") +
+        `, snapshot ${manifest.dump.key.split("/").at(-2) ?? manifest.createdAt}`);
+}
+/** drill 跑完(没抛错)后发哪种 ping、带什么:通过 = 成功;没通过 = 失败,列出没过的检查 */
+export function drillOutcome(report) {
+    const outcome = `snapshot ${report.snapshot}, ${report.restoredTableCount} tables / ` +
+        `${report.restoredRowTotal.toLocaleString()} rows restored in ${report.restoreSeconds}s`;
+    if (report.pass)
+        return { pass: true, text: `backupdrill ${TOOL_VERSION}: drill passed, ${outcome}` };
+    const failed = report.checks.filter((c) => !c.pass).map((c) => `${c.name}: ${c.detail}`);
+    return {
+        pass: false,
+        text: `backupdrill ${TOOL_VERSION}: drill failed, ${outcome}. Failed checks:\n${failed.join("\n")}`,
+    };
+}
+/** 报错可以自带一句发给监控用的说法(pingMessage),比如不能复述配置文件原文的那种 */
+export function pingMessageOf(error) {
+    const err = error;
+    return typeof err?.pingMessage === "string" ? err.pingMessage : String(err?.message ?? error);
+}
+/**
+ * 失败原因发出去之前抹掉连接信息。先按值抹(这次运行确实用到的连接串、密码、主机、密钥),
+ * 再按形状兜底:pg / S3 的报错会带主机名、IP、整条连接串,配置文件解析失败时 JSON.parse
+ * 的报错还会带一截文件原文,这些都不是事先知道的值。
+ */
+export function scrubForPing(text, sensitive) {
+    let out = text;
+    // 长的先换:密码可能是连接串的一部分,先换短的会把长的打散,长的就匹配不上了
+    for (const value of [...new Set(sensitive)].sort((a, b) => b.length - a.length)) {
+        if (value.length >= 4)
+            out = out.split(value).join("[redacted]");
+    }
+    return out
+        // Postgres 把具体的值放在 DETAIL / CONTEXT 这类附加字段里(唯一键冲突的键值、COPY 出错的整行),
+        // pg_restore 还会回显出错的 SQL。从第一个这类字段起把这一行剩下的全部去掉:值里什么字符都可能有,
+        // 包括多条报错之间的拼接符 " | ",所以不能指望找到字段的结尾。引擎上报的恢复错误块已经压成一行
+        .replace(/\b(DETAIL|CONTEXT|HINT|QUERY|STATEMENT|LINE \d+|Command was):[^\n]*/g, "$1: [removed]")
+        // 主报错里偶尔也带值:键值对 (col)=(value),以及 invalid input syntax for type x: "value"
+        .replace(/\(([^()]*)\)=\((?:[^()]|\([^()]*\))*\)/g, "($1)=([removed])")
+        .replace(/(invalid input (?:syntax|value) for [^:"\n]*: )"[^"\n]*"/gi, '$1"[removed]"')
+        .replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>`]+/gi, "[url]")
+        .replace(/[^\s"'<>`/@]*:[^\s"'<>`/@]*@/g, "[redacted]@")
+        // Supabase pooler 的用户名是 postgres.<项目 ref>
+        .replace(/\bpostgres\.[a-z0-9]{16,}\b/gi, "postgres.[ref]")
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "[ip]")
+        .replace(/\b[0-9a-f]{1,4}(?::[0-9a-f]{0,4}){3,7}\b/gi, "[ip]")
+        // 至少两个点的主机名;常见文件扩展名放过,免得把 backupdrill.config.json 也抹了
+        .replace(/\b(?:[a-z0-9-]+\.){2,}(?!(?:json|md|ya?ml|js|ts|txt|log|sql|pgcustom)\b)[a-z]{2,}\b/gi, "[host]");
+}
+/** 这次运行里不该出现在 ping 里的值:连接串、密码、主机、项目 ref、桶和 Storage 的密钥。 */
+export function sensitiveValuesOf(config, extraDatabaseUrl) {
+    const env = process.env;
+    const values = [
+        // Storage 端点里有项目 ref(<ref>.storage.supabase.co),库与 Storage 不是同一项目的报错会带出它
+        ...[config?.supabaseStorage?.endpoint, env.BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT].flatMap((endpoint) => endpoint ? [refFromStorageEndpoint(endpoint) ?? undefined, hostOf(endpoint)] : []),
+        ...[config?.storage?.endpoint, env.BACKUPDRILL_S3_ENDPOINT].map(hostOf),
+        env.BACKUPDRILL_S3_ACCESS_KEY_ID,
+        env.BACKUPDRILL_S3_SECRET_ACCESS_KEY,
+        env.BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID,
+        env.BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY,
+        config?.storage?.accessKeyId,
+        config?.storage?.secretAccessKey,
+        config?.supabaseStorage?.accessKeyId,
+        config?.supabaseStorage?.secretAccessKey,
+    ];
+    for (const conn of [config?.databaseUrl, extraDatabaseUrl, env.BACKUPDRILL_DATABASE_URL, env.DATABASE_URL]) {
+        if (!conn)
+            continue;
+        values.push(conn, projectRefOf(conn) ?? undefined);
+        // 用户名不进列表:常见的就是 postgres,按值抹会把报错里每个 postgres 都换掉;
+        // pooler 用户名里真正要藏的项目 ref 上面已经单独抹了
+        try {
+            const url = new URL(conn);
+            values.push(url.hostname, url.password, decodeURIComponent(url.password));
+        }
+        catch {
+            // 解析不了的连接串整条已经在列表里了
+        }
+    }
+    return values.filter((v) => Boolean(v));
+}
+function hostOf(endpoint) {
+    if (!endpoint)
+        return undefined;
+    try {
+        return new URL(endpoint).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}

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.3.0",
+  "version": "2.5.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": {
@@ -17,9 +17,15 @@
   },
   "files": [
     "dist",
+    "plugin/skills",
     "README.md",
     "LICENSE"
   ],
+  "pi": {
+    "skills": [
+      "./plugin/skills"
+    ]
+  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build && npm test",
@@ -43,7 +49,9 @@
     "s3",
     "cloudflare-r2",
     "backblaze-b2",
-    "disaster-recovery"
+    "disaster-recovery",
+    "healthchecks",
+    "pi-package"
   ],
   "license": "MIT",
   "author": "BackupDrill <support@backupdrill.com> (https://backupdrill.com)",

package/plugin/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/plugin/README.md

@@ -0,0 +1,79 @@
+# BackupDrill plugin
+
+Back up a Supabase project to a bucket you own and prove the backup restores, by asking your coding agent. The plugin is one skill that teaches the agent to use [backupdrill](https://github.com/backupdrill/cli), the open-source (MIT) CLI behind backupdrill.com:
+
+- `estimate` measures the database and Storage files and projects the Supabase egress cost of backing them up.
+- `backup` dumps the Postgres database with `pg_dump`, plus Storage files once you add their S3 keys, into your S3, R2 or B2 bucket, with a checksummed `manifest.json` and a `RECOVERY.md` in every snapshot.
+- `drill` restores a snapshot into a throwaway Postgres in Docker, checks that the tables and their data came back, and checksums a sample of the Storage files.
+- `restore` puts a snapshot into a new, empty Supabase project, after a dry run and only once you confirm the target.
+
+The agent runs every command as `npx -y backupdrill@2.5.0`, so the CLI version stays fixed.
+
+## What you need
+
+- A shell the agent can use, such as Claude Code. In a chat with no terminal, the agent can explain the commands but not run them.
+- Node.js 20 or newer.
+- `pg_dump` and `pg_restore` version 17, which handle Supabase's Postgres 15 to 17. On macOS: `brew install libpq@17` (plain `libpq` is now 18, whose dumps can contain SQL that Postgres 17 rejects).
+- Docker, for `drill`.
+- A bucket on AWS S3, Cloudflare R2 or Backblaze B2, with a key that can list, read and write objects in it.
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add backupdrill/cli
+/plugin install backupdrill@backupdrill
+```
+
+Or from a terminal:
+
+```sh
+claude plugin install backupdrill --marketplace backupdrill/cli
+```
+
+In Pi, the same skill comes with the npm package:
+
+```sh
+pi install npm:backupdrill
+```
+
+## Things to ask
+
+- "Back up my Supabase project to my R2 bucket."
+- "How much egress would a daily backup of this project add on the Pro plan?"
+- "Run a restore drill on the latest backup and tell me whether it passed."
+- "Set up a weekly backup in GitHub Actions."
+- "Restore last night's snapshot into my new staging project. Dry run first."
+
+## Your credentials
+
+The skill keeps your connection string and bucket keys in `.env.backupdrill` in your project root and adds that file to `.gitignore`. It creates the file with placeholders and asks you to fill it in your editor. The agent is told never to open or print the file, never to ask for keys in the chat, and to load the file only for the command that needs it.
+
+## What runs and where your data goes
+
+Everything runs on your machine:
+
+- `npx` downloads the `backupdrill` package from the npm registry the first time.
+- The CLI connects to your Supabase project's database, to its Storage if you add Storage S3 keys, and to your bucket. `restore` also connects to the target project you name.
+- `drill` starts a temporary Postgres container in Docker. The first time, Docker downloads the Postgres image from Docker Hub.
+- Nothing goes to BackupDrill. There is no account, telemetry or license check.
+
+What the agent reads while it works, such as command output with table names, row counts and file names, goes to your model provider like the rest of your conversation. The CLI itself never deletes objects in your bucket.
+
+## Troubleshooting
+
+- `Missing required config`: the message names the missing setting. Fill that line in `.env.backupdrill`.
+- A `pg_dump` version error: install the version 17 PostgreSQL client and set `BACKUPDRILL_PG_DUMP` to its `pg_dump`.
+- Can't connect to the database: use the Session pooler string from the Connect button in the Supabase dashboard, not the Direct one. Resume the project if it's paused.
+- `drill` can't start a container: start Docker.
+
+The CLI's [README](https://github.com/backupdrill/cli#readme) covers every option, and [backupdrill.com/docs/cli](https://backupdrill.com/docs/cli) walks through the same steps.
+
+## Support
+
+Open an issue at [github.com/backupdrill/cli/issues](https://github.com/backupdrill/cli/issues) or email support@backupdrill.com. Privacy policy: [backupdrill.com/privacy](https://backupdrill.com/privacy).
+
+## License
+
+MIT