Database Migrations¶
Numi uses SQLite (chats.db by default) and manages schema changes with Alembic
(migrations/). Run migration commands from the repository root using the same
DB_URL as the instance you are updating.
Applying migrations on an existing instance¶
Startup automatically applies pending migrations
(src/numi_chat/data/migrations.py), so always back up your database before
starting an updated version of the server:
- Stop the application and any other processes accessing the database.
- Create a complete SQLite backup (including any
-walsidecar data if present). - Inspect and apply pending revisions:
- Start the application and verify that an existing account can open its chats and files.
For Docker Compose deployments (./chats.db on the host is mounted at
/app/state/chats.db in the container):
Rolling back one revision¶
Review the target migration's downgrade() implementation in
migrations/versions/ before running:
Note that rolling back a revision can drop columns or tables added in that revision; always keep a file backup first.
Creating a new schema migration (for contributors)¶
- Update the SQLModel table definition in
src/numi_chat/data/models.py(loaded viasrc/numi_chat/data/db.pyinmigrations/env.py). - Upgrade a disposable test database to
headand autogenerate the new revision against it:
DB_URL="sqlite:///migration-check.db" uv run alembic upgrade head
DB_URL="sqlite:///migration-check.db" uv run alembic revision --autogenerate -m "Describe the schema change"
- Inspect the generated script in
migrations/versions/. Check nullable columns, server defaults, indexes, foreign keys, and SQLitebatch_alter_tableoperations. - Run the migration test suite to verify upgrades from older revisions with populated rows:
- Remove the disposable
migration-check.dbfile when finished, and update Database Schema Reference in the same commit.