Migrations and schema delivery

Generate, review, apply, revert, and automate PocketBase schema migrations across environments.

Use migrations to deliver collection and database changes as reviewable files. The migratecmd plugin adds a migrate command, supports Go or JavaScript templates, and can optionally create migrations automatically when collections change.

Before you begin

Choose one migration language, commit its directory with the application, and take a verified backup before changing shared or production data. Test against a disposable copy first. Set Dir explicitly when the repository layout must be stable. Record the target environment, migration language, and commit that will be promoted; the process applying the change needs access to the target database.

Register migration support

Register the plugin with the application root command. Go is the default template language; select JavaScript when JSVM migration support is enabled.

migratecmd.MustRegister(app, app.RootCmd, migratecmd.Config{
  TemplateLang: migratecmd.TemplateLangGo,
  Dir: "migrations",
  Automigrate: false,
})

Create and review a migration

Create a blank migration.

bash

   pocketbase migrate create add_status_to_messages

A timestamped file appears in the configured directory.

Generate a collection snapshot when the schema change comes from local collection configuration.

bash

   pocketbase migrate collections

Remove unrelated changes and review schema and data operations before committing.

Apply the committed migration in a disposable environment.

bash

   pocketbase migrate up

Verify fields, indexes, rules, and representative records before promoting the same commit.

⚠️Do not edit an already-applied migration. Create a new migration so every environment follows the same history.

Revert or synchronize history

After checking the down operation and taking a backup, revert the most recent migration:

bash

pocketbase migrate down 1

Use history-sync when migration files were intentionally removed and migration history must no longer reference them. This is repository maintenance, not a rollback plan.

Deliver across environments

Promote the application and migration files together. Apply migrate up once per environment, inspect the result, and record the migration version. If a migration fails, preserve the error and database state; restore from a verified backup only when the rollback procedure requires it, and fix forward with a new migration when possible.

✅Delivery is complete when the same committed set is applied and schema and data checks pass in the next environment.

Troubleshoot delivery

If the migrate command is unavailable, check that migratecmd.MustRegister is called for the application root command and rebuild the application. If a generated collection snapshot contains unrelated changes, remove those changes before committing. If an applied migration needs correction, leave the original file unchanged and create a new migration so every environment follows the same ordered history.

Next steps

Continue with Go migrations and extension testing, JavaScript migrations, and Backups and restore.