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

# Rolling back

> Reverse applied migrations with talos migration:down.

Roll back applied migrations with `talos migration:down`. The command runs each module's `bin/migration/down.ts` script from the module's own directory. Each rollback runs the migration's `down()` inside a transaction and removes its row from the `migrations` table, so a later [`migration:up`](/migrations/running) re-applies it.

```bash theme={null}
# Roll back the most recently applied migration
talos migration:down

# Roll back the single migration with this version
talos migration:down --version=20240101120000
```

| Option      | Description                                                                                              | Default |
| ----------- | -------------------------------------------------------------------------------------------------------- | ------- |
| `--version` | Version of the migration to roll back. When omitted, the most recently applied migration is rolled back. | latest  |

## How a rollback proceeds

The runner reads the applied versions from the tracking table and rolls back in reverse order of application (newest first). Without `--version`, it rolls back only the single most recently applied migration. With `--version`, it targets the one migration whose `getVersion()` matches; if that version is not applied, the command reports it and exits without changes.

For each target, the runner opens a transaction, runs the migration's `down()`, and deletes the version's row from the tracking table. Both happen in the same transaction, so a failed `down()` rolls back cleanly and leaves the tracking row intact.

## Running `down()` directly

Outside the CLI you can call `down()` from `@talosjs/migrations`. It reads `DATABASE_URL` and uses the default `migrations` table by default, or takes an explicit connection string, table name, and version:

```typescript theme={null}
import { down } from "@talosjs/migrations";

// Roll back the most recently applied migration
await down();

// Roll back a specific version against an explicit database
await down({
  databaseUrl: "postgres://user:pass@localhost:5432/mydb",
  version: "20240101120000",
});
```

<Note>
  Rolling back relies on a correct `down()`. If `down()` does not exactly reverse `up()`, prefer adding a new corrective migration over a rollback on shared data.
</Note>

See the [`migration:down` command](/cli/commands/migration-down) for the full reference.

## Next steps

* [Running migrations](/migrations/running): re-apply a rolled-back migration with `talos migration:up`.
* [Caching](/migrations/caching): a rollback also drops the migration's cache entry so the next run re-applies it.