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

# Manage Database Migrations in VeloIQ with Alembic

> Manage schema changes safely in VeloIQ using Alembic migrations via the veloiq db command — create revisions, apply upgrades, and track history.

VeloIQ pre-wires Alembic into every generated project so you have a migration tool ready whenever you need it. During development, the framework can create database tables automatically on startup — no migration step required. For production, disable that behaviour and use Alembic migrations to track and apply schema changes safely.

## Development vs production

<Tabs>
  <Tab title="Development">
    By default, `create_tables_on_startup` is `True`. The framework calls `SQLModel.metadata.create_all()` when the backend starts, creating any missing tables. This is the fastest way to get started:

    ```python theme={null}
    from veloiq_framework import create_veloiq_app
    app = create_veloiq_app()
    ```

    No migration commands needed. Add fields to your models, restart the backend, and the tables update automatically.

    <Note>
      Auto table creation adds new columns but does not drop or rename existing ones. For destructive schema changes, use Alembic even in development.
    </Note>
  </Tab>

  <Tab title="Production">
    Disable auto table creation and manage all schema changes through Alembic revisions:

    ```python theme={null}
    app = create_veloiq_app(VeloIQConfig(
        create_tables_on_startup=False,
    ))
    ```

    With this setting in place, the framework never touches the schema at startup. All changes go through the `veloiq db` workflow described below.
  </Tab>
</Tabs>

## Run Alembic commands via `veloiq db`

VeloIQ wraps the most common Alembic commands under `veloiq db` so you do not need to configure Alembic directly:

| Command                                    | What it does                                          |
| ------------------------------------------ | ----------------------------------------------------- |
| `veloiq db migrate -m "add product table"` | Generate a new revision file from your current models |
| `veloiq db upgrade`                        | Apply all pending revisions to the database           |
| `veloiq db history`                        | List all revisions in order                           |
| `veloiq db current`                        | Show the revision the database is currently at        |

## Workflow for schema changes

Follow this sequence every time you change a model:

<Steps>
  <Step title="Change your models">
    Edit `models.py` in the relevant module — add fields, change types, add relations.
  </Step>

  <Step title="Regenerate the API and frontend schemas">
    ```bash theme={null}
    veloiq generate
    ```

    This overwrites the generated `api.py` and TypeScript schema files to match the updated models.
  </Step>

  <Step title="Create a new migration revision">
    ```bash theme={null}
    veloiq db migrate -m "describe your change here"
    ```

    Alembic compares your models to the current database schema and writes a revision file with the necessary `ALTER TABLE` (or equivalent) statements.
  </Step>

  <Step title="Apply the migration">
    ```bash theme={null}
    veloiq db upgrade
    ```

    Alembic runs all pending revisions against the database in order.
  </Step>
</Steps>

<Warning>
  Do not edit the generated `api.py` before running `veloiq db migrate`. The generator reads your models to produce the revision — if `api.py` is out of sync with `models.py`, the generated revision may be incomplete or incorrect.
</Warning>

## Supported databases

VeloIQ works with any SQLAlchemy-compatible database. Set the `DATABASE_URL` environment variable (or pass `database_url` to `VeloIQConfig`) to the connection string for your database:

<Tabs>
  <Tab title="PostgreSQL">
    ```bash theme={null}
    DATABASE_URL=postgresql://user:password@localhost/mydb
    ```

    Install the driver:

    ```bash theme={null}
    pip install veloiq-framework[postgres]
    ```
  </Tab>

  <Tab title="MySQL">
    ```bash theme={null}
    DATABASE_URL=mysql+pymysql://user:password@localhost/mydb
    ```

    Install the driver:

    ```bash theme={null}
    pip install pymysql
    ```
  </Tab>

  <Tab title="SQLite">
    ```bash theme={null}
    DATABASE_URL=sqlite:///./app.db
    ```

    No additional driver needed — SQLite support is built into Python.
  </Tab>
</Tabs>