Database migrations

How Payload CMS database migrations work and when to run them

Payload CMS auto-generates database migrations whenever you change a collection or global schema. Migration files live in wlumsa.org/src/migrations/ and are checked into the repository.

How migrations work

When you add, rename, or remove a field in a collection or global, Payload detects the schema diff and generates a TypeScript migration file. That file contains the SQL to bring the database schema in line with your updated Payload config.

Migrations are not applied automatically — you run them explicitly.

Commands

Generate a migration after changing a collection or global schema:

pnpm payload migrate:create

This creates a new timestamped file in src/migrations/. Review the generated SQL before committing it.

Run pending migrations to apply them to the database:

pnpm payload migrate

Check migration status to see which migrations have and have not been applied:

pnpm payload migrate:status

When to run migrations

Situation	What to do
You changed a collection or global schema locally	Generate a migration, review it, commit the file
You pulled changes that include new migration files	Run migrate against your local database
Deploying to production	Payload runs pending migrations automatically on startup when PAYLOAD_MIGRATE is set, or you run them manually before deploy

Check with a maintainer before running migrations against the production database. Always test against a local or staging database first.

What can go wrong

Migration fails mid-run — the database may be left in a partial state. Check the error output, fix the underlying cause (usually a schema conflict), and re-run. You may need to roll back manually if data was affected.

Generated migration is empty — this usually means Payload did not detect a schema change. Confirm your collection file was saved and the config imports the updated collection.

Conflicting migrations on a feature branch — if your branch and main both added migrations, you may need to squash or reorder them. Coordinate with maintainers before merging.

Forgetting to commit migration files — if you apply a migration locally but do not commit the file, other developers and production will be out of sync. Always commit migration files alongside the schema changes that created them.