mcpField
C
Create database migration

Create database migration

github.com/tryghostData & databases55.6k87 installsUpdated today
Repository

About Create database migration

Create database migration is an executable checklist for making database migrations in the Ghost repository, paired with canonical human guidance. It covers generation, schema updates, rollback and forward testing, and related checks.

Key features

  1. 01Migration generation procedure
  2. 02Schema synchronization steps
  3. 03Rollback and forward testing
  4. 04Exporter table-list updates
  5. 05Focused migration test guidance

Use cases

  1. 01Adding a database migration in Ghost
  2. 02Updating schema definitions with migrations
  3. 03Verifying rollback and migration behavior

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/tryghost/ghost --skill create-database-migration

After installing, type/create-database-migrationin Claude Code to confirm it loaded.

Bundled filesexamples.mdrules.md

Details

From the project README

Create Database Migration

Read the canonical human guidance in 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 for example migrations.

Rules

See rules.md for rules that should always be followed when creating database migrations.

Comments

Markdown supported