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

<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
};
```

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.

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