backupdrill 2.5.0 → 2.7.0

package/dist/dump-sql.d.ts

@@ -0,0 +1,52 @@
+export interface QualifiedName {
+    schema: string;
+    name: string;
+}
+export declare function unquoteIdent(ident: string): string;
+export declare function formatQualified(name: QualifiedName): string;
+/** `pg_restore -f - -L <只含 SCHEMA 条目的清单>` 的输出 → 按出现顺序的 schema 名。 */
+export declare function parseCreateSchemas(sql: string): string[];
+export interface ForeignKeyDef {
+    constraint: string;
+    table: QualifiedName;
+    columns: string[];
+    references: QualifiedName;
+    referencedColumns: string[];
+    /**
+     * ADD CONSTRAINT 时会不会校验已有的行。NOT VALID(源库就没校验过)和 PG18 的 NOT ENFORCED
+     * 都不校验,恢复不会因为缺行而失败,所以不用查。
+     */
+    validatesRows: boolean;
+}
+/**
+ * pg_dump 的外键语句(dumpConstraint):
+ *   ALTER [FOREIGN ]TABLE [ONLY ]<表>\n    ADD CONSTRAINT <名> FOREIGN KEY (<列>) REFERENCES <表>(<列>)<选项>;
+ * 分区父表上的外键没有 ONLY。认不出的形态(如 PG18 的 PERIOD 时态外键)不返回,
+ * 调用方拿条目数对账,差多少就如实报多少条没检查。
+ */
+export declare function parseForeignKeys(sql: string): ForeignKeyDef[];
+/** pg_dump 的挂分区语句(dumpTableAttach):ALTER TABLE ONLY <父> ATTACH PARTITION <子> <边界>; */
+export declare function parsePartitionAttachments(sql: string): Array<{
+    parent: QualifiedName;
+    child: QualifiedName;
+}>;
+/**
+ * pg_dump 的建表语句(dumpTableSchema)里每列的类型,按表(schema\0name)→ 列 → 类型。
+ *   CREATE [UNLOGGED ]TABLE <表> (\n    <列> <类型>[ COLLATE …][ DEFAULT …][ NOT NULL],\n    CONSTRAINT …\n)…;
+ * 类型是 format_type 的输出,本身不含 COLLATE/DEFAULT/NOT NULL/GENERATED 这些词,读到它们为止。
+ * 带引号的列名可以跨行,所以按位置往下读,不按行切。
+ */
+export declare function parseTableColumns(sql: string): Map<string, Map<string, string>>;
+/**
+ * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
+ * 所以那一行中间是两个空格,返回空列表。
+ */
+export declare function parseCopyHeader(line: string): {
+    table: QualifiedName;
+    columns: string[];
+} | null;
+/**
+ * COPY 文本格式的一个字段 → 值(\N = NULL)。转义规则照 PostgreSQL 文档 "COPY / Text Format":
+ * \b \f \n \r \t \v \\,\ 加 1–3 位八进制,\x 加 1–2 位十六进制,其余 \c 就是 c 本身。
+ */
+export declare function decodeCopyField(field: string): string | null;

package/dist/dump-sql.js

@@ -0,0 +1,112 @@
+// 读 pg_restore 吐出来的 SQL(纯函数,可单测)。只认 pg_dump 自己的输出格式:
+// 名字一律由 fmtId / quote_identifier 生成——[a-z_][a-z0-9_]* 原样,其余加双引号、内嵌引号翻倍,
+// dump 头部把 search_path 设成空串,所以引用的表总是 schema.name 全限定。
+// 不是通用 SQL 解析器,也不需要是:认不出的语句由调用方如实报"没法检查",不猜。
+const QUOTED_IDENT = String.raw `"(?:[^"]|"")+"`;
+const IDENT = String.raw `(?:${QUOTED_IDENT}|[a-z_][a-z0-9_]*)`;
+const QUALIFIED = String.raw `(${IDENT})\.(${IDENT})`;
+const COLUMNS = String.raw `(${IDENT}(?:\s*,\s*${IDENT})*)`;
+export function unquoteIdent(ident) {
+    return ident.startsWith('"') ? ident.slice(1, -1).replace(/""/g, '"') : ident;
+}
+function splitColumns(list) {
+    return [...list.matchAll(new RegExp(IDENT, "g"))].map((match) => unquoteIdent(match[0]));
+}
+export function formatQualified(name) {
+    const show = (part) => (/^[a-z_][a-z0-9_]*$/.test(part) ? part : `"${part.replace(/"/g, '""')}"`);
+    return `${show(name.schema)}.${show(name.name)}`;
+}
+/** `pg_restore -f - -L <只含 SCHEMA 条目的清单>` 的输出 → 按出现顺序的 schema 名。 */
+export function parseCreateSchemas(sql) {
+    return [...sql.matchAll(new RegExp(String.raw `^CREATE SCHEMA (${IDENT});$`, "gm"))].map((match) => unquoteIdent(match[1]));
+}
+/**
+ * pg_dump 的外键语句(dumpConstraint):
+ *   ALTER [FOREIGN ]TABLE [ONLY ]<表>\n    ADD CONSTRAINT <名> FOREIGN KEY (<列>) REFERENCES <表>(<列>)<选项>;
+ * 分区父表上的外键没有 ONLY。认不出的形态(如 PG18 的 PERIOD 时态外键)不返回,
+ * 调用方拿条目数对账,差多少就如实报多少条没检查。
+ */
+export function parseForeignKeys(sql) {
+    const pattern = new RegExp(String.raw `^ALTER (?:FOREIGN )?TABLE (?:ONLY )?${QUALIFIED}\n {4}ADD CONSTRAINT (${IDENT}) ` +
+        String.raw `FOREIGN KEY \(${COLUMNS}\) REFERENCES ${QUALIFIED}\s*\(${COLUMNS}\)(.*);$`, "gm");
+    return [...sql.matchAll(pattern)].map((match) => {
+        // 选项里可能有带引号的列名(ON DELETE SET NULL ("x")),先去掉再找关键字
+        const options = match[8].replace(new RegExp(QUOTED_IDENT, "g"), "");
+        return {
+            constraint: unquoteIdent(match[3]),
+            table: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+            columns: splitColumns(match[4]),
+            references: { schema: unquoteIdent(match[5]), name: unquoteIdent(match[6]) },
+            referencedColumns: splitColumns(match[7]),
+            validatesRows: !/\bNOT (?:VALID|ENFORCED)\b/.test(options),
+        };
+    });
+}
+/** pg_dump 的挂分区语句(dumpTableAttach):ALTER TABLE ONLY <父> ATTACH PARTITION <子> <边界>; */
+export function parsePartitionAttachments(sql) {
+    const pattern = new RegExp(String.raw `^ALTER TABLE ONLY ${QUALIFIED} ATTACH PARTITION ${QUALIFIED} `, "gm");
+    return [...sql.matchAll(pattern)].map((match) => ({
+        parent: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+        child: { schema: unquoteIdent(match[3]), name: unquoteIdent(match[4]) },
+    }));
+}
+/**
+ * pg_dump 的建表语句(dumpTableSchema)里每列的类型,按表(schema\0name)→ 列 → 类型。
+ *   CREATE [UNLOGGED ]TABLE <表> (\n    <列> <类型>[ COLLATE …][ DEFAULT …][ NOT NULL],\n    CONSTRAINT …\n)…;
+ * 类型是 format_type 的输出,本身不含 COLLATE/DEFAULT/NOT NULL/GENERATED 这些词,读到它们为止。
+ * 带引号的列名可以跨行,所以按位置往下读,不按行切。
+ */
+export function parseTableColumns(sql) {
+    const tables = new Map();
+    const header = new RegExp(String.raw `^CREATE (?:UNLOGGED )?TABLE ${QUALIFIED} \(\n`, "gm");
+    for (const match of sql.matchAll(header)) {
+        const columns = new Map();
+        tables.set(`${unquoteIdent(match[1])}\u0000${unquoteIdent(match[2])}`, columns);
+        let at = match.index + match[0].length;
+        const column = new RegExp(String.raw ` {4}(${IDENT}) (.+?)(?= COLLATE | DEFAULT | NOT NULL| GENERATED |,?\n)`, "y");
+        while (at < sql.length && !sql.startsWith(")", at)) {
+            if (sql.startsWith("    CONSTRAINT ", at)) {
+                at = sql.indexOf("\n", at) + 1 || sql.length;
+                continue;
+            }
+            column.lastIndex = at;
+            const found = column.exec(sql);
+            if (!found)
+                break;
+            columns.set(unquoteIdent(found[1]), found[2]);
+            at = sql.indexOf("\n", column.lastIndex) + 1 || sql.length;
+        }
+    }
+    return tables;
+}
+/**
+ * 数据段的 COPY 头(dumpTableData_copy):"COPY <表> <列清单> FROM stdin;"。没有列的表列清单是空串,
+ * 所以那一行中间是两个空格,返回空列表。
+ */
+export function parseCopyHeader(line) {
+    const match = new RegExp(String.raw `^COPY ${QUALIFIED} (?:\(${COLUMNS}\))? FROM stdin;$`).exec(line);
+    if (!match)
+        return null;
+    return {
+        table: { schema: unquoteIdent(match[1]), name: unquoteIdent(match[2]) },
+        columns: match[3] ? splitColumns(match[3]) : [],
+    };
+}
+/**
+ * COPY 文本格式的一个字段 → 值(\N = NULL)。转义规则照 PostgreSQL 文档 "COPY / Text Format":
+ * \b \f \n \r \t \v \\,\ 加 1–3 位八进制,\x 加 1–2 位十六进制,其余 \c 就是 c 本身。
+ */
+export function decodeCopyField(field) {
+    if (field === "\\N")
+        return null;
+    if (!field.includes("\\"))
+        return field;
+    return field.replace(/\\(?:([0-7]{1,3})|x([0-9a-fA-F]{1,2})|(.))/g, (_, octal, hex, char) => {
+        if (octal)
+            return String.fromCharCode(parseInt(octal, 8));
+        if (hex)
+            return String.fromCharCode(parseInt(hex, 16));
+        const named = { b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v" };
+        return named[char] ?? char;
+    });
+}

package/dist/exporter.d.ts

@@ -0,0 +1,57 @@
+import { type Server } from "node:http";
+import { type S3Client } from "@aws-sdk/client-s3";
+import { type BackupConfig } from "./config.js";
+/**
+ * `backupdrill exporter`:按 Prometheus 文本格式暴露桶里备份与演练的状态。
+ * 规矩照 https://prometheus.io/docs/instrumenting/writing_exporters/ :
+ *  - 每次抓取现读桶,不按自己的定时器预取,不报旧值;
+ *  - 读不了桶时照样回 200,backupdrill_up 为 0,其余业务指标不出(半套数据比没有更误导);
+ *  - 指标不带标签(一个 exporter 进程只看一个项目,项目名属于 Prometheus 那边的 target 标签),
+ *    连接串、key、桶名一律不进指标。
+ */
+/** 10059:Prometheus wiki「Default port allocations」上 10058 之后的第一个空位(2026-10-20 查)。 */
+export declare const DEFAULT_EXPORTER_PORT = 10059;
+/** 最新一份完整快照里 exporter 要用的数,不留整份 manifest(Storage 文件多时 manifest 很大) */
+export interface SnapshotSummary {
+    createdAt: number;
+    dumpBytes: number;
+    storageFiles: number;
+    storageBytes: number;
+    tables: number;
+    estimatedRows: number;
+}
+export interface BucketState {
+    /** <prefix>/<project>/ 下的快照目录数,含没写完 manifest 的 */
+    snapshots: number;
+    /** 最新一份有 manifest.json 的快照;一份都没有时为 null */
+    latest: SnapshotSummary | null;
+    /** 最近一次记下的演练(drill --record);没有时为 null */
+    lastDrill: {
+        finishedAt: number;
+        pass: boolean;
+    } | null;
+    /** 最近一次通过的演练;restoreSeconds 来自它的记录内容 */
+    lastPassedDrill: {
+        finishedAt: number;
+        restoreSeconds?: number;
+    } | null;
+}
+/**
+ * 读桶的函数。每次调用都现读;唯一记住的是最新一份 manifest 的 ETag 和摘要:
+ * 下次带 If-None-Match 去问,没变就是 304、不传正文。快照写完就不再改,而一份 manifest 列着
+ * 每个 Storage 文件,可能有几十 MB,每 30 秒整份下载一遍会变成用户账单上的流量。
+ */
+export declare function createBucketReader(s3: S3Client, config: BackupConfig): (abortSignal: AbortSignal) => Promise<BucketState>;
+/** state 为 null = 这次没读成桶。全部是 gauge:都是"某一刻的状态",没有一个会只增不减。 */
+export declare function renderMetrics(state: BucketState | null, scrapeSeconds: number): string;
+/**
+ * 读桶的时限跟着 Prometheus 走:它在请求头里告诉我们这次抓取最多等多久,留半秒余量,
+ * 好让超时的这次还能回一个 up=0,而不是被 Prometheus 当成 exporter 挂了。
+ */
+export declare function scrapeTimeoutMs(header: string | string[] | undefined): number;
+export declare function createExporterServer(read: (abortSignal: AbortSignal) => Promise<BucketState>): Server;
+/** CLI 的 `backupdrill exporter`:起 HTTP 服务,直到进程被停掉。 */
+export declare function startExporter(config: BackupConfig, opts: {
+    host: string;
+    port: number;
+}): Promise<Server>;

package/dist/exporter.js

@@ -0,0 +1,305 @@
+import { createServer } from "node:http";
+import { performance } from "node:perf_hooks";
+import { GetObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
+import { requireBucket } from "./config.js";
+import { withDeadline } from "./deadline.js";
+import { drillRecordsPrefix, parseDrillRecord, parseDrillRecordName } from "./drill-record.js";
+import { log } from "./log.js";
+import { parseManifest } from "./manifest.js";
+import { listSnapshotPrefixes, targetClient } from "./snapshots.js";
+import { TOOL_VERSION } from "./version.js";
+/**
+ * `backupdrill exporter`:按 Prometheus 文本格式暴露桶里备份与演练的状态。
+ * 规矩照 https://prometheus.io/docs/instrumenting/writing_exporters/ :
+ *  - 每次抓取现读桶,不按自己的定时器预取,不报旧值;
+ *  - 读不了桶时照样回 200,backupdrill_up 为 0,其余业务指标不出(半套数据比没有更误导);
+ *  - 指标不带标签(一个 exporter 进程只看一个项目,项目名属于 Prometheus 那边的 target 标签),
+ *    连接串、key、桶名一律不进指标。
+ */
+/** 10059:Prometheus wiki「Default port allocations」上 10058 之后的第一个空位(2026-10-20 查)。 */
+export const DEFAULT_EXPORTER_PORT = 10059;
+/** 没有 Prometheus 超时头时(手动 curl)给读桶留的时间,与 Prometheus 默认 scrape_timeout 一致 */
+const DEFAULT_SCRAPE_TIMEOUT_MS = 10_000;
+const MAX_SCRAPE_TIMEOUT_MS = 5 * 60_000;
+/**
+ * 记录里的时间最多可以比这台机器的时钟快多少。备份、演练、exporter 可能在不同机器上跑,
+ * 几分钟的时钟差是正常的;再多就不可信。
+ */
+const CLOCK_SKEW_TOLERANCE_MS = 10 * 60_000;
+function httpStatusOf(error) {
+    return error.$metadata?.httpStatusCode;
+}
+async function readObject(s3, bucket, key, abortSignal, ifNoneMatch) {
+    try {
+        const res = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key, IfNoneMatch: ifNoneMatch }), { abortSignal });
+        return { status: "ok", text: await res.Body.transformToString(), etag: res.ETag };
+    }
+    catch (error) {
+        const status = httpStatusOf(error);
+        if (status === 304)
+            return { status: "not-modified" };
+        if (status === 404 || error.name === "NoSuchKey")
+            return { status: "missing" };
+        throw error;
+    }
+}
+function summarize(text, key) {
+    const manifest = parseManifest(text);
+    // parseManifest 不校验 createdAt(演练和恢复用不到),这里要拿它当备份时间,自己把关
+    const createdAt = Date.parse(manifest.createdAt);
+    if (!Number.isFinite(createdAt)) {
+        throw new Error(`${key} is malformed: createdAt`);
+    }
+    assertNotInFuture(createdAt, key, "createdAt");
+    const summary = {
+        createdAt,
+        dumpBytes: manifest.dump.bytes,
+        storageFiles: manifest.storage?.fileCount ?? 0,
+        storageBytes: manifest.storage?.totalBytes ?? 0,
+        tables: manifest.database.tableCount,
+        estimatedRows: manifest.database.estimatedRowTotal,
+    };
+    // 这些数会原样写进指标文本。parseManifest 只管演练和恢复要用的字段(estimatedRowTotal 就不查),
+    // 一个字符串或带换行的值能让整次抓取在 Prometheus 那边解析失败,甚至塞进假样本
+    for (const [field, value] of Object.entries(summary)) {
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            throw new Error(`${key} is malformed: ${field} is not a non-negative number`);
+        }
+    }
+    return summary;
+}
+/**
+ * 时间在将来的记录会让"距今多久"的告警永远不响(time() - 将来的时间是负数)。
+ * 报成读桶失败(up=0),让人去看是记录被改了还是哪台机器的时钟不对。
+ */
+function assertNotInFuture(at, key, field) {
+    if (at > Date.now() + CLOCK_SKEW_TOLERANCE_MS) {
+        throw new Error(`${key} has ${field} ${new Date(at).toISOString()}, more than 10 minutes in the future ` +
+            `(check the clock on the machine that wrote it)`);
+    }
+}
+/** <prefix>/<project>.drills/ 下的对象名,分页列完 */
+async function listDrillRecordNames(s3, bucket, prefix, abortSignal) {
+    const names = [];
+    let token;
+    do {
+        const res = await s3.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix, Delimiter: "/", ContinuationToken: token }), { abortSignal });
+        for (const object of res.Contents ?? []) {
+            if (object.Key)
+                names.push(object.Key.slice(prefix.length));
+        }
+        token = res.IsTruncated ? res.NextContinuationToken : undefined;
+    } while (token);
+    return names;
+}
+/**
+ * 最近一次演练和最近一次通过的演练。结束时间和结论都在文件名里,列一下目录就够;
+ * 只为了恢复用时读一次通过的那份。时间在将来的记录(写它的机器时钟快了,或被改过)跳过并警告:
+ * 它会一直排在最前面,让"距今多久"的告警算出负数。记录从不删除,所以不能让它把读桶整个弄成失败。
+ */
+async function readDrills(s3, config, abortSignal) {
+    const bucket = requireBucket(config).bucket;
+    const prefix = drillRecordsPrefix(config);
+    const now = Date.now();
+    let lastDrill = null;
+    let lastPassed = null;
+    for (const name of await listDrillRecordNames(s3, bucket, prefix, abortSignal)) {
+        const parsed = parseDrillRecordName(name);
+        if (!parsed)
+            continue;
+        if (parsed.finishedAt > now + CLOCK_SKEW_TOLERANCE_MS) {
+            log.warn(`Ignoring ${prefix}${name}: it is dated more than 10 minutes in the future (check the clock on the machine that ran the drill).`);
+            continue;
+        }
+        if (!lastDrill || parsed.finishedAt > lastDrill.finishedAt)
+            lastDrill = { ...parsed, name };
+        if (parsed.pass && (!lastPassed || parsed.finishedAt > lastPassed.finishedAt)) {
+            lastPassed = { finishedAt: parsed.finishedAt, name };
+        }
+    }
+    let lastPassedDrill = null;
+    if (lastPassed) {
+        const key = prefix + lastPassed.name;
+        const read = await readObject(s3, bucket, key, abortSignal);
+        // 刚列出来就不见了:生命周期规则正好删了它,或者有人手动删了。按读失败处理,下次抓取再看
+        if (read.status !== "ok")
+            throw new Error(`${key} disappeared while it was being read`);
+        const record = parseDrillRecord(read.text, key);
+        if (!record.pass || Date.parse(record.finishedAt) !== lastPassed.finishedAt) {
+            throw new Error(`${key} is malformed: its content does not match its name`);
+        }
+        lastPassedDrill = { finishedAt: lastPassed.finishedAt, restoreSeconds: record.restoreSeconds };
+    }
+    return {
+        lastDrill: lastDrill ? { finishedAt: lastDrill.finishedAt, pass: lastDrill.pass } : null,
+        lastPassedDrill,
+    };
+}
+/**
+ * 读桶的函数。每次调用都现读;唯一记住的是最新一份 manifest 的 ETag 和摘要:
+ * 下次带 If-None-Match 去问,没变就是 304、不传正文。快照写完就不再改,而一份 manifest 列着
+ * 每个 Storage 文件,可能有几十 MB,每 30 秒整份下载一遍会变成用户账单上的流量。
+ */
+export function createBucketReader(s3, config) {
+    const storage = requireBucket(config);
+    const root = `${storage.prefix}/${config.projectName}/`;
+    let remembered = null;
+    return async (abortSignal) => {
+        const prefixes = (await listSnapshotPrefixes(s3, storage.bucket, root, abortSignal))
+            .sort()
+            .reverse();
+        // manifest 是快照的完成标记,最后写。目录在、manifest 不在 = 备份还在跑或中途失败了,
+        // 往前找上一份完整的。不设上限:找太久就撞上抓取超时,报 up=0,这本身就该有人去看
+        let latest = null;
+        for (const prefix of prefixes) {
+            const key = `${prefix}manifest.json`;
+            const known = remembered?.key === key ? remembered : null;
+            const read = await readObject(s3, storage.bucket, key, abortSignal, known?.etag);
+            if (read.status === "missing")
+                continue;
+            if (read.status === "not-modified" && known) {
+                // 内容没变,但"是不是在将来"取决于现在几点:本机时钟被校正回来之后要重新判断
+                assertNotInFuture(known.summary.createdAt, key, "createdAt");
+                latest = known.summary;
+            }
+            else if (read.status === "ok") {
+                latest = summarize(read.text, key);
+                remembered = read.etag ? { key, etag: read.etag, summary: latest } : null;
+            }
+            else {
+                // 没带 If-None-Match 却收到 304:对端行为不对,别猜
+                throw new Error(`unexpected 304 Not Modified for ${key}`);
+            }
+            break;
+        }
+        const drills = await readDrills(s3, config, abortSignal);
+        return { snapshots: prefixes.length, latest, ...drills };
+    };
+}
+const escapeHelp = (s) => s.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+const escapeLabel = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+const seconds = (ms) => ms / 1000;
+function gauge(name, help, value) {
+    return value === null ? null : { name, help, samples: [{ value }] };
+}
+/** state 为 null = 这次没读成桶。全部是 gauge:都是"某一刻的状态",没有一个会只增不减。 */
+export function renderMetrics(state, scrapeSeconds) {
+    const latest = state?.latest ?? null;
+    const lastDrill = state?.lastDrill ?? null;
+    const lastPassed = state?.lastPassedDrill ?? null;
+    const families = [
+        gauge("backupdrill_up", "Whether the last read of the backup bucket worked (1) or failed (0).", state ? 1 : 0),
+        gauge("backupdrill_scrape_duration_seconds", "How long this scrape took to read the backup bucket.", scrapeSeconds),
+        {
+            name: "backupdrill_build_info",
+            help: "The backupdrill CLI version running this exporter. Always 1.",
+            samples: [{ labels: { version: TOOL_VERSION }, value: 1 }],
+        },
+    ];
+    if (state) {
+        families.push(gauge("backupdrill_snapshots", "Snapshot folders under <prefix>/<project>/, including ones without a manifest.json yet.", state.snapshots), gauge("backupdrill_backup_last_success_timestamp_seconds", "When the newest complete snapshot finished (its manifest.json createdAt), as a Unix timestamp. 0 if there is none.", latest ? seconds(latest.createdAt) : 0), gauge("backupdrill_latest_snapshot_dump_bytes", "Size of the database dump (pg_dump custom format) in the newest complete snapshot.", latest?.dumpBytes ?? null), gauge("backupdrill_latest_snapshot_storage_files", "Supabase Storage files in the newest complete snapshot. 0 for a database-only backup.", latest?.storageFiles ?? null), gauge("backupdrill_latest_snapshot_storage_bytes", "Total size of the Supabase Storage files in the newest complete snapshot.", latest?.storageBytes ?? null), gauge("backupdrill_latest_snapshot_tables", "Tables, partitioned tables and materialized views captured in the newest complete snapshot.", latest?.tables ?? null), gauge("backupdrill_latest_snapshot_estimated_rows", "Row count of the newest complete snapshot, estimated from Postgres statistics (n_live_tup) at backup time.", latest?.estimatedRows ?? null), gauge("backupdrill_drill_last_run_timestamp_seconds", "When the last drill recorded with --record finished, passed or not, as a Unix timestamp. 0 if none is recorded.", lastDrill ? seconds(lastDrill.finishedAt) : 0), gauge("backupdrill_drill_last_run_passed", "Whether the last recorded drill passed (1) or not (0).", lastDrill ? (lastDrill.pass ? 1 : 0) : null), gauge("backupdrill_drill_last_success_timestamp_seconds", "When the last passing drill recorded with --record finished, as a Unix timestamp. 0 if none is recorded.", lastPassed ? seconds(lastPassed.finishedAt) : 0), gauge("backupdrill_drill_last_success_restore_duration_seconds", "How long the database restore took in the last passing recorded drill.", lastPassed?.restoreSeconds ?? null));
+    }
+    const lines = [];
+    for (const family of families) {
+        if (!family)
+            continue;
+        lines.push(`# HELP ${family.name} ${escapeHelp(family.help)}`, `# TYPE ${family.name} gauge`);
+        for (const sample of family.samples) {
+            const labels = sample.labels
+                ? `{${Object.entries(sample.labels)
+                    .map(([k, v]) => `${k}="${escapeLabel(v)}"`)
+                    .join(",")}}`
+                : "";
+            lines.push(`${family.name}${labels} ${sample.value}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * 读桶的时限跟着 Prometheus 走:它在请求头里告诉我们这次抓取最多等多久,留半秒余量,
+ * 好让超时的这次还能回一个 up=0,而不是被 Prometheus 当成 exporter 挂了。
+ */
+export function scrapeTimeoutMs(header) {
+    const value = Number(Array.isArray(header) ? header[0] : header);
+    if (!Number.isFinite(value) || value <= 0)
+        return DEFAULT_SCRAPE_TIMEOUT_MS;
+    // AbortSignal.timeout 只收整数毫秒(1.1 秒算出来是 600.0000000000001,直接抛错);
+    // 上限防一个离谱的头把读桶拖成几小时
+    return Math.min(Math.max(1, Math.floor(Math.max(value - 0.5, value / 2) * 1000)), MAX_SCRAPE_TIMEOUT_MS);
+}
+const LANDING_PAGE = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>backupdrill exporter</title></head>
+<body>
+<h1>backupdrill exporter</h1>
+<p>Version ${TOOL_VERSION}. Prometheus metrics for the backups and recorded restore drills in one project's bucket.</p>
+<p><a href="/metrics">Metrics</a></p>
+</body>
+</html>
+`;
+export function createExporterServer(read) {
+    return createServer((req, res) => {
+        // 处理函数是 async:里面任何没接住的异常都会变成未处理的 rejection,把整个进程带走。
+        // 端口对 Prometheus 开着,一个怪请求不能让 exporter 停掉
+        handle(req, res, read).catch((error) => {
+            log.warn(`Request failed: ${error.message}`);
+            if (!res.headersSent)
+                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end();
+        });
+    });
+}
+async function handle(req, res, read) {
+    // 只要路径,不用 new URL:"GET // HTTP/1.1" 这种请求行会让它抛 Invalid URL
+    const path = (req.url ?? "/").split("?")[0];
+    if (req.method !== "GET") {
+        res.writeHead(405, { Allow: "GET", "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Method Not Allowed\n");
+        return;
+    }
+    if (path === "/") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(LANDING_PAGE);
+        return;
+    }
+    if (path !== "/metrics") {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Not Found\n");
+        return;
+    }
+    const started = performance.now();
+    const timeoutMs = scrapeTimeoutMs(req.headers["x-prometheus-scrape-timeout-seconds"]);
+    let state = null;
+    try {
+        state = await withDeadline(read, timeoutMs);
+    }
+    catch (error) {
+        const e = error;
+        const reason = e.name === "TimeoutError" || e.name === "AbortError"
+            ? `timed out after ${(timeoutMs / 1000).toFixed(1)}s`
+            : e.message;
+        log.warn(`Could not read the backup bucket: ${reason}`);
+    }
+    // 微秒够用,免得样本里出现 0.021267749999999978 这种浮点尾巴
+    const body = renderMetrics(state, Number(((performance.now() - started) / 1000).toFixed(6)));
+    res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+    res.end(body);
+}
+/** CLI 的 `backupdrill exporter`:起 HTTP 服务,直到进程被停掉。 */
+export async function startExporter(config, opts) {
+    const storage = requireBucket(config);
+    const server = createExporterServer(createBucketReader(targetClient(config), config));
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    // 报实际绑定的端口:--port 0 时由系统挑
+    const port = server.address().port;
+    const shownHost = opts.host.includes(":") ? `[${opts.host}]` : opts.host;
+    log.ok(`Serving metrics for s3://${storage.bucket}/${storage.prefix}/${config.projectName}/ ` +
+        `at http://${shownHost}:${port}/metrics`);
+    return server;
+}

package/dist/external-refs.d.ts

@@ -0,0 +1,40 @@
+import type pg from "pg";
+import { type ForeignKeyDef } from "./dump-sql.js";
+export interface CheckedForeignKey {
+    fk: ForeignKeyDef;
+    /** 引用列全非空的行数(MATCH SIMPLE:有一列为空就不校验) */
+    rows: number;
+    /** 其中在目标库找不到被引用行的 */
+    missingRows: number;
+}
+export interface ExternalReferenceCheck {
+    checked: CheckedForeignKey[];
+    /** 恢复一定会失败的原因,一条一句 */
+    problems: string[];
+    /** 没能检查的,一条一句。恢复在一个事务里跑,这些真出问题也会整体回滚,所以只提示不拦 */
+    unchecked: string[];
+    /** 有外键要等扩展装上之后才查得了(见 pendingExtensions) */
+    waitingForExtensions: boolean;
+}
+/**
+ * 读 dump,找出指向 dumpedSchemas 之外的外键,逐条拿目标库对行。只读:目标库上只跑 select。
+ * pg_restore 起不来、归档读不了时抛错,由调用方当成 blocker。单条外键查不成(目标端报错、
+ * 数据块读不了)只影响它自己,记进 unchecked,不拖累别的外键的结论。
+ */
+export declare function checkExternalReferences(opts: {
+    dumpPath: string;
+    dumpedSchemas: string[];
+    targetUrl: string;
+    /**
+     * manifest 里记着、目标上还没装的扩展。有它们在,被引用的表不在、引用方列的类型不在,都可能是
+     * 扩展装上之后才有的(扩展可以往别的 schema 里建表,只看它登记的 schema 不够,交叉审查复现),
+     * 这时报"装完扩展再查",不当成 blocker;正式恢复装完扩展会再查一遍。
+     */
+    pendingExtensions?: string[];
+    /**
+     * 调用方开着的事务(正式恢复里"先装扩展再复查"的那个):在它里面查,看得到还没提交的扩展。
+     * 每条查询包在一个保存点里、查完就回滚到保存点,检查本身留不下任何东西。
+     */
+    inTransaction?: pg.Client;
+}): Promise<ExternalReferenceCheck>;
+export declare function describe(fk: ForeignKeyDef): string;