- name
- cognee-migrations
- description
- Use when dealing with cognee database migrations — understanding when they run automatically, checking or repairing migration state with cognee-cli upgrade/downgrade/stamp/current, a write blocked by a failed migration, authoring a new Alembic (relational schema) revision or a graph/vector data migration, or moving data between systems (relational DB import, memory export/import).
Database migrations
cognee has two migration chains, run together:
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.shbefore 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
cognee-cli current # stamped revision per database, and the last failure
cognee-cli history # the data chain, newest first
cognee-cli upgrade # relational to head, then data chain to head
cognee-cli upgrade <slug> # data chain up to and including <slug>
cognee-cli upgrade --alembic <rev> # pin the relational target
cognee-cli downgrade <slug|base> [--dataset UUID ...] [--alembic REV] [--force]
cognee-cli stamp <head|base|slug> [--dataset UUID ...] [--force]