AutoGineer
Generated banner for Convex Migrate Rehearse
Generated logo for Convex Migrate Rehearse

Convex Migrate Rehearse

ConvexOfficialPublished by Convex

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Rehearse a live-app schema change + backfill on a snapshot-seeded preview deployment, verify, then promote the proven change to prod with the snapshot as rollback.
— the description by Convex

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a rigorous, step-by-step procedure for performing schema changes in a production-like environment. By using a snapshot-seeded preview deployment, you can validate schema updates and data backfills against real production data without risking production downtime or data corruption. The workflow emphasizes the 'optional-then-tighten' pattern, ensuring that schema validation gates are tested safely on a copy before being promoted to the live production environment.

What it does

  • Exports a read-only snapshot of production data for migration testing.
  • Creates a temporary preview deployment seeded with production data.
  • Guides the user through the optional-then-tighten schema migration pattern.
  • Facilitates batched, resumable data backfills using specialized migration tools.
  • Provides a verification phase to test application functions against migrated data.
  • Outlines a safe promotion process to production with a rollback strategy.

When to use it

  • When you need to perform a breaking schema change on a live production database.
  • When you want to verify that a data backfill correctly handles existing production records.
  • When you need to ensure schema validation gates will pass before deploying to production.
  • When you require a reliable rollback mechanism for a complex database migration.

Advantages

  • Prevents production schema push failures by catching issues in a preview environment.
  • Reduces risk by testing the exact migration sequence on production-like data.
  • Provides a clear, repeatable process for complex database evolutions.
  • Ensures data integrity through a structured verification phase.

Usage examples

“I need to add a required field to my users table in production. How do I do this safely?”
The agent will guide you through the rehearsal workflow: creating a preview, seeding it with a production snapshot, deploying the field as optional, running the backfill, and finally tightening the schema.
“How can I test my migration script against real production data without affecting the live app?”
The agent will provide the steps to export a production snapshot, import it into a preview deployment, and execute your migration scripts there for verification.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/convex/convex-migrate-rehearse/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip convex-migrate-rehearse.zip -d .agents/skills

Documentation by Convex

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

Rehearse a schema change on a preview before prod

A schema push on Convex validates every existing document against the new schema and FAILS the push if any row doesn't conform — a real data-conformance gate. The safe way to use that gate is to let it fail on a rehearsal copy, not on prod. This capability turns a preview deployment into that copy: seed it with a prod snapshot, push the new schema + run the backfill there, watch the gate, and only promote once it's green. It composes deploy-guard (target classification), migrate (the optional-then-tighten pattern), and @convex-dev/migrations (the batched, resumable backfill).

Workflow

  1. PRECONDITION: preview deployments need a Preview Deploy Key (dashboard → Project Settings → Deploy Keys → Preview) exported as CONVEX_DEPLOY_KEY before any --preview-create/--preview-name deploy — a plain npx convex login session cannot create previews, and this is a paid-tier feature. If no preview key is available, fall back to rehearsing on the personal dev deployment seeded with the snapshot, and say so.

  2. GUARD: deploy-guard — classify + announce the SOURCE (prod, being read) and the eventual TARGET (prod, being changed); get the fresh explicit yes for the prod promote up front and confirm the plan.

  3. SNAPSHOT the source data read-only: npx convex export --path snapshot.zip (from the deployment holding the real data; add --include-file-storage only if the migration touches files). This is a read; it changes nothing.

  4. CREATE the preview FROM THE PRE-CHANGE CODE — do this BEFORE editing schema.ts, so the preview starts on the schema the snapshot data already conforms to: npx convex deploy --preview-create migrate-<slug> (needs the preview key; auto-expires ~5 days). Seed it: npx convex import snapshot.zip --deployment migrate-<slug> (import targets a deployment by NAME with --deployment; there is no --preview-name flag on import). The import succeeds because the data still matches the old schema.

  5. REHEARSE on the preview, in the migrate order — each push is npx convex deploy --preview-name migrate-<slug> (re-deploys to the SAME preview, keeping its data; NOT convex dev, which targets personal dev): (a) make the new/changed field OPTIONAL and deploy — if existing rows violate it the push FAILS HERE on the copy with the offending shape; fix and re-push until green. (b) write a @convex-dev/migrations backfill and run it against the preview; verify every row is now valid. (c) tighten the validator (required / narrowed union) and deploy again — the gate now passes because the backfill ran.

  6. VERIFY on the preview: run the app's functions against the migrated data (MCP run/runOneoffQuery pointed at the preview, or a smoke query) to confirm behavior and shape.

  7. PROMOTE only on the fresh explicit yes from step 1: apply the SAME sequence to prod (optional schema → backfill → tighten). Because it already succeeded on prod-shaped data, the prod push repeats a proven run. Keep the snapshot as the rollback artifact (npx convex import snapshot.zip --replace --prod); state plainly that data written after the snapshot is lost, so keep the promote window short.

  8. CLEAN UP: the preview auto-expires; delete the local snapshot when done (it holds real data — treat it as sensitive, never commit it).

Rules

  • Create the preview from the PRE-CHANGE code and seed the snapshot BEFORE editing schema.ts — so the import conforms and the conformance gate then fails on the copy (not prod) when you push the change; each preview push is deploy --preview-name, import targets it with --deployment.

  • Follow the migrate order every time: optional field → push → backfill → verify → tighten → push; skipping 'optional first' makes the very first push reject existing rows.

  • The prod promote needs a fresh explicit yes (deploy-guard) and is a REPEAT of the proven preview run, not a new attempt.

  • Keep the prod snapshot as the rollback artifact; state plainly that a snapshot-restore loses data written after the snapshot, so keep the promote window short.

  • Treat the exported snapshot as sensitive real data: delete it locally when finished; never commit it.

  • Backfills go through @convex-dev/migrations (batched, resumable, dry-runnable), not ad-hoc one-shot mutations over a whole table.

  • This is the rehearsal-and-promote flow; for the plain 'explain optional-then-tighten' guidance with no live data, that's migrate.

Files

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Convex
Publisher
Convex (Official)
Source
convex/agent-skills · skills/convex-migrate-rehearse · commit f60629d
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Convex.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download convex-migrate-rehearse.zip