Create database migration
Create a database migration to add a table, add columns to an existing table, add a setting, or otherwise change the schema of Ghost's MySQL database. Use this skill whenever the task involves modifying Ghost's database schema — including adding, removing, or renaming columns or tables, adding new settings, creating indexes, updating data, or any change that requires a migration file in ghost. Also use when the user references schema.js, knex-migrator, the migrations directory, or asks to "add a field" or "add a column" to any Ghost model/table. Even if the user frames it as a feature or Linear issue, if the implementation requires a schema change, this skill applies.
How do I install this agent skill?
npx skills add https://github.com/tryghost/ghost --skill create-database-migrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides instructions for database migration tasks in the Ghost project, utilizing project-specific shell commands and scripts.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/3 files flagged
What does this agent skill do?
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.
- 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). - The above command will create a new directory in
ghost/core/server/data/migrations/versionsif 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. - 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/*. - 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. - Test the migration manually from the repository root:
pnpm knex-migrator migrate --v {version directory} --force - Roll the migration back to test
down():pnpm knex-migrator rollback --v {previous version} --force, then migrate forward again. - 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, whichpnpm devstarts. - If adding or dropping a table, update
ghost/core/server/data/exporter/table-lists.jsas appropriate. The consistency assertion inghost/test/unit/server/data/exporter/index.test.jschecks that every schema table is classified in the exporter lists. - Run the focused exporter unit test when the table lists change:
cd ghost && pnpm test:single test/unit/server/data/exporter/index.test.js. - 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 - 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tryghost/ghost/create-database-migration">View Create database migration on skillZs</a>