backupdrill 0.1.2 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ Backups stream through the CLI on your machine (or your CI) straight to your buc
 ## Why
 
 - Supabase's own database restore only brings back `storage.objects` **metadata**, not your actual Storage files.
-- Pro-plan backups keep 7 days and can't be pulled into your own infrastructure; PITR is $100/mo per project.
+- Pro-plan backups keep 7 days and can't be pulled into your own infrastructure; PITR is $100/month per project.
 - A `pg_dump` you've never restored is a guess.
 
 This CLI gets your database into a bucket **you** control, with a manifest you can check.
@@ -106,19 +106,19 @@ With those set, `backupdrill backup` also copies every Storage file into your bu
 
 ## Egress & cost — read this before scheduling daily backups
 
-A backup pulls data **out** of Supabase, which counts as **egress on your Supabase bill**. Verified rates (2026-07-04, [egress docs](https://supabase.com/docs/guides/platform/manage-your-usage/egress) + [pricing](https://supabase.com/pricing)):
+A backup pulls data **out** of Supabase, which counts as **egress on your Supabase bill**. Verified rates (2026-07-10, [egress docs](https://supabase.com/docs/guides/platform/manage-your-usage/egress) + [pricing](https://supabase.com/pricing)):
 
 - Backup traffic (pg_dump + first-time file downloads) is **uncached egress: $0.09/GB** above your plan's included allowance.
 - Included uncached egress: **Free 5 GB · Pro 250 GB · Team 250 GB** per month.
 - **Spend Cap is ON by default (Pro/Team).** If a backup pushes you past the quota, Supabase **throttles your whole project's egress** for the rest of the month and the backup fails — turn Spend Cap OFF to be billed the overage instead.
-- **Free is a hard cap:** exceed 5 GB and the project is restricted (never billed). A large daily backup can't complete on Free.
+- **Free never bills overage.** Exceeding the included 5 GB/month starts Supabase's Fair Use process: a notification to your billing email, then a grace period, then egress restrictions if usage stays over (the restriction clears at the next billing cycle or when you upgrade). Sustained large backups are not viable on Free.
 
 Rough cost (Pro, Spend Cap OFF, backups = your only egress):
 
 | DB + Storage | Weekly | Daily |
 |---|---|---|
-| 10 GB | $0/mo (within 250 GB) | ~$4.50/mo |
-| 50 GB | ~$0/mo | **~$112/mo** ⚠ |
+| 10 GB | $0/month (within 250 GB) | ~$4.50/month |
+| 50 GB | ~$0/month | **~$112/month** ⚠ |
 
 Cost scales with **size × frequency**. Run `backupdrill estimate` to project it for *your* project, and prefer weekly (or a smaller scope) once your data is large. The compressed dump is smaller than raw DB size, so real DB egress is below the `estimate` upper bound; Storage egress is exact.
 

package/dist/drill.d.ts

@@ -1,5 +1,13 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
+/**
+ * 无放回随机抽样:部分 Fisher-Yates,只洗出前 n 位(O(n) 次交换,不必全 shuffle)。
+ * 此前恒取 manifest 顺序的前 CAP 个 → 超过 CAP 的项目里排序靠后的文件永远不被校验;
+ * 随机抽样让每次演练覆盖不同子集,损坏的文件长期必然被抽中。
+ * 随机源用 Math.random 足够:演练是一次性进程,无可复现性要求——校验失败的文件名
+ * 会原样列进报告,定位问题不依赖重放同一批样本。
+ */
+export declare function sampleStorageFiles<T>(files: T[], n: number): T[];
 export interface DrillCheck {
     name: string;
     pass: boolean;

package/dist/drill.js

@@ -10,6 +10,23 @@ import { log } from "./log.js";
 const execFileAsync = promisify(execFile);
 // Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
 const STORAGE_SAMPLE_CAP = 100;
+/**
+ * 无放回随机抽样:部分 Fisher-Yates,只洗出前 n 位(O(n) 次交换,不必全 shuffle)。
+ * 此前恒取 manifest 顺序的前 CAP 个 → 超过 CAP 的项目里排序靠后的文件永远不被校验;
+ * 随机抽样让每次演练覆盖不同子集,损坏的文件长期必然被抽中。
+ * 随机源用 Math.random 足够:演练是一次性进程,无可复现性要求——校验失败的文件名
+ * 会原样列进报告,定位问题不依赖重放同一批样本。
+ */
+export function sampleStorageFiles(files, n) {
+    if (files.length <= n)
+        return files;
+    const pool = [...files];
+    for (let i = 0; i < n; i++) {
+        const j = i + Math.floor(Math.random() * (pool.length - i));
+        [pool[i], pool[j]] = [pool[j], pool[i]];
+    }
+    return pool.slice(0, n);
+}
 /**
  * 沙箱镜像选择:alpine 镜像只带 contrib 扩展,装不了 pgvector——含 vector 列的
  * 备份在裸镜像里恢复必然硬崩("type vector does not exist")。manifest 记录了
@@ -264,7 +281,7 @@ async function verifyRestored(connString, manifest) {
  */
 async function verifyStorage(s3, config, manifest, verifyAll) {
     const files = manifest.storage.files;
-    const sample = verifyAll ? files : files.slice(0, STORAGE_SAMPLE_CAP);
+    const sample = verifyAll ? files : sampleStorageFiles(files, STORAGE_SAMPLE_CAP);
     // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>,base 从 dump.key 反推
     const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
     const mismatches = [];
@@ -279,15 +296,16 @@ async function verifyStorage(s3, config, manifest, verifyAll) {
             mismatches.push(`${f.bucket}/${f.key} (unreadable)`);
         }
     }
-    const scope = verifyAll
-        ? `all ${files.length}`
-        : `${sample.length}/${files.length} sampled`;
+    // 抽样时如实说明这是随机样本(N of M);全量(--verify-all-files 或文件数 ≤ 上限)说 all
+    const scope = sample.length === files.length
+        ? `all ${files.length} files`
+        : `random sample of ${sample.length} of ${files.length} files`;
     return {
         name: "storage file integrity",
         pass: mismatches.length === 0,
         detail: mismatches.length === 0
-            ? `${scope} files match their manifest checksums`
-            : `${mismatches.length} of ${scope} failed: ${mismatches.slice(0, 5).join(", ")}`,
+            ? `${scope} match their manifest checksums`
+            : `${mismatches.length} failed in ${scope}: ${mismatches.slice(0, 5).join(", ")}`,
     };
 }
 // ── 主流程 ──────────────────────────────────────────────────────────

package/dist/estimate.d.ts

@@ -1,6 +1,6 @@
 import type { BackupConfig } from "./config.js";
 /**
- * Supabase egress 定价(2026-07-04 经核实,来源见 README「Egress & cost」)。
+ * Supabase egress 定价(2026-07-10 经核实,来源见 README「Egress & cost」)。
  * 单价 = 超出计划包含额度后的每 GB 价;included = 各计划每月包含的 egress。
  * 备份 = 把数据拉出 Supabase = egress,计入用户账单。这是 PRD §4.3 的上线否决项:
  * 让用户"我们帮你算过账"而不是收到意外账单。

package/dist/estimate.js

@@ -59,10 +59,10 @@ export async function runEstimate(config, pricing) {
     console.error(`  Plan: ${pricing.planLabel} — ${pricing.includedGb} GB egress included, ` +
         `then $${pricing.pricePerGb}/GB`);
     console.error("");
-    console.error("  Frequency   Runs/mo   Monthly egress   Overage   Est. cost/mo");
-    console.error("  ─────────   ───────   ──────────────   ───────   ────────────");
+    console.error("  Frequency   Runs/month   Monthly egress   Overage   Est. cost/month");
+    console.error("  ─────────   ──────────   ──────────────   ───────   ───────────────");
     for (const r of projection.rows) {
-        console.error(`  ${r.frequency.padEnd(9)}   ${String(r.runsPerMonth).padStart(7)}   ` +
+        console.error(`  ${r.frequency.padEnd(9)}   ${String(r.runsPerMonth).padStart(10)}   ` +
             `${(r.monthlyEgressGb + " GB").padStart(14)}   ` +
             `${(r.overageGb + " GB").padStart(7)}   ` +
             `$${r.monthlyCost.toFixed(2)}`);
@@ -76,11 +76,13 @@ export async function runEstimate(config, pricing) {
     const weekly = projection.rows.find((r) => r.frequency === "weekly");
     console.error("");
     if (pricing.hardCap) {
-        // Free:超额=限流,备份直接失败,daily 大库根本跑不完
+        // Free:超额不计费,走 Fair Use 通知 → 宽限期 → 限制;持续超额的大备份在 Free 跑不通
         if (daily && daily.overageGb > 0) {
-            log.warn(`${pricing.planLabel} egress is a HARD CAP (${pricing.includedGb} GB). ` +
-                `Daily backups (~${daily.monthlyEgressGb} GB/mo) will blow the cap and ` +
-                `get your project throttled — the backup itself will fail. ` +
+            log.warn(`${pricing.planLabel} plan egress is never billed, but exceeding the included ` +
+                `${pricing.includedGb} GB/month starts Supabase's Fair Use process: a ` +
+                `notification, then a grace period, then egress restrictions. Daily backups ` +
+                `(~${daily.monthlyEgressGb} GB/month) would keep you permanently over the ` +
+                `line — sustained large backups are not viable on Free. ` +
                 `Use weekly at most, or upgrade to Pro.`);
         }
     }
@@ -93,9 +95,9 @@ export async function runEstimate(config, pricing) {
             "numbers above are what you'd pay.");
         const worst = daily?.monthlyCost ?? 0;
         if (worst >= SUBSCRIPTION_FLOOR_USD) {
-            log.warn(`At daily frequency the egress overage alone (~$${worst.toFixed(0)}/mo) is ` +
+            log.warn(`At daily frequency the egress overage alone (~$${worst.toFixed(0)}/month) is ` +
                 `in the range of a paid backup subscription. Consider weekly ` +
-                `(~$${(weekly?.monthlyCost ?? 0).toFixed(0)}/mo overage) or a smaller scope.`);
+                `(~$${(weekly?.monthlyCost ?? 0).toFixed(0)}/month overage) or a smaller scope.`);
         }
     }
     return projection;

package/dist/index.js

@@ -7,9 +7,10 @@ import { runDrill } from "./drill.js";
 import { runRestore } from "./restore.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
-// Supabase egress 定价表(2026-07-04 核实,来源见 README「Egress & cost」)。
+// Supabase egress 定价表(2026-07-10 核实,来源见 README「Egress & cost」)。
 // 备份流量 100% 未缓存,故用 uncached 单价 $0.09/GB;included 用 uncached 额度。
-// Free 硬上限(超额即限流,不计费);Pro/Team 由 Spend Cap 决定超额限流还是计费。
+// Free 永不计费:超额走 Fair Use 流程(通知 → 宽限期 → 限制),持续大备份不可行;
+// Pro/Team 由 Spend Cap 决定超额限流还是计费。
 const EGRESS_PRICING = {
     free: { planLabel: "Free", includedGb: 5, pricePerGb: 0.09, hardCap: true },
     pro: { planLabel: "Pro", includedGb: 250, pricePerGb: 0.09, hardCap: false },

package/package.json

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