create-database-migration

# Create Database Migration Read the canonical human guidance in [`docs/practices/database-migrations.md`](../../../docs/practices/database-migrations.md) before making a migration. This skill is the executable checklist that accompanies it. ## Instructions If you are adding a new table whose shape is still changing, consider marking it as in development instead of writing a migration yet; see "New tables still in development" in the guide. 1. Create a new, empty migration file: `pnpm gx generate migration <kebab-case-slug>` from the repository root. IMPORTANT: do not create the migration file manually; always use this script to create the initial empty migration file. The slug must be kebab-case (e.g. `add-column-to-posts`). 2. The above command will create a new directory in `ghost/core/server/data/migrations/versions` if needed, create the empty migration file with the appropriate name, and bump the core and admin package versions to RC if this is the first migration after a release. 3. Update the migration file with the changes you want to make in the database, following the existing patterns in the codebase. Where appropriate, prefer to use the utility functions in `ghost/core/server/data/migrations/utils/*`. 4. Update the schema definition file in `ghost/core/server/data/schema/schema.js`, and make sure it aligns with the latest changes from the migration. 5. Test the migration manually from the repository root: `pnpm knex-migrator migrate --v {version directory} --force` 6. Roll the migration back to test `down()`: `pnpm knex-migrator rollback --v {previous version} --force`, then migrate forward again. 7. Run the migration integration test, which covers initialization, rollback, forward migration, and idempotency: `cd ghost && pnpm test:single test/integration/migrations/migration.test.js`. It needs MySQL running, which `pnpm dev` starts. 8. If adding or dropping a table, update `ghost/core/server/data/exporter/table-lists.js` as appropriate. The consistency assertion in `ghost/test/unit/server/data/exporter/index.test.js` checks that every schema table is classified in the exporter lists. 9. Run the focused exporter unit test when the table lists change: `cd ghost && pnpm test:single test/unit/server/data/exporter/index.test.js`. 10. For schema changes, run the schema-sync test: `cd ghost && pnpm test:single test/integration/migrations/schema-sync.test.ts`. For changes to fixtures, default settings, or default routes, run the database integrity test and update only the affected hash: `cd ghost && pnpm test:single test/unit/server/data/schema/integrity.test.ts` 11. Run unit tests in Ghost core, and iterate until they pass: `cd ghost && pnpm test:unit` ## Examples See [examples.md](examples.md) for example migrations. ## Rules See [rules.md](rules.md) for rules that should always be followed when creating database migrations.