# Convex Migration Helper

Plans Convex schema and data migrations with widen-migrate-narrow and...

- Repository: https://github.com/openclaw/clawhub (9543 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add openclaw/clawhub --skill convex-migration-helper -g -a claude-code -y`
Codex: `npx skills add openclaw/clawhub --skill convex-migration-helper -g -a codex -y`
Cursor: `npx skills add openclaw/clawhub --skill convex-migration-helper -g -a cursor -y`
Gemini CLI: `npx skills add openclaw/clawhub --skill convex-migration-helper -g -a gemini-cli -y`

## Description

Plans Convex schema and data migrations with widen-migrate-narrow and @convex-dev/migrations. Use for breaking schema changes, backfills, table reshaping, or zero-downtime rollouts.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Convex Migration Helper

Safely migrate Convex schemas and data when making breaking changes.

## When to Use

- Adding new required fields to existing tables
- Changing field types or structure
- Splitting or merging tables
- Renaming or deleting fields
- Migrating from nested to relational data

## When Not to Use

- Greenfield schema with no existing data in production or dev
- Adding optional fields that do not need backfilling
- Adding new tables with no existing data to migrate
- Adding or removing indexes with no correctness concern
- Questions about Convex schema design without a migration need

## Key Concepts

### Schema Validation Drives the Workflow

Convex will not let you deploy a schema that does not match the data at rest.
This is the fundamental constraint that shapes every migration:

- You cannot add a required field if existing documents don't have it
- You cannot change a field's type if existing documents have the old type
- You cannot remove a field from the schema if existing documents still have it

This means migrations follow a predictable pattern: **widen the schema, migrate
the data, narrow the schema**.

### Online Migrations

Convex migrations run online, meaning the app continues serving requests while
data is updated asynchronously in batches. During the migration window, your
code must handle both old and new data formats.

### Prefer New Fields Over Changing Types

When changing the shape of data, create a new field rather than modifying an
existing one. This makes the transition safer and easier to roll back.

### Don't Delete Data

Unless you are certain, prefer deprecating fields over deleting them. Mark the
field as `v.optional` and add a code comment explaining it is deprecated and why
it existed.

## Safe Changes (No Migration Needed)

### Adding Optional Field

```typescript
// Before
users: defineTable({
  name: v.string(),
});

The rest: https://github.com/openclaw/clawhub/blob/HEAD/.agents/skills/convex-migration-helper/SKILL.md