convex-migrations

Schema migration strategies for evolving applications including adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime migration patterns

402stars31forksUpdated 6/18/2026

Database Management #migrations #convex #database #backfill #data-modeling #schema

Security Assessment

Safe(100/100)

Security Score100/100

About convex-migrations

The Convex Migrations skill provides comprehensive strategies for evolving Convex database schemas safely without downtime. Unlike traditional databases that require explicit migration files and commands, Convex handles schema evolution through instant deployments with optional fields and backfill patterns. This skill addresses the critical challenge of modifying production database schemas while maintaining application availability and data integrity.

The skill covers essential migration patterns including adding new fields with optional-to-required transitions, backfilling existing data in batches, removing deprecated fields safely, and managing index changes. It emphasizes Convex's unique approach where schema changes deploy instantly but existing data is not automatically transformed, requiring developers to handle both old and new data formats gracefully during transitions. The skill includes complete code examples for each migration pattern, from schema definitions to backfill mutations with pagination.

This skill is designed for developers building applications on Convex who need to evolve their data models over time. It's particularly valuable for teams managing production systems where schema changes must be executed without service interruptions, data loss, or breaking existing functionality. The patterns support zero-downtime deployments and provide clear step-by-step guidance for complex migration scenarios.

FAQ

How does Convex handle schema migrations differently from traditional databases?

Convex does not use explicit migration files or commands. Schema changes deploy instantly with 'npx convex dev', but existing data is not automatically transformed. You must use optional fields and backfill mutations to safely migrate data while handling both old and new formats in your application code.

What is the recommended pattern for adding a new required field?

Start by adding the field as optional in your schema, update your code to handle both cases (with and without the field), create a backfill mutation to populate the field for existing documents in batches, and finally make the field required in the schema after backfilling completes.

How do I safely remove a deprecated field from my schema?

First, stop using the field in all queries and mutations throughout your codebase. Then remove the field from the schema definition. Since Convex doesn't automatically remove data, existing documents will retain the field, but it won't be validated or typed in new operations.

What is the batch size recommendation for backfill operations?

The skill examples use a batch size of 100 documents per mutation execution. This prevents timeouts while ensuring efficient processing. Use pagination with cursors and the scheduler to process subsequent batches automatically.

Do I need to take my application offline to perform migrations?

No, Convex migrations are designed for zero-downtime deployments. By using optional fields and gracefully handling both old and new data formats in your code, you can perform migrations while your application remains fully operational.