Skip to content

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:

  1. Stop the application and any other processes accessing the database.
  2. Create a complete SQLite backup (including any -wal sidecar data if present).
  3. Inspect and apply pending revisions:
make db-current
make db-history
make db-migrate
make db-current
  1. 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):

docker compose stop numi-chat
cp chats.db chats.db.bak
make docker-migrate
make docker-up

Rolling back one revision

Review the target migration's downgrade() implementation in migrations/versions/ before running:

make db-downgrade

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)

  1. Update the SQLModel table definition in src/numi_chat/data/models.py (loaded via src/numi_chat/data/db.py in migrations/env.py).
  2. Upgrade a disposable test database to head and 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"
  1. Inspect the generated script in migrations/versions/. Check nullable columns, server defaults, indexes, foreign keys, and SQLite batch_alter_table operations.
  2. Run the migration test suite to verify upgrades from older revisions with populated rows:
uv run pytest tests/data/test_migrations.py tests/data/test_deletion_integrity.py
  1. Remove the disposable migration-check.db file when finished, and update Database Schema Reference in the same commit.