AutoGineer
Generated banner for Convex Migrate
Generated logo for Convex Migrate

Convex Migrate

ConvexOfficialPublished by Convex

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

From the author

Migrate schema + backfill data on a deployed Convex app using @convex-dev/migrations.
— the description by Convex

AutoGineer summary

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

The convex-migrate skill provides a systematic approach to updating database schemas in production environments using the @convex-dev/migrations library. It emphasizes a multi-step process that prevents application downtime by decoupling schema updates from data transformation, ensuring that existing records remain compatible with new requirements throughout the migration lifecycle.

What it does

  • Guides the process of making schema fields optional to prevent deployment errors.
  • Facilitates the installation and configuration of migration tools.
  • Provides a framework for writing backfill scripts to transform legacy data.
  • Outlines verification steps to ensure data integrity after transformations.
  • Instructs on when and how to safely tighten validators for new fields.

When to use it

  • When you need to add a required field to an existing table with data.
  • When changing the data structure of existing rows in a live Convex app.
  • When you want to avoid breaking production apps during schema evolution.

Advantages

  • Prevents application crashes caused by invalid data during schema updates.
  • Ensures a clean transition from optional to required fields.
  • Provides a clear, repeatable procedure for data backfilling.

Usage examples

“How do I add a required field to my users table without breaking the live app?”
The agent will guide you to first add the field as optional, write a migration script to populate the field for existing users, run the migration, and finally update the schema to make the field required.

Install

  1. Download the skill as a ZIP:

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

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

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

Documentation by Convex

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

Migrate the schema / data on a live app

Change a deployed schema without breaking existing data: stage the schema change, install @convex-dev/migrations, write a backfill that makes old rows valid, run it, and verify before tightening the validator.

Workflow

  1. Make the new field optional first (so deploy doesn't reject existing rows).

  2. Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.

  3. Run the migration; verify all rows are valid.

  4. Tighten the validator (make the field required) once the backfill is complete.

Rules

  • Never tighten a validator before the backfill completes — it rejects existing rows and breaks the live app.

  • Add new fields as optional first, migrate, then require.

  • Verify row counts before and after.

Files

SKILL.md

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

Migrate the schema / data on a live app

Change a deployed schema without breaking existing data: stage the schema change, install @convex-dev/migrations, write a backfill that makes old rows valid, run it, and verify before tightening the validator.

Workflow

  1. Make the new field optional first (so deploy doesn't reject existing rows).

  2. Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.

  3. Run the migration; verify all rows are valid.

  4. Tighten the validator (make the field required) once the backfill is complete.

Rules

  • Never tighten a validator before the backfill completes — it rejects existing rows and breaks the live app.

  • Add new fields as optional first, migrate, then require.

  • Verify row counts before and after.

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.

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 · 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.zip