backupdrill 2.1.3 → 2.1.4

package/dist/backup.js

@@ -11,7 +11,8 @@ import { renderRecoveryDoc } from "./recovery-doc.js";
 import { projectRefOf, refFromStorageEndpoint, assertNoHostOverride } from "./restore-engine.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
-import { dumpUrlFor, connectPg } from "./supabase-ca.js";
+import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
+import { libpqChildEnv, urlSslModeOf } from "./restore-engine.js";
 const execFileAsync = promisify(execFile);
 function majorOf(serverVersionNum) {
     // server_version_num: 150004 → 15,  170002 → 17
@@ -111,7 +112,15 @@ async function dumpToS3(config, s3, key, pgDumpBin) {
         ...schemaArgs,
         "--dbname",
         dumpDbUrl,
-    ], { stdio: ["ignore", "pipe", "pipe"] });
+    ], 
+    // 环境剔除改写目标/身份的 PG* 变量:pg_dump 只认 --dbname 里的 URL(TLS 策略等保留)
+    {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: libpqChildEnv({}, process.env, {
+            supabaseHost: isSupabaseHost(config.databaseUrl),
+            urlSslMode: urlSslModeOf(dumpDbUrl),
+        }),
+    });
     let stderr = "";
     dump.stderr.on("data", (d) => {
         stderr += d.toString();

package/dist/lib.d.ts

@@ -1,8 +1,8 @@
 export { runBackup } from "./backup.js";
-export { SUPABASE_ROOT_CA, pgConnectOptions } from "./supabase-ca.js";
+export { SUPABASE_ROOT_CA, pgConnectOptions, PG_CLIENT_OPTIONS, normalizeConnectionTarget } from "./supabase-ca.js";
 export { runDrill, drillDump } from "./drill.js";
 export { runRestore } from "./restore.js";
-export { projectRefOf, assertNoHostOverride } from "./restore-engine.js";
+export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
 export { loadConfig } from "./config.js";

package/dist/lib.js

@@ -3,11 +3,11 @@
 export { runBackup } from "./backup.js";
 // verify-full:只导出**原子** API。刻意不导出裸 SUPABASE_SSL —— 它一旦和 connectionString
 // 搭配使用,URL 里的 sslmode=disable 又会把它覆盖掉,等于把这次修掉的绕过再放回去。
-export { SUPABASE_ROOT_CA, pgConnectOptions } from "./supabase-ca.js";
+export { SUPABASE_ROOT_CA, pgConnectOptions, PG_CLIENT_OPTIONS, normalizeConnectionTarget } from "./supabase-ca.js";
 export { runDrill, drillDump } from "./drill.js";
 export { runRestore } from "./restore.js";
 // 身份判定三件套对外导出:托管 worker 用它们与 app 侧 shared 的副本做同规则回归(交叉审查)
-export { projectRefOf, assertNoHostOverride } from "./restore-engine.js";
+export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
 export { loadConfig } from "./config.js";

package/dist/restore-engine.d.ts

@@ -3,6 +3,14 @@ export type RestoreTargetKind = "sandbox" | "supabase";
 /** 主机名规范化:先按驱动语义百分号解码(pg-connection-string / libpq 都会解码主机名,
  * `supabase%2Ecom` 在驱动眼里就是 supabase.com),再剥掉合法的 DNS 根点(db.x.supabase.co. ≡
  * db.x.supabase.co)。身份比较不规范化 = 一个尾点或一个 %2E 就能绕过同源阻断(交叉审查)。 */
+/**
+ * 连接串任何位置解码后出现 NUL(或原文里的 %00)都视为启动包字段注入:驱动把 NUL 当字段分隔符,
+ * 后面的内容(user=… / options=reference=…)会成为额外的启动参数,连接目标与身份判定脱节。
+ * 合法连接串不存在 NUL,整串一刀切,不再逐字段追(交叉审查:query 值里的 NUL 同样能注入)。
+ */
+export declare function containsNul(connString: string): boolean;
+/** Supavisor 集群别名语法:用户名里出现字面量小写 `.cluster.`(handler_helpers.ex),之后全是别名。 */
+export declare function isClusterAliasUsername(username: string): boolean;
 export declare function normalizeHost(hostname: string): string;
 /**
  * 从连接串提取 Supabase 项目 ref(纯函数):直连主机 `db.<ref>.supabase.co` 或
@@ -26,7 +34,23 @@ export interface EngineResult {
     postData: ClassifiedPass;
     ok: boolean;
 }
-export declare function spawnPgRestore(bin: string, args: string[], extraEnv?: NodeJS.ProcessEnv): Promise<{
+/**
+ * libpq 子进程(pg_dump / pg_restore)的环境。`supabaseHost` 为真时再剔除 PGOPTIONS:Supavisor 会从
+ * options 里读租户覆盖(reference=…),而 Node 客户端对 Supabase 主机已显式钉死 options;非 Supabase
+ * 主机两边都尊重用户的 PGOPTIONS——两个客户端在任何情况下看到的都是同一份连接语义。
+ */
+export declare function libpqChildEnv(extraEnv?: NodeJS.ProcessEnv, base?: NodeJS.ProcessEnv, opts?: {
+    supabaseHost: boolean;
+    urlSslMode?: string | null;
+}): NodeJS.ProcessEnv;
+/** 见 libpqChildEnv:一个绝不存在的根证书路径 = 让 libpq 的 require 既不验证也不去找默认 root.crt。 */
+export declare const NO_VERIFY_ROOTCERT_SENTINEL = "/nonexistent/backupdrill-no-verify-root.crt";
+/** 连接串 query 里的 sslmode(驱动语义:URL 优先于环境变量);解析不了或没写 → null。 */
+export declare function urlSslModeOf(connString: string): string | null;
+export declare function spawnPgRestore(bin: string, args: string[], extraEnv?: NodeJS.ProcessEnv, opts?: {
+    supabaseHost: boolean;
+    urlSslMode?: string | null;
+}): Promise<{
     code: number | null;
     stderr: string;
 }>;

package/dist/restore-engine.js

@@ -10,10 +10,29 @@
 //     pre-data 阶段的 schema "already exists" 是两类目标共同的预期冲突。
 import { spawn } from "node:child_process";
 import { resolvePgRestoreBin } from "./pgbin.js";
-import { dumpUrlFor, connectPg } from "./supabase-ca.js";
+import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
 /** 主机名规范化:先按驱动语义百分号解码(pg-connection-string / libpq 都会解码主机名,
  * `supabase%2Ecom` 在驱动眼里就是 supabase.com),再剥掉合法的 DNS 根点(db.x.supabase.co. ≡
  * db.x.supabase.co)。身份比较不规范化 = 一个尾点或一个 %2E 就能绕过同源阻断(交叉审查)。 */
+/**
+ * 连接串任何位置解码后出现 NUL(或原文里的 %00)都视为启动包字段注入:驱动把 NUL 当字段分隔符,
+ * 后面的内容(user=… / options=reference=…)会成为额外的启动参数,连接目标与身份判定脱节。
+ * 合法连接串不存在 NUL,整串一刀切,不再逐字段追(交叉审查:query 值里的 NUL 同样能注入)。
+ */
+export function containsNul(connString) {
+    if (/%00/i.test(connString))
+        return true;
+    try {
+        return decodeURIComponent(connString).includes("\0");
+    }
+    catch {
+        return connString.includes("\0");
+    }
+}
+/** Supavisor 集群别名语法:用户名里出现字面量小写 `.cluster.`(handler_helpers.ex),之后全是别名。 */
+export function isClusterAliasUsername(username) {
+    return username.includes(".cluster.");
+}
 export function normalizeHost(hostname) {
     let decoded = hostname;
     try {
@@ -33,6 +52,8 @@ export function normalizeHost(hostname) {
  * 与恢复端(同源阻断)共用同一个身份判定。非 Supabase 形态返回 null。
  */
 export function projectRefOf(connString) {
+    if (containsNul(connString))
+        return null;
     try {
         const url = new URL(connString);
         const direct = normalizeHost(url.hostname).match(/^db\.([a-z0-9]{16,})\.supabase\.co$/);
@@ -44,7 +65,9 @@ export function projectRefOf(connString) {
         // 解码后含 NUL 一律不认:启动包用 NUL 分隔字段,`postgres%00options%00reference=…%00x.<ref>`
         // 在驱动/Supavisor 眼里是 user=postgres 外加一个 options 字段,身份判定看到的 ref 是假的(交叉审查)
         const username = decodeURIComponent(url.username);
-        if (username.includes("\0"))
+        // `<user>.cluster.<alias>` 是 Supavisor 的保留语法(只认小写 `.cluster.`,别名可含点):
+        // 别名经成员关系解析到真正的项目,不是 ref,认不出就不猜;连接本身由 assertNoHostOverride 拒绝
+        if (isClusterAliasUsername(username))
             return null;
         const pooled = username.match(/^[\s\S]+\.([a-z0-9]{16,})$/);
         if (pooled && /\.pooler\.supabase\.com$/.test(normalizeHost(url.hostname)))
@@ -65,11 +88,80 @@ export function refFromStorageEndpoint(endpoint) {
         return null;
     }
 }
-export function spawnPgRestore(bin, args, extraEnv = {}) {
+/**
+ * libpq 环境变量里会改写**连接到哪里、以谁的身份**的那些:剔除它们,子进程才只认 --dbname 里的
+ * URL。TLS 策略(PGSSLMODE / PGSSLROOTCERT…)、超时、编码、应用名这类**不改目标**的变量保留——
+ * 外部 Postgres 用户常靠 PGSSLMODE=require 上 TLS,一刀切剔除等于把他们降级到 prefer(交叉审查)。
+ * Supabase 主机的 TLS 由 dumpUrlFor 直接写进 URL(verify-full + 打包 CA),不依赖环境。
+ * 密码来源保留:URL 不带密码时 node-postgres 同样读 PGPASSWORD,也经 pgpass 模块读 PGPASSFILE,
+ * 两个客户端才对得上;URL 带密码时 credentialSafeDbArgs 会显式覆盖。
+ * 服务文件三件套(PGSERVICE / PGSERVICEFILE / PGSYSCONFDIR)剔除:pg_service.conf 能整段改写
+ * host/options,是 libpq 独有的旁路;URL 里的 ?service= 也在 assertNoHostOverride 拒绝。
+ */
+const LIBPQ_TARGET_ENV = new Set([
+    "PGHOST",
+    "PGHOSTADDR",
+    "PGPORT",
+    "PGDATABASE",
+    "PGUSER",
+    "PGSERVICE",
+    "PGSERVICEFILE",
+    "PGSYSCONFDIR",
+    "PGTARGETSESSIONATTRS",
+]);
+/**
+ * libpq 子进程(pg_dump / pg_restore)的环境。`supabaseHost` 为真时再剔除 PGOPTIONS:Supavisor 会从
+ * options 里读租户覆盖(reference=…),而 Node 客户端对 Supabase 主机已显式钉死 options;非 Supabase
+ * 主机两边都尊重用户的 PGOPTIONS——两个客户端在任何情况下看到的都是同一份连接语义。
+ */
+export function libpqChildEnv(extraEnv = {}, base = process.env, opts = { supabaseHost: false }) {
+    const env = {};
+    // node-postgres 独有的 sslmode 值:no-verify = 加密但**不验证书**。libpq 里最接近的是 require,
+    // 但 require 一旦找到根证书就升级成 verify-ca(显式 sslrootcert、sslrootcert=system,或默认
+    // 发现 ~/.postgresql/root.crt 都算),遇到 sslrootcert=system 还直接拒连。翻译时:去掉 CRL 变量,
+    // 并把 PGSSLROOTCERT 指向一个不存在的路径——libpq 对显式路径 stat 失败时在 require 模式下
+    // 跳过验证、且不再去找默认的 root.crt,子进程才真的是"加密、不验",与 Node 侧一致(交叉审查)。
+    // URL 里自带 sslmode 时它压过环境变量(两个客户端都如此),这时不做 no-verify 翻译——否则
+    // 哨兵根证书会让 verify-full 因"证书文件不存在"而拒连(交叉审查)
+    const noVerify = base.PGSSLMODE === "no-verify" && !opts.urlSslMode;
+    for (const [key, value] of Object.entries(base)) {
+        if (LIBPQ_TARGET_ENV.has(key))
+            continue;
+        if (opts.supabaseHost && key === "PGOPTIONS")
+            continue;
+        if (noVerify) {
+            if (key === "PGSSLMODE") {
+                env[key] = "require";
+                continue;
+            }
+            if (key === "PGSSLROOTCERT" || key === "PGSSLCRL" || key === "PGSSLCRLDIR")
+                continue;
+        }
+        env[key] = value;
+    }
+    if (noVerify)
+        env.PGSSLROOTCERT = NO_VERIFY_ROOTCERT_SENTINEL;
+    return { ...env, ...extraEnv };
+}
+/** 见 libpqChildEnv:一个绝不存在的根证书路径 = 让 libpq 的 require 既不验证也不去找默认 root.crt。 */
+export const NO_VERIFY_ROOTCERT_SENTINEL = "/nonexistent/backupdrill-no-verify-root.crt";
+/** 连接串 query 里的 sslmode(驱动语义:URL 优先于环境变量);解析不了或没写 → null。 */
+export function urlSslModeOf(connString) {
+    try {
+        // 重复参数两个驱动都取最后一个;最后一个为空视同没写(pg 会回退环境变量)
+        const all = new URL(connString).searchParams.getAll("sslmode");
+        const last = all.length ? all[all.length - 1] : "";
+        return last === "" ? null : last;
+    }
+    catch {
+        return null;
+    }
+}
+export function spawnPgRestore(bin, args, extraEnv = {}, opts = { supabaseHost: false }) {
     return new Promise((resolve, reject) => {
         const proc = spawn(bin, args, {
             stdio: ["ignore", "ignore", "pipe"],
-            env: { ...process.env, ...extraEnv },
+            env: libpqChildEnv(extraEnv, process.env, opts),
         });
         let stderr = "";
         proc.stderr.on("data", (d) => (stderr += d.toString()));
@@ -257,41 +349,57 @@ export function credentialSafeDbArgs(connString) {
  * 目标)的 options 没有租户语义,照常放行。
  */
 export function assertNoHostOverride(connString) {
+    // 整串 NUL 检查放在 URL 解析之前:query 值、路径、任何位置的 NUL 都是启动包注入,
+    // libpq 稍后也会拒,但驱动侧先发出的启动包已经到了 pooler——在任何连接之前就拒
+    if (containsNul(connString)) {
+        throw new Error("connection string contains a NUL byte — use a plain connection string.");
+    }
+    // 解析不了的连接串直接拒:曾经"放行让 pg 自己报错",但 pg 的解析器比 WHATWG URL 宽
+    // (`postgresql://user@/db?host=…` 这类串 pg 接受、这里解析失败),放行 = 身份判定为空却照样连接
+    // (交叉审查)。校验逻辑放在 try 外面——曾按文案里有没有 "override" 决定重抛,新理由一措辞不同就被吞。
+    let url;
     try {
-        const url = new URL(connString);
-        // 用户名/密码/主机里解码后出现 NUL:启动包以 NUL 分隔字段,后面的内容会被当成额外的启动参数
-        // (options=reference=… 之类),连接目标与身份判定脱节。libpq 稍后也会拒,但驱动侧先发出的
-        // 启动包已经到了 pooler——在任何连接/身份判定之前就拒(交叉审查)。
-        for (const [label, raw] of [["username", url.username], ["password", url.password], ["host", url.hostname]]) {
-            let decoded = raw;
-            try {
-                decoded = decodeURIComponent(raw);
-            }
-            catch {
-                // 非法编码:驱动同样解不开,按原样看
-            }
-            if (decoded.includes("\0")) {
-                throw new Error(`connection string ${label} contains a NUL byte override — use a plain connection string.`);
-            }
+        url = new URL(connString);
+    }
+    catch {
+        throw new Error("connection string could not be parsed as a URL — use a plain postgresql://user:password@host:port/database string.");
+    }
+    // 空 authority(postgresql:///db):主机只能来自环境变量或 ?host=,Node 与 libpq 子进程各自
+    // 回退到不同默认值,身份判定也无从谈起——必须显式写主机(交叉审查)
+    if (!url.hostname) {
+        throw new Error("connection string has no host — use a plain postgresql://user:password@host:port/database string.");
+    }
+    const params = url.searchParams;
+    const isSupabasePooler = /\.pooler\.supabase\.com$/.test(normalizeHost(url.hostname));
+    let username;
+    try {
+        username = decodeURIComponent(url.username);
+    }
+    catch {
+        // 非法百分号编码不能按原样放行:pg 会做部分解码(%75 → u,%GG 保留),这里看到的字符串
+        // 与驱动实际发出的用户名不同,别名/身份判定都可能被绕过(交叉审查)。解不开就拒。
+        throw new Error("connection string username has invalid percent-encoding — use a plain connection string.");
+    }
+    // 集群别名连接:我们解析不出它真正路由到哪个项目,身份判定为空 → 同源/目标一致性都没法保证,
+    // 在任何 I/O 之前拒绝,而不是让"null 身份"静默放行
+    if (isSupabasePooler && isClusterAliasUsername(username)) {
+        throw new Error("connection string uses Supavisor's <user>.cluster.<alias> syntax — BackupDrill cannot resolve which project " +
+            "the alias routes to, so identity checks cannot run. Use the project's own pooler string (<user>.<project-ref>).");
+    }
+    for (const key of params.keys()) {
+        // dbname 也算目标覆盖:libpq 让 ?dbname= 压过路径里的库名,node-postgres 却不认这个键——
+        // 预检看的是一个库、pg_restore 写的是另一个。service/servicefile 让 libpq 从 pg_service.conf
+        // 整段加载 host/options(含租户覆盖),node-postgres 不认——同样拒绝(交叉审查)。
+        // URLSearchParams 已把键解码,%64bname 这类编码形态同样命中。
+        if (/^(host|hostaddr|user|dbname|service|servicefile)$/i.test(key)) {
+            throw new Error(`connection string carries a ?${key}= override — the effective server/identity would ` +
+                `differ from the URL authority that identity checks inspect. Use a plain connection string.`);
         }
-        const params = url.searchParams;
-        const isSupabasePooler = /\.pooler\.supabase\.com$/.test(normalizeHost(url.hostname));
-        for (const key of params.keys()) {
-            if (/^(host|hostaddr|user)$/i.test(key)) {
-                throw new Error(`connection string carries a ?${key}= override — the effective server/identity would ` +
-                    `differ from the URL authority that identity checks inspect. Use a plain connection string.`);
-            }
-            if (isSupabasePooler && /^options$/i.test(key)) {
-                throw new Error("connection string carries ?options= on a Supabase pooler host — the pooler reads a tenant override " +
-                    "(reference=…) from it, so identity checks could not trust the username. Remove ?options= entirely.");
-            }
+        if (isSupabasePooler && /^options$/i.test(key)) {
+            throw new Error("connection string carries ?options= on a Supabase pooler host — the pooler reads a tenant override " +
+                "(reference=…) from it, so identity checks could not trust the username. Remove ?options= entirely.");
         }
     }
-    catch (error) {
-        if (error.message.includes("override"))
-            throw error;
-        // URL 解析不了的连接串由 pg 自己报错,这里放行
-    }
 }
 export async function restoreDatabaseArtifact(opts) {
     const bin = resolvePgRestoreBin();
@@ -300,12 +408,13 @@ export async function restoreDatabaseArtifact(opts) {
     // 中间人可拿到连接与数据);沙箱/外部主机原样透传。先改写 SSL 再拆密码。
     const { url, env } = credentialSafeDbArgs(dumpUrlFor(opts.connString));
     const common = ["--no-owner", "--no-privileges", "--dbname", url, opts.dumpPath];
-    const first = await spawnPgRestore(bin, ["--section=pre-data", "--section=data", ...common], env);
+    const childOpts = { supabaseHost: isSupabaseHost(opts.connString), urlSslMode: urlSslModeOf(url) };
+    const first = await spawnPgRestore(bin, ["--section=pre-data", "--section=data", ...common], env, childOpts);
     const preData = finalizePass(first.code, first.stderr, classifyBlocks(first.stderr, SCHEMA_EXISTS_ERROR));
     if (preData.failures.length) {
         return { preData, postData: { expectedSkips: 0, failures: [] }, ok: false };
     }
-    const second = await spawnPgRestore(bin, ["--section=post-data", ...common], env);
+    const second = await spawnPgRestore(bin, ["--section=post-data", ...common], env, childOpts);
     const postData = finalizePass(second.code, second.stderr, classifyBlocks(second.stderr, opts.target === "sandbox" ? SANDBOX_MANAGED_ERROR : NEVER_MATCH));
     return { preData, postData, ok: postData.failures.length === 0 };
 }

package/dist/restore.js

@@ -322,6 +322,15 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
  * 否则下载到本地目录。这是 US-5 恢复向导的 CLI 形态。
  */
 export async function runRestore(config, opts) {
+    // 任何 I/O 之前先把源与目标的连接串过一遍覆盖/别名守卫:源串带集群别名或租户覆盖时
+    // 身份判定为空,同源阻断会失效——不能只查目标(交叉审查)。备份端 runBackup 对源做同样的事。
+    // 源守卫只在**有远端目标**时才需要:纯本地下载(无目标库、无目标 Storage)不写任何远端,
+    // 老快照的源配置哪怕不可考也应能下载出来(交叉审查)。
+    const hasRemoteTarget = Boolean(opts.targetDatabaseUrl || opts.targetSupabaseUrl);
+    if (hasRemoteTarget && config.databaseUrl !== NO_SOURCE_DATABASE)
+        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();
@@ -341,8 +350,6 @@ export async function runRestore(config, opts) {
             serviceRoleKey: opts.targetServiceRoleKey,
         }
         : null;
-    if (opts.targetDatabaseUrl)
-        assertNoHostOverride(opts.targetDatabaseUrl);
     // 同源阻断(统一收口):目标(库或 Storage)的 ref 命中任何源项目 ref → 拒绝。
     // 覆盖 storage-only 组合:目标 Storage = 备份读取源的项目时,upsert 会改写源。
     const sourceRefs = sourceProjectRefs(config, manifest);

package/dist/supabase-ca.d.ts

@@ -15,7 +15,19 @@ export declare function supabaseCaFile(): string;
  * ——libpq 里 URL 参数优先级高于环境变量,残留的 sslmode=require 会盖掉我们的 verify-full。
  */
 export declare function forceVerifyFull(databaseUrl: string, caPath: string): string;
+export declare function isSupabaseHost(databaseUrl: string): boolean;
 /** pg_dump 用:Supabase 主机才改写成 verify-full;其它原样透传。 */
+/**
+ * 把连接目标写死在连接串里:端口缺省 5432、库名缺省 postgres、并去掉**空的** options 参数。
+ * 为什么:node-pg 与 libpq 对"URL 里没写的字段"各自回退到环境变量(PGPORT / PGDATABASE /
+ * PGOPTIONS…)。子进程环境已剔除 PG*,而 Node 侧的预检客户端仍会读——两边可能连到不同的
+ * 库/端口,空目标检查看的是一个库、pg_restore 写的是另一个(交叉审查)。Node 客户端与
+ * pg_dump/pg_restore 都用规范化后的串,谁也不再依赖环境变量补字段。
+ * 空的 `?options=` 会让 pg 的 val() 回退读 PGOPTIONS,同样去掉;非空 options 是用户显式意图,
+ * 保留(pooler 主机上任何 options 已被 assertNoHostOverride 拒绝)。
+ * 解析不了的串原样返回:上游守卫(assertNoHostOverride / assertSafeDatabaseUrl)负责拒绝。
+ */
+export declare function normalizeConnectionTarget(databaseUrl: string): string;
 export declare function dumpUrlFor(databaseUrl: string): string;
 /**
  * node-pg 连接选项:把"剥离连接串里的 SSL 参数"与"套上打包 CA"做成**原子**的一步。
@@ -27,8 +39,18 @@ export declare function dumpUrlFor(databaseUrl: string): string;
  *
  * 非 Supabase 主机(本 CLI 不限制目标)原样返回:不剥、不套,尊重用户自己的 sslmode。
  */
+/**
+ * Supabase 主机的 pg Client 显式带 startup `options`。为什么:node-postgres 只在 config.options
+ * 为假值时才读环境变量 PGOPTIONS,而 Supavisor 会从 options 里解析 `reference=<ref>` 并让它优先于
+ * 用户名里的租户——继承的 PGOPTIONS 能把连接悄悄路由到别的项目(交叉审查)。给一个无害的真值就把
+ * 环境变量挡在门外(Supavisor 与直连 Postgres 都实测接受);顺带在 pg_stat_activity 里能认出是谁在连。
+ * 只对 Supabase 主机做:租户覆盖只存在于 Supavisor,而 PgBouncer 这类中间件默认拒绝陌生的启动参数
+ * (unsupported startup parameter: options),别给自带 Postgres 的用户制造回归。
+ */
+export declare const PG_CLIENT_OPTIONS = "-c application_name=backupdrill";
 export declare function pgConnectOptions(databaseUrl: string): {
     connectionString: string;
+    options?: string;
     ssl?: typeof SUPABASE_SSL;
 };
 /**

package/dist/supabase-ca.js

@@ -214,15 +214,126 @@ function effectiveHost(databaseUrl) {
     const host = (last !== "" ? last : decodedAuthority).toLowerCase().replace(/\.$/, "");
     return host || null;
 }
-function isSupabaseHost(databaseUrl) {
+export function isSupabaseHost(databaseUrl) {
     const host = effectiveHost(databaseUrl);
     return host !== null && SUPABASE_HOST.test(host);
 }
 /** pg_dump 用:Supabase 主机才改写成 verify-full;其它原样透传。 */
+/**
+ * 把连接目标写死在连接串里:端口缺省 5432、库名缺省 postgres、并去掉**空的** options 参数。
+ * 为什么:node-pg 与 libpq 对"URL 里没写的字段"各自回退到环境变量(PGPORT / PGDATABASE /
+ * PGOPTIONS…)。子进程环境已剔除 PG*,而 Node 侧的预检客户端仍会读——两边可能连到不同的
+ * 库/端口,空目标检查看的是一个库、pg_restore 写的是另一个(交叉审查)。Node 客户端与
+ * pg_dump/pg_restore 都用规范化后的串,谁也不再依赖环境变量补字段。
+ * 空的 `?options=` 会让 pg 的 val() 回退读 PGOPTIONS,同样去掉;非空 options 是用户显式意图,
+ * 保留(pooler 主机上任何 options 已被 assertNoHostOverride 拒绝)。
+ * 解析不了的串原样返回:上游守卫(assertNoHostOverride / assertSafeDatabaseUrl)负责拒绝。
+ */
+export function normalizeConnectionTarget(databaseUrl) {
+    let url;
+    try {
+        url = new URL(databaseUrl);
+    }
+    catch {
+        return databaseUrl;
+    }
+    // 空 authority 形态(postgresql:///db?host=…):URL 解析得到空主机,node-pg 却能接受——这类串由
+    // dumpUrlFor 的主机识别与 assertNoHostOverride 的 ?host= 拒绝各自处理,这里不碰、不猜
+    if (!url.hostname)
+        return databaseUrl;
+    if (!url.port)
+        url.port = "5432";
+    // 没有用户名就没有可钉死的身份与缺省库名(libpq 退回操作系统用户、node-postgres 退回 PGUSER/
+    // PGDATABASE 环境变量,两边立刻分叉):直接拒绝,连接串必须自带用户名
+    if (!url.username) {
+        throw new Error("connection string must include a user name (postgresql://user:password@host:port/database).");
+    }
+    // 库名缺省 = 用户名:这是 libpq 与 node-postgres 共同的语义(两者都在 dbname 缺失时回退到
+    // user),写死它只是不让环境变量 PGDATABASE 插进来,不改变既有连接串的目标(交叉审查:
+    // 曾错写成 postgres,会让 postgresql://app:pw@host 这类外部库串静默换库)。
+    // 路径里的百分号编码两个客户端解法不同:libpq 全部解码,node-postgres(pg-connection-string)
+    // 用 decodeURI——保留字(/ ? # : @ & = + $ , ;)的编码不解。所以缺省库名用**解码后的用户名**
+    // 写进路径,让 URL 只对需要的字符做编码,再逐一验证两种解法得到同一个库名;做不到就要求显式库名。
+    if (!url.pathname || url.pathname === "/") {
+        let user;
+        try {
+            user = decodeURIComponent(url.username);
+        }
+        catch {
+            throw new Error("connection string user name has invalid percent-encoding.");
+        }
+        const explicit = "connection string omits the database name and the user name cannot serve as the default — add /<database> after the host.";
+        // / 破坏路径结构,? # 会被编成保留字序列(两边解法分叉),% 本身有歧义,控制字符不进路径
+        if (/[/?#%\u0000-\u001f\u007f]/.test(user) || user === "")
+            throw new Error(explicit);
+        url.pathname = `/${user}`;
+        const encoded = url.pathname.slice(1);
+        let libpqView;
+        let nodeView;
+        try {
+            libpqView = decodeURIComponent(encoded);
+            nodeView = decodeURI(encoded);
+        }
+        catch {
+            throw new Error(explicit);
+        }
+        if (libpqView !== user || nodeView !== user)
+            throw new Error(explicit);
+    }
+    // options 参数按"最后一个生效"的驱动语义处理(pg-connection-string 与 libpq 对重复参数都取最后
+    // 一个):最后一个 options 为空 → 整组 options 全部剔除(空值会让 pg 回退读 PGOPTIONS;只删空的
+    // 那份会让更早的非空 options 复活,改变语义——交叉审查);最后一个非空 → 原样保留整组。
+    // 按原文操作、不经 URLSearchParams 重新序列化,否则其它参数值里的 %20 会被改写成 +
+    // (pg 解成空格、libpq 按字面 + 处理,两边密码就对不上)。
+    if (url.search) {
+        // 空片段(?&x=1)与无 = 的裸键(?options&…)Node 能容忍、libpq 报 "missing key/value separator":
+        // 一律清掉,两边看到同一份 query。键按**大小写敏感**比对:驱动的键是大小写敏感的
+        // (OPTIONS 对 pg 是另一个键、对 libpq 是非法关键字),按不敏感归组会把合法的小写 options 一起删掉。
+        const pairs = url.search.slice(1).split("&").filter((pair) => pair !== "");
+        const keyOf = (pair) => {
+            const eq = pair.indexOf("=");
+            const rawKey = eq === -1 ? pair : pair.slice(0, eq);
+            try {
+                return decodeURIComponent(rawKey);
+            }
+            catch {
+                return rawKey; // 编码坏了按原文比对
+            }
+        };
+        const valueOf = (pair) => {
+            const eq = pair.indexOf("=");
+            return eq === -1 ? "" : pair.slice(eq + 1);
+        };
+        const optionPairs = pairs.filter((pair) => keyOf(pair) === "options");
+        const lastIsEmpty = optionPairs.length > 0 && valueOf(optionPairs[optionPairs.length - 1]) === "";
+        // 其它键的裸形态(?sslmode=disable&sslmode)两边语义对不上:Node 取最后一个(空 → 回退环境变量),
+        // libpq 直接报错;静默删掉会让更早的值(这里是 disable = 明文)复活。不猜,拒绝(交叉审查)。
+        const bareOther = pairs.find((pair) => !pair.includes("=") && keyOf(pair) !== "options");
+        if (bareOther !== undefined) {
+            throw new Error(`connection string parameter "${keyOf(bareOther)}" has no value — remove it or give it a value.`);
+        }
+        // 空的 sslmode(?sslmode=)两边对不上:libpq 报 invalid sslmode value,Node 回退环境变量——拒绝。
+        // 只管 sslmode:空 host= 等已有各自的既定处理(stripSslParams / forceVerifyFull 那套),不在这里动
+        // 两个驱动都取最后一个 sslmode:只有最后一个为空才算空(?sslmode=&sslmode=verify-full 是合法的)
+        const sslModePairs = pairs.filter((pair) => keyOf(pair) === "sslmode" && pair.includes("="));
+        if (sslModePairs.length > 0 && valueOf(sslModePairs[sslModePairs.length - 1]) === "") {
+            throw new Error('connection string parameter "sslmode" is empty — remove it or give it a value.');
+        }
+        const kept = pairs.filter((pair) => {
+            // options 组:最后一个为空/裸 → 整组删;否则只留带 = 的(裸的已被后面的值取代,libpq 会报错)
+            if (keyOf(pair) === "options")
+                return !lastIsEmpty && pair.includes("=");
+            return true;
+        });
+        url.search = kept.length ? `?${kept.join("&")}` : "";
+    }
+    return url.toString();
+}
 export function dumpUrlFor(databaseUrl) {
-    return isSupabaseHost(databaseUrl)
-        ? forceVerifyFull(databaseUrl, supabaseCaFile())
-        : databaseUrl;
+    const normalized = normalizeConnectionTarget(databaseUrl);
+    return isSupabaseHost(normalized)
+        ? forceVerifyFull(normalized, supabaseCaFile())
+        : normalized;
 }
 /**
  * node-pg 连接选项:把"剥离连接串里的 SSL 参数"与"套上打包 CA"做成**原子**的一步。
@@ -234,10 +345,21 @@ export function dumpUrlFor(databaseUrl) {
  *
  * 非 Supabase 主机(本 CLI 不限制目标)原样返回:不剥、不套,尊重用户自己的 sslmode。
  */
+/**
+ * Supabase 主机的 pg Client 显式带 startup `options`。为什么:node-postgres 只在 config.options
+ * 为假值时才读环境变量 PGOPTIONS,而 Supavisor 会从 options 里解析 `reference=<ref>` 并让它优先于
+ * 用户名里的租户——继承的 PGOPTIONS 能把连接悄悄路由到别的项目(交叉审查)。给一个无害的真值就把
+ * 环境变量挡在门外(Supavisor 与直连 Postgres 都实测接受);顺带在 pg_stat_activity 里能认出是谁在连。
+ * 只对 Supabase 主机做:租户覆盖只存在于 Supavisor,而 PgBouncer 这类中间件默认拒绝陌生的启动参数
+ * (unsupported startup parameter: options),别给自带 Postgres 的用户制造回归。
+ */
+export const PG_CLIENT_OPTIONS = "-c application_name=backupdrill";
 export function pgConnectOptions(databaseUrl) {
-    if (!isSupabaseHost(databaseUrl))
-        return { connectionString: databaseUrl };
-    return { connectionString: stripSslParams(databaseUrl), ssl: SUPABASE_SSL };
+    // 与 dumpUrlFor 同一份规范化:Node 客户端与 libpq 子进程看到的目标必须逐字段一致
+    const normalized = normalizeConnectionTarget(databaseUrl);
+    if (!isSupabaseHost(normalized))
+        return { connectionString: normalized };
+    return { connectionString: stripSslParams(normalized), options: PG_CLIENT_OPTIONS, ssl: SUPABASE_SSL };
 }
 /**
  * 给一个 pg Client 挂上 error 监听。**必须在 connect() 之前挂。**

package/package.json

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