> ## Documentation Index
> Fetch the complete documentation index at: https://wlumsa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
pnpm payload migrate
```

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

```bash theme={null}
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 |

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

## 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.