# Plan Safe Convex Data Migrations

Breaking Convex schema changes can fail deploys or damage production data. This skill guides safe rollouts, batched backfills, dry runs, and verification.

## Install

```bash
npx skillstore add get-convex/convex-migration-helper
```

## Metadata

- Status: approved
- Slug: get-convex-convex-migration-helper
- Skillstore revision: r1
- Version status: missing
- Tree hash: e2a42d588eb42a36664d2829518d8056b36cd4e84b63631aafa58ed041f2f86b
- Author: get-convex
- GitHub username: get-convex
- License: MIT
- Repository: https://github.com/get-convex/agent-skills/tree/main/skills/convex-migration-helper/
- Ref: 30c73eac2afe762f6aa9c4553158769369d47351
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, network
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/get-convex-convex-migration-helper
- Manifest: https://skillstore.pages.dev/api/skills/get-convex-convex-migration-helper/manifest

## Capabilities

- Explains when Convex schema changes require migrations.
- Guides widen-migrate-narrow deployment plans for breaking changes.
- Shows how to use @convex-dev/migrations for batched, resumable migrations.
- Provides examples for adding fields, removing fields, changing types, and splitting tables.
- Includes dry-run, status monitoring, cancellation, and verification guidance.
- Highlights common pitfalls such as large collect calls and premature field deletion.

## Use Cases

- Add Required Fields Safely: Plan a rollout that adds optional fields first, backfills existing documents, then makes fields required after verification.
- Prepare Zero Downtime Rollouts: Design staged deploys where application code handles old and new data formats during migration windows.
- Refactor Existing Data Models: Map steps for field deletion, type changes, table splitting, orphan cleanup, and migration completion checks.

## Prompt Templates

### Identify Migration Need

```
Review this Convex schema change and tell me whether it needs a data migration. Explain the deployment order and main risks.
```

### Plan Required Field Rollout

```
Create a widen-migrate-narrow plan for adding a required field to an existing Convex table. Include verification and rollback notes.
```

### Design Batched Migration

```
Help me design a batched Convex migration with dry run, status monitoring, and safe batch sizing for this table.
```

### Audit Production Rollout

```
Audit this Convex migration plan for production safety. Check schema widening, dual reads or writes, dry run coverage, and completion checks.
```

## Limitations

- Does not connect to a Convex deployment or inspect live data by itself.
- Requires the user to review generated migration logic before running it.
- Examples must be adapted to each app schema, indexes, and production traffic.
- Does not replace backups, dry runs, or staging validation for critical data.

## Best Practices

- Widen the schema before touching production data.
- Run a dry run and inspect status before production execution.
- Verify every document is migrated before narrowing the schema.

## Anti Patterns

- Making a field required before existing documents are backfilled.
- Using collect on large tables instead of a batched migration.
- Deleting legacy fields before readers and writers stop using them.

## Security Audit

- Audited at: 2026-07-05T14:55:33.422\+00:00
- Summary: All static findings were adjudicated as false positives. The apparent SQLite and shell execution findings are Convex ctx.db examples and Markdown backticks in documentation. No prompt injection, data exfiltration intent, or hidden malicious behavior was found in the reviewed skill files.

## Stats

- Views: 88
- Downloads: 9
- Favorites: 0
- Popularity score: 0