backupdrill 2.5.0 → 2.7.0

package/dist/restore.js

@@ -7,6 +7,7 @@ import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { parseManifest } from "./manifest.js";
 import { s3SnapshotStore } from "./snapshot-store.js";
 import { restoreDatabaseArtifact, installExtensions, projectRefOf, refFromStorageEndpoint, assertNoHostOverride, normalizeHost, } from "./restore-engine.js";
+import { checkExternalReferences, describe } from "./external-refs.js";
 import { verifyRestored } from "./drill.js";
 import { restoreStorage, planStorageRestore, } from "./storage-restore.js";
 import { connectPg } from "./supabase-ca.js";
@@ -175,32 +176,106 @@ export function nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage
  * schema 内零用户对象——关系、函数/过程、独立类型(enum/domain/range/composite)
  * 全部计入:只查关系时,"目标里只有函数"会放行,然后在 pre-data 中途撞冲突,
  * 留下半截目标(评审第 7 轮)。
+ * 扩展自带的对象不算(pg_depend deptype 'e'):转储不带扩展成员的定义,和恢复内容撞不上;
+ * 算进去的话,用户照我们的提示在控制台把扩展开进 public,或者上一次失败的恢复已经装好了扩展,
+ * 都会被这道门挡住(2.7.0)。扩展的**配置表和配置序列**(pg_extension.extconfig)除外:pg_dump 会把
+ * 它们的数据带上,恢复会往里插重复行,序列的 setval 还不随事务回滚(交叉审查复现),照旧算已有对象。
  */
 async function assertEmptyTarget(targetUrl, schemas, alsoRestoringStorage) {
+    const objectCount = await userObjectCount(targetUrl, schemas);
+    if (objectCount > 0) {
+        throw new Error(nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage));
+    }
+}
+/** 空目标门数的那些对象(见 assertEmptyTarget)有多少个。 */
+async function userObjectCount(targetUrl, schemas) {
     const client = await connectPg(targetUrl);
     try {
         const res = await client.query(`select
          (select count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace
-           where n.nspname = any($1::text[]) and c.relkind in ('r','p','m','v','S','f','c'))
+           where n.nspname = any($1::text[]) and c.relkind in ('r','p','m','v','S','f','c')
+             and not (exists (select 1 from pg_depend d where d.deptype = 'e'
+                                and ((d.classid = 'pg_class'::regclass and d.objid = c.oid)
+                                  -- 扩展建的复合类型(dblink 的 dblink_pkey_results)登记在类型上,不在关系上
+                                  or (d.classid = 'pg_type'::regclass and d.objid = c.reltype)))
+                      and not exists (select 1 from pg_extension e where c.oid = any(e.extconfig))))
        + (select count(*) from pg_proc p join pg_namespace n on n.oid = p.pronamespace
-           where n.nspname = any($1::text[]))
+           where n.nspname = any($1::text[])
+             and not exists (select 1 from pg_depend d where d.classid = 'pg_proc'::regclass
+                               and d.objid = p.oid and d.deptype = 'e'))
        + (select count(*) from pg_type t join pg_namespace n on n.oid = t.typnamespace
-           where n.nspname = any($1::text[]) and t.typtype in ('e','d','r'))
+           where n.nspname = any($1::text[]) and t.typtype in ('e','d','r')
+             and not exists (select 1 from pg_depend d where d.classid = 'pg_type'::regclass
+                               and d.objid = t.oid and d.deptype = 'e'))
          as n`, [schemas]);
-        const objectCount = Number(res.rows[0].n);
-        if (objectCount > 0) {
-            throw new Error(nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage));
-        }
+        return Number(res.rows[0].n);
     }
     finally {
         await client.end();
     }
 }
+/**
+ * 恢复失败之后目标是什么状态,给报错接的那句话。单事务失败通常就是回滚了,但"通常"不够:
+ * COMMIT 发出去、回复在路上丢了,服务端已经提交,pg_restore 照样报错(交叉审查第二轮复现)。
+ * 所以不凭推断说"已回滚",而是回头数一遍目标:空的才这么说。
+ */
+async function targetStateAfterFailure(targetUrl, schemas) {
+    let objectCount;
+    try {
+        objectCount = await userObjectCount(targetUrl, schemas);
+    }
+    catch (error) {
+        return (` The restore runs in one transaction, so a failed run normally leaves nothing behind, but checking ` +
+            `the target afterwards failed (${error.message}). Check it before running restore again.`);
+    }
+    if (objectCount === 0) {
+        return (" It ran in one transaction and was rolled back, so nothing from the snapshot is on the target and " +
+            "you can run restore again on the same project once the cause is fixed.");
+    }
+    return (` The restore runs in one transaction, yet schema(s) ${schemas.join(", ")} now hold ${objectCount} ` +
+        `object(s), so it may have committed before pg_restore lost its connection. Check the target before ` +
+        `doing anything else; restore won't write into it again while those objects are there.`);
+}
+/** README 里讲怎么先把 Auth 用户搬过去的那一节;报错和 dry-run 都指向它。 */
+const AUTH_USERS_GUIDE = "https://github.com/backupdrill/cli#tables-that-reference-authusers";
+function referencesHint(schemas) {
+    return (`This backup only holds schema(s) ${schemas.join(", ")}, so those rows have to be on the target before ` +
+        `the restore. Copy them over first (Supabase Auth users: ${AUTH_USERS_GUIDE}), then run restore again.`);
+}
+/**
+ * 外键检查结果打印成预检行;返回 blocker 句子(空 = 不拦)。dry-run 和正式执行共用同一份判定;
+ * 正式执行时问题不在这里打印,由调用方带着提示一起抛出,免得同一句话出现两遍。
+ */
+function logExternalReferences(check, schemas, printProblems) {
+    for (const note of check.unchecked) {
+        log.warn(`references outside the backup: ${note} — not checked; a failed restore is rolled back`);
+    }
+    if (check.problems.length) {
+        if (printProblems) {
+            for (const problem of check.problems)
+                log.error(`references outside the backup: ${problem}`);
+            log.warn(referencesHint(schemas));
+        }
+        return check.problems;
+    }
+    if (check.checked.length) {
+        for (const { fk, rows } of check.checked) {
+            log.ok(`references outside the backup: ${describe(fk)} — ${rows.toLocaleString("en-US")} row(s), ` +
+                `all found on the target`);
+        }
+    }
+    else if (!check.unchecked.length) {
+        log.ok(`references outside the backup: no foreign key points outside ${schemas.join(", ")}`);
+    }
+    return [];
+}
 /**
  * dry-run 只读预检(PRD §5.3.2):零写入,把正式执行会撞的墙全部提前撞一遍。
  * 逐项打印,任何 blocker 汇总后抛出(退出码非零 = "现在执行不会成功")。
+ * 有目标库时会把 dump 下载到本地临时目录读一遍(2.7.0 起):归档校验和、指向备份之外的外键,
+ * 这两类墙只有看了 dump 才撞得到。下载是读桶,目标库上仍然只有 select。
  */
-async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoRestoringStorage) {
+async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoRestoringStorage, reader) {
     const blockers = [];
     const db = manifest.database;
     const mb = (n) => (n / 1024 / 1024).toFixed(1);
@@ -238,6 +313,7 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoR
             blockers.push(error.message);
             log.error(`empty-target check: ${error.message}`);
         }
+        let toolReadsArchive = false;
         const client = await connectPg(targetUrl);
         try {
             // SHOW 的结果列名是 server_version;用 current_setting 显式起别名,
@@ -267,6 +343,7 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoR
                 log.error(`pg_restore tool: local v${toolMajor} cannot read a v${requiredMajor} archive`);
             }
             else {
+                toolReadsArchive = true;
                 log.ok(`pg_restore tool: local v${toolMajor} ≥ archive requirement v${requiredMajor}`);
             }
             const toolTargetBlocker = toolMajor !== null && Number.isFinite(targetMajor)
@@ -293,6 +370,12 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoR
         finally {
             await client.end();
         }
+        if (toolReadsArchive) {
+            blockers.push(...(await inspectDumpForTarget(manifest, targetUrl, reader)));
+        }
+        else {
+            log.warn("dump not inspected (archive checksum, references outside the backup) — needs a working pg_restore");
+        }
     }
     else {
         log.warn("no target database URL — database restore would be skipped");
@@ -320,6 +403,73 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoR
     }
     log.ok("dry run passed — nothing was written; re-run with --confirm-target to execute");
 }
+/**
+ * 单事务恢复特有的失败:每张表连同它的索引、序列、TOAST 表在提交前都占着一个锁槽。槽数 =
+ * max_locks_per_transaction × (max_connections + …),Supabase 最小规格(max_connections 60)实测
+ * 900 张表能过、1200 张表报 out of shared memory(2026-10-23,PG 17)。分区多的库会撞上。
+ * Supabase 只能用 CLI 调这个参数(会重启数据库),照官方文档的命令给出来。
+ */
+export function restoreFailureAdvice(failure) {
+    if (!/max_locks_per_transaction/.test(failure))
+        return "";
+    return (" The target ran out of lock slots: a single-transaction restore holds a lock on every table, index " +
+        "and sequence until it commits. Raise max_locks_per_transaction on the target and retry. On Supabase " +
+        "that takes the Supabase CLI and restarts the database: supabase postgres-config update " +
+        "--config max_locks_per_transaction=256 --project-ref <target-ref> --experimental");
+}
+/** dry-run 的读 dump 部分:下载到临时目录,对校验和,查指向备份之外的外键。返回 blocker。 */
+async function inspectDumpForTarget(manifest, targetUrl, reader) {
+    // 正式恢复先装扩展再查外键;dry-run 不装,被引用的表可能要等扩展装上才有
+    const installed = await installedExtensions(targetUrl);
+    const pendingExtensions = (manifest.database.extensions ?? [])
+        .filter((ext) => !installed.has(ext.name))
+        .map((ext) => ext.name);
+    const workdir = await mkdtemp(join(tmpdir(), "backupdrill-dryrun-"));
+    try {
+        log.step("Downloading dump to inspect it (read-only)…");
+        const dumpPath = join(workdir, "dump.pgcustom");
+        let sha256;
+        try {
+            ({ sha256 } = await reader.downloadDump(manifest, dumpPath));
+        }
+        catch (error) {
+            log.error(`dump download: ${error.message}`);
+            return [`dump download failed: ${error.message}`];
+        }
+        if (sha256 !== manifest.dump.sha256) {
+            log.error(`archive integrity: sha256 ${sha256.slice(0, 12)}… does not match manifest ${manifest.dump.sha256.slice(0, 12)}…`);
+            return ["archive checksum does not match the manifest"];
+        }
+        log.ok(`archive integrity: sha256 matches (${sha256.slice(0, 12)}…)`);
+        try {
+            const check = await checkExternalReferences({
+                dumpPath,
+                dumpedSchemas: manifest.database.schemas,
+                targetUrl,
+                pendingExtensions,
+            });
+            return logExternalReferences(check, manifest.database.schemas, true);
+        }
+        catch (error) {
+            log.error(`references outside the backup: could not read the dump — ${error.message}`);
+            return [`could not read the dump: ${error.message}`];
+        }
+    }
+    finally {
+        await rm(workdir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** 目标上已经装了哪些扩展。 */
+async function installedExtensions(targetUrl) {
+    const client = await connectPg(targetUrl);
+    try {
+        const res = await client.query("select extname from pg_extension");
+        return new Set(res.rows.map((row) => row.extname));
+    }
+    finally {
+        await client.end();
+    }
+}
 /**
  * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
  * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),
@@ -396,7 +546,7 @@ export async function runRestore(config, opts) {
     // 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, alsoRestoringStorage);
+        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget, alsoRestoringStorage, reader);
         result.dryRun = true;
         return result;
     }
@@ -472,22 +622,77 @@ export async function runRestore(config, opts) {
                 throw new Error(`archive integrity check failed: downloaded sha256 ${sha256.slice(0, 12)}… ` +
                     `does not match manifest ${manifest.dump.sha256.slice(0, 12)}… — refusing to restore a corrupted dump`);
             }
-            // 扩展预装:沙箱装不上只能记录(环境局限),真实目标装不上必须阻断——
-            // 用户在 dashboard 一键可开,恢复残缺副本则要人工收拾(引擎头注的裁决分工)
+            // 指向备份之外的外键(典型:profiles.id → auth.users),目标上缺被引用的行,恢复必然失败。
+            // 和 dry-run 同一份检查,在往目标写任何东西(连扩展都还没装)之前拦下,报错直接说缺什么、去哪补。
+            // 被引用的表也可能是待装的扩展建的:这种先记下,装完扩展再查一遍。
+            // (先装扩展再查的话,查不过时扩展已经留在目标上,带配置表的扩展会让修好之后的重跑被空目标门拦下)
             const extensions = manifest.database.extensions ?? [];
+            const installed = extensions.length ? await installedExtensions(targetUrl) : new Set();
+            const pendingExtensions = extensions.filter((ext) => !installed.has(ext.name)).map((ext) => ext.name);
+            const checkReferences = async (pending, opts) => {
+                log.step("Checking foreign keys that point outside the backup…");
+                const references = await checkExternalReferences({
+                    dumpPath,
+                    dumpedSchemas: manifest.database.schemas,
+                    targetUrl,
+                    pendingExtensions: pending,
+                    inTransaction: opts.inTransaction,
+                });
+                const referenceProblems = logExternalReferences(references, manifest.database.schemas, false);
+                if (referenceProblems.length && opts.final) {
+                    throw new Error(`the restore would fail on foreign keys, so nothing from the snapshot was written:\n  - ` +
+                        `${referenceProblems.join("\n  - ")}\n${referencesHint(manifest.database.schemas)}`);
+                }
+                return references;
+            };
+            // 还有扩展没装时,第一遍查出的问题(缺行、缺列、缺唯一索引)先不下结论:扩展装上可能补上它们
+            // (交叉审查复现过往已有表里写种子数据、建唯一索引的扩展)。交给下面"装扩展 + 复查"的事务去定,
+            // 复查不过照样拦、连扩展一起回滚。
+            // dry-run 装不了扩展,这些照旧报成 blocker:新建的 Supabase 项目通常还没装源库用过的扩展,
+            // 要是 dry-run 也先不下结论,最常见的"auth.users 是空的"就只剩一条警告了。代价是那种往别人的表里
+            // 补数据的扩展,dry-run 会比正式恢复更严
+            const firstCheck = await checkReferences(pendingExtensions, { final: pendingExtensions.length === 0 });
+            // 扩展预装:沙箱装不上只能记录(环境局限),真实目标装不上必须阻断——
+            // 用户在 dashboard 一键可开,恢复残缺副本则要人工收拾(引擎头注的裁决分工)。
+            // 有外键要等扩展装上才查得了时,装扩展和复查放在同一个事务里,复查过了才提交:复查不过就连扩展
+            // 一起回滚,目标原样不动(否则带配置表的扩展留下来,修好之后的重跑会被空目标门拦下,交叉审查复现)。
+            // 正式恢复(pg_restore)失败时装上的扩展留着:下一次运行照样要它们,空目标门也不数扩展自带的对象
+            // (配置表除外)。曾经在失败后删掉"本次新装的"扩展,交叉审查复现了它会误删别的连接同时装上的扩展。
             if (extensions.length) {
                 log.step(`Installing ${extensions.length} extension(s) on target…`);
-                const unavailable = await installExtensions(targetUrl, extensions);
-                if (unavailable.length) {
-                    throw new Error(`target cannot install extension(s): ${unavailable.join(", ")} — enable them in ` +
-                        `the Supabase dashboard (Database → Extensions) and retry.`);
+                const unavailableMessage = (unavailable) => `target cannot install extension(s): ${unavailable.join(", ")} — enable them in ` +
+                    `the Supabase dashboard (Database → Extensions) and retry.`;
+                if (firstCheck.waitingForExtensions || firstCheck.problems.length) {
+                    const client = await connectPg(targetUrl);
+                    try {
+                        await client.query("begin");
+                        const unavailable = await installExtensions(targetUrl, extensions, client);
+                        if (unavailable.length)
+                            throw new Error(unavailableMessage(unavailable));
+                        await checkReferences([], { inTransaction: client, final: true });
+                        await client.query("commit");
+                    }
+                    catch (error) {
+                        await client.query("rollback").catch(() => { });
+                        throw error;
+                    }
+                    finally {
+                        await client.end();
+                    }
+                }
+                else {
+                    const unavailable = await installExtensions(targetUrl, extensions);
+                    if (unavailable.length)
+                        throw new Error(unavailableMessage(unavailable));
                 }
             }
             log.step("Restoring database into target…");
             const engine = await restoreDatabaseArtifact({ dumpPath, connString: targetUrl, target: "supabase" });
             if (!engine.ok) {
                 const failures = [...engine.preData.failures, ...engine.postData.failures];
-                throw new Error(`database restore failed: ${failures.join(" | ")}`);
+                throw new Error(`database restore failed: ${failures.join(" | ")}.` +
+                    (await targetStateAfterFailure(targetUrl, manifest.database.schemas)) +
+                    restoreFailureAdvice(failures.join(" ")));
             }
             result.restoredToDatabase = true;
             // 与演练同一套表级验证:两条路径对同一快照必须同一结论(PRD §5.2 验收)

package/dist/snapshots.d.ts

@@ -2,6 +2,11 @@ import { S3Client } from "@aws-sdk/client-s3";
 import { type BackupConfig } from "./config.js";
 /** 读备份桶(用户自己的桶)的 S3 客户端。drill/restore 共用。 */
 export declare function targetClient(config: BackupConfig): S3Client;
+/**
+ * 列出 root(带尾斜杠)下的全部快照目录,返回带尾斜杠的前缀,未排序。只看 CommonPrefixes,
+ * root 下直接放的对象不算快照。
+ */
+export declare function listSnapshotPrefixes(s3: S3Client, bucket: string, root: string, abortSignal?: AbortSignal): Promise<string[]>;
 /** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */
 export declare function resolveSnapshot(s3: S3Client, config: BackupConfig, explicit?: string): Promise<string>;
 export declare function getObjectText(s3: S3Client, bucket: string, key: string): Promise<string>;

package/dist/snapshots.js

@@ -18,27 +18,35 @@ export function targetClient(config) {
         },
     });
 }
-/** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */
-export async function resolveSnapshot(s3, config, explicit) {
-    const storage = requireBucket(config);
-    const root = `${storage.prefix}/${config.projectName}/`;
-    if (explicit)
-        return `${root}${explicit}/`;
+/**
+ * 列出 root(带尾斜杠)下的全部快照目录,返回带尾斜杠的前缀,未排序。只看 CommonPrefixes,
+ * root 下直接放的对象不算快照。
+ */
+export async function listSnapshotPrefixes(s3, bucket, root, abortSignal) {
     const prefixes = [];
     let token;
     do {
         const res = await s3.send(new ListObjectsV2Command({
-            Bucket: storage.bucket,
+            Bucket: bucket,
             Prefix: root,
             Delimiter: "/",
             ContinuationToken: token,
-        }));
+        }), { abortSignal });
         for (const cp of res.CommonPrefixes ?? []) {
             if (cp.Prefix)
                 prefixes.push(cp.Prefix);
         }
         token = res.IsTruncated ? res.NextContinuationToken : undefined;
     } while (token);
+    return prefixes;
+}
+/** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */
+export async function resolveSnapshot(s3, config, explicit) {
+    const storage = requireBucket(config);
+    const root = `${storage.prefix}/${config.projectName}/`;
+    if (explicit)
+        return `${root}${explicit}/`;
+    const prefixes = await listSnapshotPrefixes(s3, storage.bucket, root);
     if (!prefixes.length) {
         throw new Error(`No snapshots found under s3://${storage.bucket}/${root}. Run a backup first.`);
     }

package/package.json

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

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

@@ -8,7 +8,7 @@
 #
 # REQUIRED SECRETS (database backup)
 #   BACKUPDRILL_DATABASE_URL          Supabase Session Pooler connection string
-#                                     (Project Settings → Database → Session pooler).
+#                                     (dashboard: Connect → Session pooler).
 #                                     The default postgres user works as-is; a
 #                                     read-only role usually fails under RLS —
 #                                     see the README's connection-string section.