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

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:
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.
Auto table creation adds new columns but does not drop or rename existing ones. For destructive schema changes, use Alembic even in development.

​
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:
CommandWhat it does
veloiq db migrate -m "add product table"Generate a new revision file from your current models
veloiq db upgradeApply all pending revisions to the database
veloiq db historyList all revisions in order
veloiq db currentShow the revision the database is currently at

​
Workflow for schema changes

Follow this sequence every time you change a model:
1

Change your models

Edit models.py in the relevant module — add fields, change types, add relations.
2

Regenerate the API and frontend schemas

veloiq generate
This overwrites the generated api.py and TypeScript schema files to match the updated models.
3

Create a new migration revision

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

Apply the migration

veloiq db upgrade
Alembic runs all pending revisions against the database in order.
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.

​
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: 
DATABASE_URL=postgresql://user:password@localhost/mydb
Install the driver:
pip install veloiq-framework[postgres]