Skip to main content

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

SubcommandDescription
veloiq db upgradeApply 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 historyShow full revision history
veloiq db currentShow 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. 
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. 
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. 
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. 
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. 
veloiq db history

​
veloiq db current

Shows which revision is currently applied to the database, along with whether the database is at head. 
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. 
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: 
# backend/app/main.py
app = create_veloiq_app(VeloIQConfig(
    create_tables_on_startup=False,
    ...
))
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: 
# 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
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.