114 lines
3.5 KiB
Plaintext
114 lines
3.5 KiB
Plaintext
---
|
|
title: Migrations
|
|
label: Migrations
|
|
order: 20
|
|
keywords: database, migrations, ddl, sql, mongodb, postgres, documentation, Content Management System, cms, headless, typescript, node, react, express
|
|
desc: Payload features first-party database migrations all done in TypeScript.
|
|
---
|
|
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"payload": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload"
|
|
}
|
|
}
|
|
```
|
|
|
|
<Banner>
|
|
Note that you need to run Payload migrations through the package manager that you are using, because Payload should not be globally installed on your system.
|
|
</Banner>
|
|
|
|
### 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](/docs/database/transactions).
|
|
|
|
Here is an example migration file:
|
|
|
|
```ts
|
|
import { MigrateUpArgs, MigrateDownArgs } from '@payloadcms/your-db-adapter'
|
|
|
|
export async function up({ payload }: MigrateUpArgs): Promise<void> {
|
|
// Perform changes to your database here.
|
|
// You have access to `payload` as an argument, and
|
|
// everything is done in TypeScript.
|
|
};
|
|
|
|
export async function down({ payload }: MigrateDownArgs): Promise<void> {
|
|
// Do whatever you need to revert changes if the `up` function fails
|
|
};
|
|
```
|
|
|
|
### 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.
|
|
|
|
## Commands
|
|
|
|
### Migrate
|
|
|
|
The `migrate` command will run any migrations that have not yet been run.
|
|
|
|
```text
|
|
npm run payload migrate
|
|
```
|
|
|
|
### Create
|
|
|
|
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.
|
|
|
|
```text
|
|
npm 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`
|
|
|
|
```text
|
|
npm run payload migrate:status
|
|
```
|
|
|
|
### Down
|
|
|
|
Roll back the last batch of migrations.
|
|
|
|
```text
|
|
npm run payload migrate:down
|
|
```
|
|
|
|
### Refresh
|
|
|
|
Roll back all migrations that have been run, and run them again.
|
|
|
|
```text
|
|
npm run payload migrate:refresh
|
|
```
|
|
|
|
### Reset
|
|
|
|
Roll back all migrations.
|
|
|
|
```text
|
|
npm run payload migrate:reset
|
|
```
|
|
|
|
### Fresh
|
|
|
|
Drops all entities from the database and re-runs all migrations from scratch.
|
|
|
|
```text
|
|
npm run payload migrate:fresh
|
|
```
|