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

# veloiq db: Alembic Database Migration Commands

> The veloiq db command wraps Alembic to create revisions, apply upgrades, and inspect migration history for your VeloIQ application.

`veloiq db` is a thin wrapper around [Alembic](https://alembic.sqlalchemy.org/) that locates your project's `alembic.ini`, loads your `.env` file, and runs the corresponding Alembic sub-command in the correct directory. You do not need to invoke `alembic` directly — `veloiq db` handles path detection and environment loading for you. Run all `veloiq db` commands from your project root or from the `backend/` directory.

## Subcommands

| Subcommand                       | Description                                                         |
| -------------------------------- | ------------------------------------------------------------------- |
| `veloiq db upgrade`              | Apply all pending Alembic migrations                                |
| `veloiq db migrate -m "message"` | Auto-generate a new revision from model changes                     |
| `veloiq db downgrade <revision>` | Revert to an earlier revision                                       |
| `veloiq db stamp [revision]`     | Mark the database as being at a revision without running migrations |
| `veloiq db history`              | Show full revision history                                          |
| `veloiq db current`              | Show the currently applied revision                                 |

## Detailed usage

### `veloiq db upgrade`

Applies every pending migration up to `head`. Run this after creating a new revision or after pulling changes that include new migration files.

```bash theme={null}
veloiq db upgrade
```

On a fresh project, this command creates all tables defined by your models. On subsequent runs it applies only the revisions that have not yet been applied to the database.

### `veloiq db migrate`

Compares your SQLModel definitions against the current database schema and auto-generates a new Alembic revision file. The `-m` flag is required and should describe the change.

```bash theme={null}
veloiq db migrate -m "add sku field to product"
veloiq db migrate -m "create orders table"
```

After generating a revision, review the file created under `backend/alembic/versions/` to confirm it captures your intended changes, then apply it with `veloiq db upgrade`.

### `veloiq db downgrade`

Reverts the database to an earlier revision. Pass a relative offset (`-1`, `-2`) or an absolute revision identifier.

```bash theme={null}
veloiq db downgrade -1        # roll back one step
veloiq db downgrade base      # roll back everything
veloiq db downgrade abc123    # roll back to a specific revision ID
```

### `veloiq db stamp`

Marks the database as being at a given revision without executing any migration SQL. Useful when you have an existing database that predates Alembic tracking and you want to bring it under migration management without re-running historical migrations.

```bash theme={null}
veloiq db stamp               # marks current schema as 'head'
veloiq db stamp abc123        # marks as a specific revision
```

### `veloiq db history`

Prints the full list of revisions with their IDs, descriptions, and branch labels.

```bash theme={null}
veloiq db history
```

### `veloiq db current`

Shows which revision is currently applied to the database, along with whether the database is at `head`.

```bash theme={null}
veloiq db current
```

## Environment file

All `veloiq db` subcommands accept an `--env-file` option that controls which file is loaded for environment variables (default: `.env`). The command searches for the file at the path you provide, then under `backend/`, so the same invocation works from both the project root and the `backend/` directory.

```bash theme={null}
veloiq db upgrade --env-file .env.production
```

## Disabling automatic table creation

By default, VeloIQ creates tables on startup if they do not exist. When you adopt Alembic migrations, disable this behavior so that the migration history remains the single source of truth for your schema:

```python theme={null}
# backend/app/main.py
app = create_veloiq_app(VeloIQConfig(
    create_tables_on_startup=False,
    ...
))
```

<Note>
  Set `create_tables_on_startup=False` before running your first `veloiq db upgrade` in any environment where you want Alembic to own the schema. Leaving it enabled in development is fine for rapid prototyping.
</Note>

## Standard workflow

Follow this sequence every time you change a model:

```bash theme={null}
# 1. Edit backend/app/modules/<module>/models.py

# 2. Regenerate API and TypeScript schemas
veloiq generate

# 3. Auto-generate the Alembic revision
veloiq db migrate -m "describe the schema change"

# 4. Apply the migration
veloiq db upgrade
```

<Tip>
  Always run `veloiq generate` before `veloiq db migrate`. The migration is generated by comparing your live SQLModel classes against the database — if the generated `api.py` is stale it may not import correctly, causing the autogenerate step to miss changes.
</Tip>