---
id: gh-convex-backup
name: "convex-backup"
url: https://skills.yangsir.net/skill/gh-convex-backup
author: convex
domain: ai-data-management-analysis
tags: ["backup", "restore", "convex", "disaster-recovery", "database"]
install_count: 34900
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-backup
---

# convex-backup

> 为 Convex 应用建立可靠备份并做恢复演练：导出快照、按 RPO 排期持久化，再把快照导入一次性预览部署并逐表核对行数与真实记录以证明数据真的回得来。它把「备份能恢复」从假设变成经过验证的事实，并产出可门控执行的恢复手册，让灾难发生前就发现失败。

**Stats**: 34,900 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 从「备份了但没试过恢复」到经过验证的恢复能力

**Before**:

团队定期跑导出命令，却从没真正把数据导入回去验证过；真出事时手忙脚乱翻文档、猜导入参数，关键表是否完整、有没有丢行只能靠运气，恢复窗口往往拖到数小时。

**After**:

该 Skill 导出快照后部署一次性预览做恢复演练，逐表核对行数与真实记录样本，几分钟内确认数据确实回得来，并给出按 RPO 匹配的排期与门控恢复手册。

| Metric | Before | After | Change |
|---|---|---|---|
| 恢复验证耗时 | 240分钟 | 15分钟 | -94% |
| 关键表恢复确认率 | 30% | 100% | +233% |
| 备份有效性验证覆盖率 | 20% | 100% | +400% |

## Readme

<!-- GENERATED from convex-agents content/capabilities/convex-backup.json — do not edit by hand. -->

# 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.

## Workflow

1. 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).
2. 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.
3. 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.
4. 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.
5. 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).
6. HYGIENE: delete local snapshot copies when done (real data); the drill preview auto-expires. Never commit a backup file.

## 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.


---
*Source: https://skills.yangsir.net/skill/gh-convex-backup*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-backup/markdown*