playbooks

home / skills / nilecui / skillsbase / create-database-migration

create-database-migration skill

/.cursor/skills/create-database-migration

This skill guides you through creating and applying Ghost MySQL migrations using slimer, ensuring schema changes are consistent and testable.

npx playbooks add skill nilecui/skillsbase --skill create-database-migration

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.7 KB
---
name: Create database migration
description: 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.
---

# Create Database Migration

## Instructions

1. Change directories into `ghost/core`: `cd ghost/core`
2. Create a new, empty migration file using slimer: `slimer migration <name-of-database-migration>`. IMPORTANT: do not create the migration file manually; always use slimer to create the initial empty migration file.
3. The above command will create a new directory in `ghost/core/core/server/data/migrations/versions` if needed, and create the empty migration file with the appropriate name.
4. 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/core/server/data/migrations/utils/*`.
5. Update the schema definition file in `ghost/core/core/server/data/schema/schema.js`, and make sure it aligns with the latest changes from the migration.
6. Test the migration manually: `yarn knex-migrator migrate --v {version directory} --force`
7. If adding or dropping a table, update `ghost/core/core/server/data/exporter/table-lists.js` as appropriate.
8. Run the schema integrity test, and update the hash: `yarn test:single test/unit/server/data/schema/integrity.test.js`
9. Run unit tests in Ghost core, and iterate until they pass: `cd ghost/core && yarn 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.

Overview

This skill creates a Ghost MySQL database migration to add tables, modify existing tables, add settings, or otherwise change the schema. It guides you through using the slimer command to generate a migration skeleton, updating migration code and schema definitions, and validating changes with tests. The workflow enforces existing patterns and utilities to keep migrations consistent and safe.

How this skill works

Use slimer to generate an empty migration file in the correct versions directory, then implement schema changes by editing that migration and the project's schema definition. Leverage provided migration utilities and follow existing code patterns. Validate changes by running the migrator, updating the schema integrity hash, and executing unit tests until everything passes.

When to use it

  • Adding a new table to the Ghost MySQL schema.
  • Adding or removing columns from an existing table.
  • Introducing a new configuration setting that requires a schema change.
  • Refactoring schema layout that requires data transformations.
  • Preparing a schema change that must be included in a release.

Best practices

  • Always create the migration file with slimer; do not create files manually.
  • Follow existing migration patterns and use utility functions found in data/migrations/utils.
  • Keep schema.js in sync with migration changes and update the schema integrity hash after edits.
  • Test migrations manually with the knex-migrator before committing.
  • Update table lists used by the exporter when adding or removing tables.
  • Run the full unit test suite and iterate until all tests pass.

Example use cases

  • Add a new 'newsletter_subscriptions' table and populate it with initial settings.
  • Add a nullable 'bio' column to the 'users' table and backfill data in the migration.
  • Create a migration to drop an unused table and update the exporter table lists accordingly.
  • Introduce a new site setting that requires a schema column and update schema.js.
  • Refactor a composite column into two separate columns with a safe data transformation step.

FAQ

What command creates the initial migration file?

Run slimer migration <name-of-database-migration> from ghost/core; slimer generates the empty file in the correct versions directory.

Can I create the migration file manually?

No. Always use slimer to ensure correct naming and placement of the migration file.

How do I test the migration locally?

Run yarn knex-migrator migrate --v {version-directory} --force to apply the migration, then run the schema integrity test and unit tests (yarn test:unit) until they pass.

What else must I update when adding or dropping a table?

Update the exporter table-lists.js and the schema.js file, then update the integrity hash and run tests.