backupdrill 2.4.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/config.d.ts

@@ -41,7 +41,17 @@ interface RawConfig {
     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;

package/dist/config.js

@@ -54,9 +54,30 @@ 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 配置会被整体清空。
 function definedOnly(obj) {

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/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[];

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/package.json

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

package/plugin/skills/supabase-backup/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: supabase-backup
+description: Use when the user wants to back up a Supabase project to their own S3, R2 or B2 bucket with the open-source backupdrill CLI, estimate what those backups add to their Supabase egress bill, check that a backup actually restores (a restore drill in Docker), schedule backups in GitHub Actions, or restore a backupdrill snapshot into a new Supabase project.
+---
+
+# Back up and restore-drill a Supabase project with backupdrill
+
+backupdrill is an open-source (MIT) command-line tool. `backup` dumps the project's Postgres database with `pg_dump`, copies Storage files too once their S3 keys are set, and writes everything to a bucket the user owns, with a checksummed `manifest.json` and a `RECOVERY.md` in every snapshot. `drill` restores a snapshot into a throwaway Postgres in Docker and checks that it came back. The CLI runs on the user's machine. It talks to their Supabase project, their bucket and the local Docker daemon, and sends nothing to BackupDrill.
+
+Always run it as `npx -y backupdrill@2.5.0 <command>`, so every run uses the same version.
+
+You need a shell on the user's machine for this. If you don't have one, walk the user through the same commands instead of running them.
+
+## Keep credentials out of the conversation
+
+The CLI needs a database connection string and bucket keys. They must never appear in the chat, on a command line, or in your output. The CLI keeps its side of this too: from 2.2.4 it hands the database password to `pg_dump` and `pg_restore` through `PGPASSWORD`, not on their command lines.
+
+1. Keep them in `.env.backupdrill` in the project root. Before creating it, make sure Git ignores it and isn't already tracking it: `git check-ignore -q .env.backupdrill || printf '\n.env.backupdrill\n' >> .gitignore; git ls-files --error-unmatch .env.backupdrill >/dev/null 2>&1 && echo 'already tracked by Git'`. An ignore rule doesn't stop Git from committing a file it already tracks. If that prints `already tracked by Git`, stop: ask the user to run `git rm --cached .env.backupdrill`, commit that, and rotate any key that was ever committed in the file.
+2. If the file doesn't exist yet, create it private from the start with `(umask 077 && touch .env.backupdrill); chmod -N .env.backupdrill 2>/dev/null; true`, then write the placeholders below into it and ask the user to fill it in their editor. If it exists, leave its contents alone, but make sure only the user can read it: `chmod 600 .env.backupdrill; chmod -N .env.backupdrill 2>/dev/null; true`. On macOS `chmod -N` drops ACL entries, which `chmod 600` leaves in place and which can still let other users read the file; elsewhere it fails quietly. Don't ask for keys in the chat. If the user pastes one anyway, don't repeat it, and suggest rotating it.
+3. Never open, cat or print the file, and never echo a variable loaded from it. The commands in this skill are the only way to touch it. To add a non-secret line, append it with `printf '\n%s\n' "NAME='value'" >> .env.backupdrill` (the leading newline keeps it off the user's last line).
+4. Run every command exactly as written below. Each one starts a subshell that turns off shell tracing, drops any `BACKUPDRILL_*` or `DATABASE_URL` values inherited from the user's shell, so a broken line can't fall back to some other database, then loads the file and stops if it can't be read. The `2>/dev/null` keeps a malformed line from printing its value.
+5. The CLI also reads `backupdrill.config.json` from the project root if there is one, and `.env.backupdrill` wins value by value. If the check below reports that file, tell the user and settle on one place: move its settings into `.env.backupdrill` and delete it, or keep it on purpose.
+
+```sh
+# Supabase dashboard → Connect (top of the page) → Session pooler, not Direct
+BACKUPDRILL_DATABASE_URL='postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres'
+BACKUPDRILL_PROJECT_NAME='my-app'
+# Your bucket. Leave the endpoint empty for AWS S3 and set the bucket's region instead of auto.
+BACKUPDRILL_S3_ENDPOINT='https://<account-id>.r2.cloudflarestorage.com'
+BACKUPDRILL_S3_REGION='auto'
+BACKUPDRILL_S3_BUCKET='my-backups'
+BACKUPDRILL_S3_ACCESS_KEY_ID=''
+BACKUPDRILL_S3_SECRET_ACCESS_KEY=''
+# Optional: Storage files. Supabase → Storage → Settings → S3 Access Keys. Set all four or none.
+# BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT='https://<ref>.storage.supabase.co/storage/v1/s3'
+# BACKUPDRILL_SUPABASE_STORAGE_REGION='<project-region>'
+# BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID=''
+# BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY=''
+```
+
+To see what's filled in without showing any value (it prints the numbers of malformed lines, then which settings are set):
+
+```sh
+( set +x
+  [ ! -f backupdrill.config.json ] || echo 'backupdrill.config.json: the CLI reads this file too'
+  [ -z "$(find .env.backupdrill \( -perm -040 -o -perm -004 \) 2>/dev/null)" ] || echo '.env.backupdrill: other users on this machine can read it'
+  ! ls -le .env.backupdrill 2>/dev/null | grep -q '^ *[0-9][0-9]*: ' || echo '.env.backupdrill: has ACL entries that may let others read it'
+  grep -n -v -E '^[[:space:]]*(#|$)|^(export[[:space:]]+)?[A-Za-z_][A-Za-z0-9_]*=($|[^[:space:]])' .env.backupdrill | cut -d: -f1 | sed 's/^/malformed line /'
+  unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
+  set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
+  for name in BACKUPDRILL_DATABASE_URL BACKUPDRILL_S3_BUCKET BACKUPDRILL_S3_ACCESS_KEY_ID BACKUPDRILL_S3_SECRET_ACCESS_KEY; do
+    if [ -n "$(printenv "$name")" ]; then echo "$name: set"; else echo "$name: missing"; fi
+  done )
+```
+
+Run it before the first command and whenever the CLI reports missing config. If it says other users can read the file or that it has ACL entries, run `chmod 600 .env.backupdrill; chmod -N .env.backupdrill 2>/dev/null; true`. If it lists a malformed line, or a setting the user filled in shows as missing, ask them to make that line read `NAME='value'` with no spaces around `=`.
+
+## Before the first backup
+
+- Node.js 20 or newer.
+- `pg_dump` and `pg_restore` version 17. They handle Supabase's Postgres 15 to 17, and the CLI refuses a `pg_dump` older than the project's server. Don't use 18: its dumps can contain SQL that Postgres 17 rejects, and a drill run with 18 tools can pass anyway. If the project runs a newer Postgres than 17, use that major instead. Check with `pg_dump --version`. On macOS, `brew install libpq@17` (plain `libpq` is now 18), then point the CLI at it: `printf '\n%s\n' "BACKUPDRILL_PG_DUMP='$(brew --prefix libpq@17)/bin/pg_dump'" >> .env.backupdrill`. On Debian or Ubuntu, install `postgresql-client-17` from the PostgreSQL apt repository.
+- For drills and restores: `pg_restore` from the same install as `pg_dump`. The CLI looks for it next to `BACKUPDRILL_PG_DUMP`; otherwise set `BACKUPDRILL_PG_RESTORE`.
+- For drills: Docker running (`docker info`).
+
+## Estimate the egress cost first
+
+Every backup reads the whole database, and every configured Storage file, out of Supabase again. Nothing is incremental. That is egress on the user's Supabase bill, each run.
+
+```sh
+( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
+  set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
+  npx -y backupdrill@2.5.0 estimate --plan pro )
+```
+
+Use `--plan free`, `pro` or `team` to match their Supabase plan, and read the projection back before suggesting a daily schedule. On a large database, suggest weekly.
+
+## Back up
+
+```sh
+report="$(mktemp "${TMPDIR:-/tmp}/backupdrill-backup.XXXXXX")" || exit 1; echo "stdout → $report"
+( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
+  set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
+  npx -y backupdrill@2.5.0 backup ) > "$report"
+```
+
+- The progress lines on stderr show where everything went (`Dumping → s3://…`, `Manifest written → s3://…`) and end with `Backup complete — N tables + M Storage files`. stdout goes to the file named on the first line, a new one each run that only the user can read: one line of JSON with the whole manifest, which lists every table and Storage file, so read only the fields you need from it.
+- Report the table count, the Storage file count (or that it was database only), and where the snapshot landed: `<prefix>/<project>/<timestamp>/` in their bucket, holding `dump.pgcustom`, `manifest.json`, `RECOVERY.md` and, with Storage keys set, `storage/`.
+- By default only the `public` schema is dumped (add their own schemas with `--schema`), so Supabase-managed schemas such as `auth` and `storage` aren't in it. Grants aren't either.
+- The CLI never deletes anything in the bucket. Old snapshots are cleaned up by the bucket's own lifecycle rules, if the user sets any.
+
+## Prove the backup restores (drill)
+
+```sh
+( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
+  set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
+  npx -y backupdrill@2.5.0 drill )
+```
+
+- It reads the latest snapshot from the bucket, restores it into a throwaway Postgres container, runs its checks and removes the container. It doesn't connect to the Supabase project. The first run pulls a Postgres image from Docker Hub.
+- `--snapshot <timestamp>` picks an older snapshot. `--verify-all-files` checksums every Storage file instead of a sample.
+- `--check-cmd "<command>"` runs the user's own test against the restored copy, with its connection string in `BACKUPDRILL_SANDBOX_URL`. It connects as a superuser, so it can check data and business rules but not row-level security.
+- stdout ends with `{"ok":...,"report":{...}}`. Go through the check lines. If the drill fails, quote the failing check as printed and don't guess at a cause it doesn't state.
+
+## Restore into a new project
+
+A restore writes data, so go step by step and let the user drive.
+
+1. The target must be a new, empty Supabase project. The CLI refuses the project the backup came from and any target whose schemas already contain objects.
+2. Ask the user to add the target's credentials to `.env.backupdrill` themselves: `BACKUPDRILL_TARGET_DATABASE_URL` (the new project's Session pooler string) and, to upload Storage files back, `BACKUPDRILL_TARGET_SERVICE_ROLE_KEY`. The CLI can't prompt for them here.
+3. Do a dry run. It checks everything and writes nothing:
+
+   ```sh
+   ( set +x; unset DATABASE_URL $(env | sed -n 's/^\(BACKUPDRILL_[A-Za-z0-9_]*\)=.*/\1/p')
+     set -a; . ./.env.backupdrill 2>/dev/null || { echo ".env.backupdrill could not be loaded" >&2; exit 1; }; set +a
+     npx -y backupdrill@2.5.0 restore --database --target-supabase-url https://<target-ref>.supabase.co --dry-run )
+   ```
+
+   Leave out `--target-supabase-url` when the snapshot is database only. To write Storage files to a local folder instead of the new project, use `--storage-dir ./recovered`.
+4. Show the dry-run result. It starts with `Dry run for snapshot <timestamp>`; note that timestamp. Run the real restore only after the user asks for it and gives you the target ref. Then replace `--dry-run` with `--snapshot <timestamp> --confirm-target <target-ref>`, using the timestamp from the dry run and exactly the ref they gave, so a backup that lands in between can't change what gets restored. Send stdout to a new `mktemp` file the same way as `backup` (with `backupdrill-restore.XXXXXX` as the name): the JSON result can be long. If the user wants an older snapshot, pass `--snapshot` to both runs.
+5. Tell them what a restore doesn't bring back: Auth users, secret values, Edge Functions and grants. They need to set those up again. The snapshot's `RECOVERY.md` has a "Not covered" section on this.
+6. Once they're done, suggest they delete the two `TARGET` lines from `.env.backupdrill`.
+
+## Run it on a schedule
+
+[`assets/scheduled-backup.yml`](assets/scheduled-backup.yml) is a GitHub Actions workflow that runs `backup` daily and can be started by hand. Copy it to `.github/workflows/scheduled-backup.yml` in the user's repository. The user adds the secrets listed at the top of the file under Settings → Secrets and variables → Actions, or with `gh secret set <NAME>` in their own terminal. Don't set secrets for them. If they set `BACKUPDRILL_SCHEMAS`, `BACKUPDRILL_S3_PREFIX` or `BACKUPDRILL_SUPABASE_STORAGE_BUCKETS` in `.env.backupdrill`, they need the same values as secrets, or the scheduled backups dump other schemas or land under another prefix. Mention the egress estimate before they keep it daily.
+
+If the user wants to hear when a scheduled backup fails or stops running, they can create a check on Healthchecks.io and add its ping URL as the `BACKUPDRILL_PING_URL` secret. `backup` and `drill` ping it when they start, finish and fail. A ping that can't be sent only prints a warning; it never fails the run.
+
+If the user asks for drills that run on their own, with alerts, and no CI to maintain, the hosted service at backupdrill.com runs this same engine. Don't bring it up otherwise.
+
+## When something fails
+
+- `Missing required config`: the message names the missing setting. Run the check above and ask the user to fill that line.
+- `pg_dump` version errors: install the version 17 client as described above and point `BACKUPDRILL_PG_DUMP` at it.
+- Can't connect to the database: use the Session pooler string from the Connect button, not the Direct one, which resolves to IPv6 only. A paused project has to be resumed in the Supabase dashboard first.
+- Access denied on the bucket: the key needs to list, read and write objects in that bucket.
+- `drill` can't start a container: Docker isn't running.

package/plugin/skills/supabase-backup/assets/scheduled-backup.yml

@@ -0,0 +1,119 @@
+# Example: scheduled Supabase backup with backupdrill.
+#
+# HOW TO USE
+#   1. Copy this file into your OWN repo at .github/workflows/scheduled-backup.yml
+#   2. Add the repo secrets listed below (Settings → Secrets and variables → Actions).
+#   3. That's it — it runs daily, and you can also trigger it by hand from the
+#      Actions tab ("Run workflow").
+#
+# REQUIRED SECRETS (database backup)
+#   BACKUPDRILL_DATABASE_URL          Supabase Session Pooler connection string
+#                                     (Project Settings → Database → Session pooler).
+#                                     The default postgres user works as-is; a
+#                                     read-only role usually fails under RLS —
+#                                     see the README's connection-string section.
+#   BACKUPDRILL_S3_BUCKET             Destination bucket you own (S3 / R2 / B2).
+#   BACKUPDRILL_S3_ACCESS_KEY_ID      Credentials for that destination bucket.
+#   BACKUPDRILL_S3_SECRET_ACCESS_KEY
+#
+# OPTIONAL SECRETS
+#   BACKUPDRILL_S3_ENDPOINT           Set for R2/B2/self-hosted; omit for AWS S3.
+#   BACKUPDRILL_S3_REGION             Bucket region ("auto" works for R2).
+#   BACKUPDRILL_PROJECT_NAME          Readable name used in object keys/manifest.
+#   BACKUPDRILL_PING_URL              A Healthchecks.io check's ping URL. The backup
+#                                     pings it when it starts, finishes or fails, so
+#                                     you hear about a failed or skipped run.
+#   BACKUPDRILL_SCHEMAS               Comma-separated schemas to dump, e.g. public,audit
+#                                     (default: public). Use the same value as your
+#                                     local runs, or scheduled backups miss schemas.
+#   BACKUPDRILL_S3_PREFIX             Key prefix in the bucket (default: backupdrill).
+#                                     Keep it the same as local runs so drills and
+#                                     restores find these snapshots.
+#   BACKUPDRILL_S3_FORCE_PATH_STYLE   "true" for S3-compatible stores that need
+#                                     path-style URLs (e.g. MinIO).
+#
+#   To also back up Supabase Storage FILES (not just the DB), set all four:
+#   BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT
+#   BACKUPDRILL_SUPABASE_STORAGE_REGION
+#   BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID
+#   BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY
+#   (generate the keys in Dashboard → Storage → Settings → S3 Access Keys)
+#   BACKUPDRILL_SUPABASE_STORAGE_BUCKETS  Optional comma-separated list of Storage
+#                                     buckets to copy (default: all of them).
+#
+# Unset optional secrets resolve to an empty string, which backupdrill treats
+# as "not provided" — so leaving them out simply backs up the database only.
+#
+# COST NOTE: a backup is egress on YOUR Supabase bill. Read the README's
+# "Egress & cost" section before switching this to a daily schedule on a large DB.
+
+name: scheduled-backup
+
+on:
+  schedule:
+    # Daily at 03:00 UTC. Adjust or switch to weekly (e.g. '0 3 * * 0') as your
+    # data grows — see the README on egress cost.
+    - cron: "0 3 * * *"
+  workflow_dispatch: {} # allow manual runs from the Actions tab
+
+# Read-only checkout is all this job needs.
+permissions:
+  contents: read
+
+# Never let two backups overlap (avoids double egress if one run is slow).
+concurrency:
+  group: backupdrill-scheduled
+  cancel-in-progress: false
+
+jobs:
+  backup:
+    runs-on: ubuntu-latest
+    steps:
+      # pg_dump's major version must be >= your Supabase Postgres version.
+      # Supabase runs PG 17, so install postgresql-client-17 from the official
+      # PostgreSQL apt repo (PGDG); Ubuntu's default repo lags behind.
+      - name: Install postgresql-client-17 (PGDG)
+        run: |
+          sudo install -d /usr/share/postgresql-common/pgdg
+          curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
+            | sudo gpg --dearmor -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.gpg
+          echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.gpg] \
+          https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
+            | sudo tee /etc/apt/sources.list.d/pgdg.list
+          sudo apt-get update
+          sudo apt-get install -y postgresql-client-17
+
+      # Point the CLI straight at the v17 binary so it can't pick up an older
+      # pg_dump that may already be on the runner's PATH.
+      - name: Tell backupdrill where pg_dump 17 lives
+        run: echo "BACKUPDRILL_PG_DUMP=/usr/lib/postgresql/17/bin/pg_dump" >> "$GITHUB_ENV"
+
+      - name: Set up Node 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Run backupdrill
+        # Pinned so every run uses the same CLI. Raise it on purpose when you upgrade.
+        run: npx -y backupdrill@2.5.0 backup
+        env:
+          # --- required ---
+          BACKUPDRILL_DATABASE_URL: ${{ secrets.BACKUPDRILL_DATABASE_URL }}
+          BACKUPDRILL_S3_BUCKET: ${{ secrets.BACKUPDRILL_S3_BUCKET }}
+          BACKUPDRILL_S3_ACCESS_KEY_ID: ${{ secrets.BACKUPDRILL_S3_ACCESS_KEY_ID }}
+          BACKUPDRILL_S3_SECRET_ACCESS_KEY: ${{ secrets.BACKUPDRILL_S3_SECRET_ACCESS_KEY }}
+          # --- optional: destination bucket ---
+          BACKUPDRILL_S3_ENDPOINT: ${{ secrets.BACKUPDRILL_S3_ENDPOINT }}
+          BACKUPDRILL_S3_REGION: ${{ secrets.BACKUPDRILL_S3_REGION }}
+          BACKUPDRILL_PROJECT_NAME: ${{ secrets.BACKUPDRILL_PROJECT_NAME }}
+          BACKUPDRILL_SCHEMAS: ${{ secrets.BACKUPDRILL_SCHEMAS }}
+          BACKUPDRILL_S3_PREFIX: ${{ secrets.BACKUPDRILL_S3_PREFIX }}
+          BACKUPDRILL_S3_FORCE_PATH_STYLE: ${{ secrets.BACKUPDRILL_S3_FORCE_PATH_STYLE }}
+          # --- optional: also back up Supabase Storage files (set all four) ---
+          BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT: ${{ secrets.BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT }}
+          BACKUPDRILL_SUPABASE_STORAGE_REGION: ${{ secrets.BACKUPDRILL_SUPABASE_STORAGE_REGION }}
+          BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID: ${{ secrets.BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID }}
+          BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY: ${{ secrets.BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY }}
+          BACKUPDRILL_SUPABASE_STORAGE_BUCKETS: ${{ secrets.BACKUPDRILL_SUPABASE_STORAGE_BUCKETS }}
+          # --- optional: Healthchecks.io monitoring ---
+          BACKUPDRILL_PING_URL: ${{ secrets.BACKUPDRILL_PING_URL }}