Database migrations

cognee has two migration chains, run together:

Chain	Changes	Lives in	Revision stored in
Relational schema (Alembic)	Tables and columns of the relational DB (users, datasets, ACLs, pipeline runs, …)	cognee/alembic/ (alembic.ini is in cognee/)	alembic_version table
Graph/vector data	Cross-store data rewrites (re-keying node ids, adding graph columns) across graph DB, vector DB and relational ledger	cognee/modules/migrations/ (registry.py, versions/)	Per dataset: dataset_database.migration_revision (access control on). Globally: global_database_version.global_migration_revision (access control off)

Use it

They run by themselves

run_migrations() applies the relational chain first, then the data chain. It runs:

• at API server startup (and in the Docker entrypoint.sh before gunicorn);
• on the first write in an SDK or CLI process (remember, add, cognify, improve, memory imports), once per process;
• when you call await cognee.run_migrations().

A fresh database is built by running the whole chain (no stamping). At head, the first run in each process still does a no-op Alembic upgrade plus a scan of the per-database revision rows; later calls in the same process are skipped by an in-memory flag. ENABLE_AUTO_MIGRATIONS=false turns off all automatic runs; then run cognee-cli upgrade yourself.

Concurrent processes are serialized by a migration lock: a Postgres advisory lock (works across hosts) or a file lock next to the SQLite DB (one host only).

Check and repair