convex-backup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Back up — and prove the restore works

备份——并证明恢复确实可行

Every backup story has two halves and most people only do the first: taking the backup, and proving you can get it back. This capability does both — it sets up regular snapshot exports and then runs a RESTORE DRILL that actually recovers the data into a disposable preview and asserts it's intact. The drill reuses migrate-rehearse's exact primitives (snapshot export → preview deploy → snapshot import) pointed at recovery instead of a forward change, so the safety net is tested, not assumed.

每个备份方案都有两部分，而大多数人只做第一部分：执行备份，以及证明能够把数据取回来。此能力两者皆做——它设置定期的快照导出，然后执行恢复演练（RESTORE DRILL），将数据实际恢复到一次性预览环境中，并断言数据完整。演练复用 migrate-rehearse 完全相同的基础操作（快照导出 → 预览部署 → 快照导入），只是将目标从正向变更切换为恢复，从而实际检验安全网，而非将其视为理所当然。

Workflow

工作流

GUARD: deploy-guard — classify + announce the deployment being backed up (reading/exporting is safe; the drill's restore target is a throwaway preview, never prod).
TAKE the snapshot:
```
npx convex export --path backup-<date>.zip
```
(add
```
--include-file-storage
```
if the app stores files). This is the backup artifact; treat it as sensitive real data.
SCHEDULE it (the ongoing half): recommend a cadence matched to how fast the data changes and how much loss is tolerable (RPO) — e.g. a daily
```
npx convex export
```
via CI/cron to durable storage the user controls, with a retention window. Convex's own platform backups exist; this adds a user-owned, portable copy.
RESTORE DRILL (the half almost nobody does — this is the point): (a) PRECONDITION: a Preview Deploy Key as
```
CONVEX_DEPLOY_KEY
```
(same requirement as migrate-rehearse; a paid-tier feature). If unavailable, drill against a fresh personal dev deployment instead and say so. (b) create a throwaway preview from the CURRENT code:
```
npx convex deploy --preview-create restore-drill-<date>
```
. (c) restore the snapshot into it:
```
npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace
```
(import targets a deployment by NAME with
```
--deployment
```
; there is no
```
--preview-name
```
on import). (d) ASSERT recovery: read the restored data back (MCP
```
tables
```
for row counts,
```
data
```
/
```
runOneoffQuery
```
for spot-checks) and confirm the critical tables came back with the expected row counts and a sample of real records — a restore that 'succeeds' but lands 0 rows is a FAILED drill. Compare against the source's counts where available.
REPORT the drill result plainly: what was backed up, that the restore was ACTUALLY performed and verified (or that it FAILED and why — a failed drill is the most valuable output, found before a real disaster), the recommended schedule + retention, and the recovery runbook (the exact commands to restore to prod:
```
npx convex import backup.zip --replace --prod
```
, gated by deploy-guard, with the post-snapshot-write-loss caveat stated).
HYGIENE: delete local snapshot copies when done (real data); the drill preview auto-expires. Never commit a backup file.

守卫（GUARD）：deploy-guard——对正在备份的部署进行分类并发出通知（读取/导出是安全操作；演练的恢复目标是一次性预览环境，绝不会是 prod）。
获取快照（TAKE）：
```
npx convex export --path backup-<date>.zip
```
（如果应用存储文件，请添加
```
--include-file-storage
```
）。该文件是备份产物；应将其视为敏感的真实数据。
制定计划（SCHEDULE）（持续执行的部分）：根据数据变化速度以及可容忍的数据丢失量（RPO），推荐匹配的备份频率——例如，每天通过 CI/cron 执行一次
```
npx convex export
```
，将备份保存到由用户控制的持久化存储中，并设置保留期限。Convex 自身的平台备份已经存在；此方案会额外创建一份用户自有、可移植的副本。
恢复演练（RESTORE DRILL）（几乎无人执行的部分——这正是重点）：（a）前置条件（PRECONDITION）：将 Preview Deploy Key 配置为
```
CONVEX_DEPLOY_KEY
```
（与 migrate-rehearse 的要求相同；属于付费套餐功能）。如果无法获取，则改为在全新的个人 dev 部署上执行演练，并明确说明这一点。（b）基于当前代码创建一次性预览环境：
```
npx convex deploy --preview-create restore-drill-<date>
```
。（c）将快照恢复到该环境：
```
npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace
```
（导入时通过
```
--deployment
```
指定以 NAME 标识的 deployment；导入操作不支持
```
--preview-name
```
）。（d）断言恢复结果（ASSERT）：读回已恢复的数据（使用 MCP
```
tables
```
获取行数，通过
```
data
```
/
```
runOneoffQuery
```
进行抽查），确认关键表已恢复且行数符合预期，并能查询到真实记录样本——如果恢复显示“成功”，但落地了 0 行，则演练失败（FAILED）。在源数据计数可用时，与其进行比较。
清晰报告（REPORT）演练结果：备份了什么；恢复是否确实已执行并验证，或者演练是否失败及其原因——演练失败是最有价值的产出，可以在真实灾难发生前发现问题；同时给出推荐的备份计划与保留期限，以及恢复运行手册（将备份恢复到 prod 的确切命令：
```
npx convex import backup.zip --replace --prod
```
，该操作受 deploy-guard 门控，并明确说明快照后写入数据可能丢失的注意事项）。
清理（HYGIENE）：完成后删除本地快照副本（其中包含真实数据）；演练预览环境会自动过期。切勿提交备份文件。

Rules

规则

A backup you have never restored is a hope, not a backup — always run (or offer to run) the restore DRILL, don't just take the export.
The drill restores into a THROWAWAY preview (or dev), never prod; the restore target and the backup source are different deployments.
Assert recovery, don't assume it: a restore that lands 0 rows is a FAILED drill — check critical-table row counts + a real-record sample against the source.
A FAILED drill is the most valuable output — surface it loudly; that's the whole reason to drill before a real disaster.
Schedule matched to RPO (how much data loss is tolerable); keep a user-owned portable copy alongside Convex's platform backups, with a retention window.
Snapshots are sensitive real data: delete local copies when done, never commit them; the restore-to-prod runbook is deploy-guard-gated with the post-snapshot-write-loss caveat stated.
Shares migrate-rehearse's snapshot+preview mechanics but aims them at RECOVERY, not a forward change — a forward schema change is migrate-rehearse.

从未恢复过的备份只是一个愿望，不是备份——始终执行（或主动提供执行）恢复演练，不要仅仅完成导出。
演练只能恢复到一次性预览环境（或 dev），绝不能恢复到 prod；恢复目标与备份源必须属于不同的 deployment。
必须断言恢复结果，不能想当然：如果恢复后落地了 0 行，则演练失败——对照源数据检查关键表的行数和真实记录样本。
演练失败是最有价值的产出——应显著 surfaced；这正是要在真实灾难前进行演练的全部意义。
制定与 RPO（可容忍的数据丢失量）匹配的备份计划；在 Convex 平台备份之外保留一份用户自有、可移植的副本，并设置保留期限。
快照包含敏感的真实数据：完成后删除本地副本，切勿提交；恢复到 prod 的运行手册必须受 deploy-guard 门控，并明确说明快照后写入数据可能丢失的注意事项。
与 migrate-rehearse 共用快照和预览机制，但目标是恢复（RECOVERY），而不是正向变更——正向 schema 变更应由 migrate-rehearse 处理。