cognee: Skill for Claude Code

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

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]