Skip to main content
veloiq db is a thin wrapper around Alembic 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

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

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

​
veloiq db history

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

​
veloiq db current

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

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

​
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:
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.

​
Standard workflow

Follow this sequence every time you change a model:
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.