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.
pocketbase migrate create add_status_to_messagesA timestamped file appears in the configured directory.
- Generate a collection snapshot when the schema change comes from local collection configuration.
pocketbase migrate collectionsRemove unrelated changes and review schema and data operations before committing.
- Apply the committed migration in a disposable environment.
pocketbase migrate upVerify fields, indexes, rules, and representative records before promoting the same commit.
Revert or synchronize history
After checking the down operation and taking a backup, revert the most recent migration:
pocketbase migrate down 1Use 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.
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.