skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
serverpod/serverpod64 installs

serverpod-migrations

Serverpod database migrations — when and how to create/apply/repair migrations. Use whenever database schema changes are involved.

How do I install this agent skill?

npx skills add https://github.com/serverpod/serverpod --skill serverpod-migrations
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides standard procedures for managing Serverpod database migrations using the framework's official CLI and MCP tools. No malicious behaviors or security risks were detected.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Serverpod Migrations

Serverpod has a migration system that generates SQL for changes to models with table in .spy.yaml. The migrations are applied:

  • When the apply_migrations tool is called via the serverpod MCP. Typically during development with the Serverpod runner running (serverpod start or serverpod runner start).
  • When the server is started with dart run bin/main.dart --apply-migrations flag. Typically when running the server in production.

When migrations are needed

  • Added, removed, or renamed table models or fields in .spy.yaml.
  • Changed relation fields that alter generated foreign keys.
  • Added, removed, or changed indexes.

Migrations are not needed when the project has no database configured (e.g. config/<runMode>.yaml with no database section).

Standard flow

The standard flow for creating and applying migrations is simplified when the runner is running.

With a running runner and MCP server

When the server is running under the runner use the serverpod MCP to:

  1. Create a migration using the create_migration tool.
  2. Apply the migration using the apply_migrations tool.

ALWAYS use the MCP server if it is available. When it reports that the server is not running, call tail_runner_logs, then run serverpod runner start in the server package when no runner is running, then call the tools again.

ONLY if the MCP is not available or the runner cannot bring the server up

When the MCP is not available or serverpod runner start fails, use the CLI commands to:

  1. Ensure the code is generated by running serverpod generate.
  2. Create a migration using the serverpod create-migration command.

Editing a generated migration

A migration directory holds migration.sql, definition.sql and the definition.json, definition_project.json and migration.json files.

migration.sql MAY be edited by hand after it is created. Two common reasons:

  • Adding a data transformation, so existing rows are migrated along with the schema.
  • Turning a destructive change into a non-destructive one, by reaching the same end state through intermediate steps — for example add the new column, backfill it from the old one, then drop the old column, instead of dropping and recreating.

Never edit the other files in the directory. definition.sql is the full schema, and the *.json files are what the next serverpod create-migration diffs against, so changing them corrupts every migration created afterwards.

Two rules follow from how migrations are applied:

  • A database that has no migrations installed is created from the latest definition.sql alone and never runs migration.sql. An existing database applies each newer migration.sql in order. So the schema an edited migration.sql ends up with must stay identical to definition.sql, and data transformations in it only affect databases that upgrade through that version.
  • Editing a migration that has already been applied does nothing to the databases that ran it. Create a new migration for those.

On the client side (models with database: client or database: all), the same applies to the migration SQL inside the version's migration.dart; its definition SQL and JSON files are equally off limits.

Repair migrations

If the database is in an inconsistent state, a repair migration brings it back to a consistent state. It is created by reading the live schema and diffing it against a target migration version, so the database must be reachable.

With a running runner and MCP server

  1. Create the repair migration using the create_repair_migration tool. Optional arguments: version (target migration version, defaults to the latest), tag, and force (required for destructive changes, or when no drift is detected).
  2. Apply it using the apply_migrations tool, which applies both pending and repair migrations without restarting the server.

ALWAYS use the MCP server if it is available. When it reports that the server is not running, call tail_runner_logs, then run serverpod runner start when no runner is running, then call the tools again.

ONLY if the MCP is not available or the runner cannot bring the server up

# Use the `--mode` flag to specify the run mode
# Use the `--version` flag to specify the target version
# Use the `--force` flag to create a migration with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-repair-migration [--mode production] [--version <name>] [--force] [--tag <tag>]

Apply the repair migration by restarting the server with dart run bin/main.dart --apply-repair-migration. Ask the user to run this command.

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/serverpod/serverpod/serverpod-migrations">View serverpod-migrations on skillZs</a>