backupdrill 2.2.3 → 2.2.5

package/README.md

@@ -31,6 +31,17 @@ npm install -g backupdrill
 npx backupdrill backup
 ```
 
+## Use it from Claude Code or Cursor
+
+The [`plugin/`](plugin/) folder is a plugin for Claude Code and Cursor. It teaches the agent to run `estimate`, `backup`, `drill` and `restore` for you, keeps your keys in a gitignored `.env.backupdrill` that the agent never opens, and always does a dry run before a restore. In Claude Code:
+
+```
+/plugin marketplace add backupdrill/cli
+/plugin install backupdrill@backupdrill
+```
+
+Details are in [plugin/README.md](plugin/README.md).
+
 ## Usage
 
 Configure via **env vars**, a **config file**, or **flags** (precedence: flags > env > file).

package/dist/backup.js

@@ -17,7 +17,7 @@ import { dumpPartSizeFor } from "./part-size.js";
 // 解析函数搬到了 pgbin(演练与恢复都要读 pg_restore 版本,放这里会成环);保留旧出口
 export { parsePgDumpMajor };
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
-import { libpqChildEnv, urlSslModeOf } from "./restore-engine.js";
+import { credentialSafeDbArgs, libpqChildEnv, urlSslModeOf } from "./restore-engine.js";
 const execFileAsync = promisify(execFile);
 function majorOf(serverVersionNum) {
     // server_version_num: 150004 → 15,  170002 → 17
@@ -106,7 +106,9 @@ async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
     });
     const schemaArgs = config.schemas.map((s) => `--schema=${s}`);
     // pg_dump(libpq):Supabase 主机才改写成 sslmode=verify-full + sslrootcert=<打包CA临时文件>
-    const dumpDbUrl = dumpUrlFor(config.databaseUrl);
+    // 凭据不进 argv(D6):argv 对同机任何进程的 `ps` 可见。与恢复路径同一个函数——
+    // 先改写 SSL 再拆密码,密码经 PGPASSWORD 交给 libpq
+    const { url: dumpDbUrl, env: credentialEnv } = credentialSafeDbArgs(dumpUrlFor(config.databaseUrl));
     const dump = spawn(pgDumpBin, [
         "--format=custom",
         "--no-owner",
@@ -118,7 +120,7 @@ async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
     // 环境剔除改写目标/身份的 PG* 变量:pg_dump 只认 --dbname 里的 URL(TLS 策略等保留)
     {
         stdio: ["ignore", "pipe", "pipe"],
-        env: libpqChildEnv({}, process.env, {
+        env: libpqChildEnv(credentialEnv, process.env, {
             supabaseHost: isSupabaseHost(config.databaseUrl),
             urlSslMode: urlSslModeOf(dumpDbUrl),
         }),

package/dist/restore-engine.js

@@ -395,6 +395,10 @@ export function credentialSafeDbArgs(connString) {
         }
         return { url: connString, env: {} };
     }
+    // 兜底(入口的 assertNoHostOverride 已拒字面 #):片段留在输出里,libpq 会把 `#?host=…` 当查询参数
+    if (url.hash) {
+        throw new Error("connection string contains a literal '#' — percent-encode it as %23 (for example inside the password).");
+    }
     let password = "";
     if (url.password) {
         try {
@@ -427,9 +431,9 @@ export function credentialSafeDbArgs(connString) {
             if (/^password$/i.test(key)) {
                 const rawValue = eq === -1 ? "" : part.slice(eq + 1);
                 try {
-                    const value = decodeURIComponent(rawValue.replace(/\+/g, "%20"));
-                    if (value)
-                        queryPasswords.push(value);
+                    // 空值也要记:libpq 取最后一个(空 = 回落 .pgpass),只记非空会把前面的旧值
+                    // 当成密码——?password=stale&password= 预检走 .pgpass、pg_dump 却用 stale
+                    queryPasswords.push(decodeURIComponent(rawValue.replace(/\+/g, "%20")));
                 }
                 catch {
                     throw new Error("the connection string ?password= value contains malformed percent-encoding — " +
@@ -469,6 +473,12 @@ export function assertNoHostOverride(connString) {
     if (containsNul(connString)) {
         throw new Error("connection string contains a NUL byte — use a plain connection string.");
     }
+    // 字面 # 同样在解析前拒:WHATWG URL 把 # 之后当片段,这里看到的主机干净;libpq 不认片段,
+    // 剥掉 ?password= 后剩下的 `#?host=…` 会被它读成查询参数,改写连接目标(交叉审查)。
+    // 合法的 # 只会出现在密码等值里,写成 %23 即可
+    if (connString.includes("#")) {
+        throw new Error("connection string contains a literal '#' — percent-encode it as %23 (for example inside the password).");
+    }
     // 解析不了的连接串直接拒:曾经"放行让 pg 自己报错",但 pg 的解析器比 WHATWG URL 宽
     // (`postgresql://user@/db?host=…` 这类串 pg 接受、这里解析失败),放行 = 身份判定为空却照样连接
     // (交叉审查)。校验逻辑放在 try 外面——曾按文案里有没有 "override" 决定重抛,新理由一措辞不同就被吞。

package/dist/restore.d.ts

@@ -61,6 +61,12 @@ export declare function assertRequestApplies(manifest: Manifest, wantsDatabase:
  * 这道门要求人把目标身份亲手打一遍。
  */
 export declare function assertConfirmedTarget(confirmTarget: string | undefined, targetDatabaseUrl?: string, targetSupabaseUrl?: string): void;
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export declare function nonEmptyTargetMessage(schemas: string[], objectCount: number, alsoRestoringStorage: boolean): string;
 /**
  * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
  * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),

package/dist/restore.js

@@ -155,6 +155,20 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
             `(use --dry-run first to preview all checks without writing).`);
     }
 }
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export function nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage) {
+    const message = `target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
+        `restore only writes into an empty target. Create a fresh Supabase project ` +
+        `(or empty these schemas) and retry.`;
+    if (!alsoRestoringStorage)
+        return message;
+    return (`${message} If a previous run already restored the database and only Storage was ` +
+        `interrupted, re-run WITHOUT the database target to retry Storage alone.`);
+}
 /**
  * 空目标门(PRD §5.3.3 / 决策 D5):目标 schema 里存在任何用户对象即拒绝写入。
  * "空"的定义来自 R0 spike:不是"schema 不存在"(Supabase 恒有 public),而是
@@ -162,7 +176,7 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
  * 全部计入:只查关系时,"目标里只有函数"会放行,然后在 pre-data 中途撞冲突,
  * 留下半截目标(评审第 7 轮)。
  */
-async function assertEmptyTarget(targetUrl, schemas) {
+async function assertEmptyTarget(targetUrl, schemas, alsoRestoringStorage) {
     const client = await connectPg(targetUrl);
     try {
         const res = await client.query(`select
@@ -175,11 +189,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
          as n`, [schemas]);
         const objectCount = Number(res.rows[0].n);
         if (objectCount > 0) {
-            throw new Error(`target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
-                `restore only writes into an empty target. Create a fresh Supabase project ` +
-                `(or empty these schemas) and retry. If a previous run already restored the ` +
-                `database and only Storage was interrupted, re-run WITHOUT the database target ` +
-                `to retry Storage alone.`);
+            throw new Error(nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage));
         }
     }
     finally {
@@ -190,7 +200,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
  * dry-run 只读预检(PRD §5.3.2):零写入,把正式执行会撞的墙全部提前撞一遍。
  * 逐项打印,任何 blocker 汇总后抛出(退出码非零 = "现在执行不会成功")。
  */
-async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
+async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoRestoringStorage) {
     const blockers = [];
     const db = manifest.database;
     const mb = (n) => (n / 1024 / 1024).toFixed(1);
@@ -221,7 +231,7 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
             log.ok("target identity: distinct from source");
         }
         try {
-            await assertEmptyTarget(targetUrl, db.schemas);
+            await assertEmptyTarget(targetUrl, db.schemas, alsoRestoringStorage);
             log.ok(`target schemas (${db.schemas.join(", ")}) are empty`);
         }
         catch (error) {
@@ -376,10 +386,13 @@ export async function runRestore(config, opts) {
         storageFilesWritten: 0,
     };
     assertRequestApplies(manifest, !!opts.targetDatabaseUrl, !!storageTarget);
+    // 这次运行会不会碰 Storage(回传到目标,或下载到本地)。只有会碰时,空目标门才该
+    // 提示"库已恢复、只重试 Storage";skipStorage 的纯数据库运行(托管恢复)不该看到这句。
+    const alsoRestoringStorage = !!manifest.storage && !opts.skipStorage;
     // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
     if (opts.dryRun) {
         log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
-        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget);
+        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget, alsoRestoringStorage);
         result.dryRun = true;
         return result;
     }
@@ -408,7 +421,7 @@ export async function runRestore(config, opts) {
                     "at a fresh Supabase project.");
             }
             log.step("Checking target is empty…");
-            await assertEmptyTarget(targetUrl, manifest.database.schemas);
+            await assertEmptyTarget(targetUrl, manifest.database.schemas, alsoRestoringStorage);
             // 版本预检不只属于 dry-run:跳过 dry-run 直接执行时,目标比源旧照样会
             // 半途炸掉或部分恢复(评审第 8 轮)——写入前必须拦住
             const versionClient = await connectPg(targetUrl);

package/package.json

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