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

# Migrations

Migrations are plain SQL files in the `migrations/` directory, run with [sql-migrate](https://github.com/rubenv/sql-migrate). Since they are embedded into your binary, a deployed application carries its own schema history.

### Writing Migrations

Migration files are named sequentially with a short description, such as `0001_initial.sql` and `0002_create_rockets.sql`. Each file has an up and a down section:

```sql migrations/0002_create_rockets.sql theme={null}
-- +migrate Up
CREATE TABLE rockets (
    id         TEXT PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    name       TEXT NOT NULL,
    fuel       BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX idx_rockets_name ON rockets (name);

-- +migrate Down
DROP TABLE IF EXISTS rockets;
```

### Running Migrations

During development, you rarely need to think about migrations since `copper run` applies any pending ones before starting your application. If you would like to skip this, pass `-migrate=false`.

You may also run migrations on their own:

```
copper migrate
```

To roll back, pass the direction:

```
copper migrate -direction=down
```

<Warning>
  `down` reverts only the most recent migration. You may run it again to step back further.
</Warning>

### Migrations in Production

`copper build` compiles a standalone migrator alongside your app:

```
copper build
./build/migrate.out -config config/prod.toml    # apply pending migrations
./build/app.out -config config/prod.toml        # start the app
```

Run the migrator as a deploy step before starting (or restarting) the app.

To roll back the most recent migration, set the direction with `-set`:

```
./build/migrate.out -config config/prod.toml -set 'csql.migrations.direction="down"'
```

The value is parsed as TOML, so the inner quotes matter. All of the `[csql.migrations]` keys are listed in the [Configuration Reference](/reference/configuration).