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.
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.
Here is an example migration file:
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/igrations
, ./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.
The migrate
command will run any migrations that have not yet been run.
Create a new migration file in the migrations directory. You can optionally name the migration that will be created. By default, migrations will be named using a timestamp.
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
Roll back the last batch of migrations.
Roll back all migrations that have been run, and run them again.
Roll back all migrations.
Drops all entities from the database and re-runs all migrations from scratch.