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

# Overview

> Apply versioned, transactional schema changes to your database with up/down rollbacks and dependency ordering.

The `@talosjs/migrations` package is a database migration runner for Bun's native SQL client. A migration is a class implementing `IMigration` with `up` and `down` methods, a timestamp-based version, and an optional dependency list. Migrations are registered with a decorator, sorted by version, and run inside a transaction. Applied versions are tracked in a database table so each one runs exactly once.

## How migrations behave

Every migration carries a timestamp version (`YYYYMMDDHHMMSSMMM`), and the runner sorts by version before applying migrations in order. The `up()` method applies a change and `down()` reverses it, which keeps schema changes symmetric and reviewable. Each migration runs inside `sql.begin()`, so a failure rolls back the whole migration and stops the run. Applied versions are recorded in a tracking table (default `migrations`), and anything already applied is skipped on the next run.

A migration can also declare other migrations as dependencies, and those run first regardless of timestamp. As with the rest of the framework, you register a migration class with a decorator and the runner resolves it from the container.

## The `IMigration` contract

A migration is a class that satisfies `IMigration` from `@talosjs/migrations`:

```typescript theme={null}
export interface IMigration {
  up: (tx: TransactionSQL, sql: SQL) => Promise<void>;
  down: (tx: TransactionSQL, sql: SQL) => Promise<void>;
  getVersion: () => string;
  getDependencies: () => Promise<MigrationClassType[]> | MigrationClassType[];
}
```

| Member              | Purpose                                                                                |
| ------------------- | -------------------------------------------------------------------------------------- |
| `up(tx, sql)`       | Apply the schema change. Runs inside a transaction (`tx`); `sql` is the pooled client. |
| `down(tx, sql)`     | Reverse the schema change: drop exactly what `up` added.                               |
| `getVersion()`      | Return the timestamp version string; used for ordering and tracking.                   |
| `getDependencies()` | Return the migration classes that must run before this one.                            |

## The tracking table

The runner records one row per applied version in a tracking table (default `migrations`, `id VARCHAR(20) PRIMARY KEY`), creating it if it is missing. Before running a migration, the runner checks the table for its `id`; if it is already there, the migration is skipped. Rolling a migration back deletes its row, so a later [`migration:up`](/migrations/running) re-applies it.

## Environment variables

| Variable       | Required                                       | Purpose                                                                                         |
| -------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | Yes (unless `databaseUrl` is passed in config) | Postgres connection string used by the runner, e.g. `postgres://user:pass@localhost:5432/mydb`. |

```bash theme={null}
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
```

## Next steps

* [Writing migrations](/migrations/writing): scaffold a migration and implement `up()`, `down()`, and dependency ordering.
* [Running migrations](/migrations/running): apply pending migrations across every module with `talos migration:up`.
* [Rolling back](/migrations/rollback): reverse an applied migration with `talos migration:down`.
* [Caching](/migrations/caching): how the per-version run cache skips unchanged migrations.
* [`@talosjs/migrations` component](/components/migrations): the full package reference.