Database

Zavod keeps runtime state in a SQL database: sqlite by default, Postgres in production. The database is shared between zavod and the nomenklatura components it embeds:

Tables	Schema defined in	Created by
cache, resolver (nomenklatura)	the component constructors	the components, on first use
statement (nomenklatura)	nomenklatura.db	load_dataset_to_db
position, program, review, review_entity (zavod)	zavod/stateful/model.py	Alembic migrations

The nomenklatura tables are not managed by zavod's Alembic setup: they are created when missing by whoever uses them.

The zavod schema is versioned with Alembic: only the migrations in zavod/alembic/ create or change these tables. Production runs from repository checkouts, so the migrations live in the repository rather than the installed package.

Running jobs affected by a migration will crash, restart, pull the new image, and block until the migration is complete. It's impractical to wait until all jobs finish - they start throughout the day and some run frequently.

We don't need to go to extreme lengths to make migrations backward compatible.

Using Alembic

From the zavod/ directory:

# Create the zavod tables on a database that doesn't have them yet:
alembic upgrade head

Migrations connect to the same database as zavod. For Postgres, extend statement timeout by setting NOMENKLATURA_DB_STMT_TIMEOUT (0 to disable it).

Changing the schema

1. Edit the table definitions in zavod/stateful/model.py.
2. Autogenerate a revision and review the draft:

alembic revision --autogenerate -m "add column"

1. Apply it with alembic upgrade head.