# Create Migration

> Create a new database migration file for the OWID MySQL database. Use when the user needs to create a database schema change or migration.

- Skill: `owid/create-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add owid/create-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/owid/create-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: owid (https://skillmd.com/u/owid)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/owid/create-migration

---


# Create Database Migration

Create a new database migration file for the OWID MySQL 8 database.

## Steps

1. Run `yarn createDbMigration db/migration/<NewMigrationName>` where `<NewMigrationName>` is a descriptive name for the migration
2. The generated filename will contain a timestamp prefix, so scan the `db/migration/` directory to find the actual path of the new file
3. Report the new file path to the user

## Naming Guidelines

Choose a descriptive name for the migration that clearly indicates what schema change is being made (e.g., `AddUserEmailIndex`, `CreateAuditLogTable`, `RemoveDeprecatedColumns`).

## Writing the Migration

Read [db/readme.md](../../../db/readme.md) before populating the file. In particular: use past migrations in `db/migration/` as reference, and always write a **down** migration in case the change needs to be reverted.

## After Writing the Migration

Follow the checklist in [db/migration/CLAUDE.md](../../../db/migration/CLAUDE.md): recreate any views referencing modified columns, update the DB type definitions in `packages/@ourworldindata/types/src/dbTypes/`, update the table docs in `db/docs/`, and tell the user the owid/etl and owid/analytics repositories may need adjusting.