Payload exposes a full suite of migration controls available for your use. Migration commands are accessible via the npm run payload command in your project directory.

Ensure you have an npm script called "payload" in your package.json file.

1{
2  "scripts": {
3    "payload": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload"
4  }
5}

Migration file contents

Payload stores all created migrations in a folder that you can specify. By default, migrations are stored in ./src/migrations.

A migration file has two exports - an up function, which is called when a migration is executed, and a down function that will be called if for some reason the migration fails to complete successfully. The up function should contain all changes that you attempt to make within the migration, and the down should ideally revert any changes you make.

For an added level of safety, migrations should leverage Payload transactions. Migration functions should make use of the req by adding it to the arguments of your payload local API calls such as payload.create and database adapter methods like payload.db.create.

Here is an example migration file:

1import { MigrateUpArgs, MigrateDownArgs } from '@payloadcms/your-db-adapter'
2
3export async function up ({ payload, req }: MigrateUpArgs): Promise<void> {
4  // Perform changes to your database here.
5  // You have access to `payload` as an argument, and
6  // everything is done in TypeScript.
7};
8
9export async function down ({ payload, req }: MigrateDownArgs): Promise<void> {
10  // Do whatever you need to revert changes if the `up` function fails
11};

Migrations Directory

Each DB adapter has an optional property migrationDir where you can override where you want your migrations to be stored/read. If this is not specified, Payload will check the default and possibly make a best effort to find your migrations directory by searching in common locations ie. ./src/migrations, ./dist/migrations, ./migrations, etc.

All database adapters should implement similar migration patterns, but there will be small differences based on the adapter and its specific needs. Below is a list of all migration commands that should be supported by your database adapter.

1npm run payload migrate:create optional-name-here

Status

The migrate:status command will check the status of migrations and output a table of which migrations have been run, and which migrations have not yet run.

payload migrate:status

1npm run payload migrate:status

Down

Roll back the last batch of migrations.

1npm run payload migrate:down

Refresh

Roll back all migrations that have been run, and run them again.

1npm run payload migrate:refresh

Reset

Roll back all migrations.

1npm run payload migrate:reset

Fresh

Drops all entities from the database and re-runs all migrations from scratch.

1npm run payload migrate:fresh

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Migrations

Migration file contents

Migrations Directory

Commands

Migrate

Create

Status

Down

Refresh

Reset

Fresh

Transactions

On this page