cognee.run_startup_migrations

Applies all pending database schema migrations before the rest of your application starts.

await cognee.run_startup_migrations()

It runs two steps in sequence:

Relational schema — executes alembic upgrade head against your configured relational database (SQLite by default, or Postgres).
Vector schema — runs the vector adapter’s run_migrations method for every database that needs it:
- Single-user mode (ENABLE_BACKEND_ACCESS_CONTROL=False): migrates the single default vector engine.
- Multi-user mode (ENABLE_BACKEND_ACCESS_CONTROL=True, the default): iterates over every dataset database and migrates each one individually. A failure for one dataset is logged and skipped; the remaining datasets continue to migrate.
- If the active vector engine has no run_migrations method, Cognee logs a warning and skips that engine.
- If the dataset_database table does not exist yet (a fresh database), the vector migration step is skipped with a warning instead of raising. This is handled on both SQLite (OperationalError, “no such table”) and PostgreSQL/pgvector (ProgrammingError / UndefinedTableError).

Entrypoints

All migration functions live in the cognee.run_migrations module. run_startup_migrations is also re-exported at the top level as cognee.run_startup_migrations, so it is the recommended entrypoint for most applications.

Function	Import	Migrates
`run_startup_migrations`	`cognee.run_startup_migrations` (or `from cognee.run_migrations import run_startup_migrations`)	Relational and vector schema (recommended)
`run_migrations`	`from cognee.run_migrations import run_migrations`	Relational schema only (`alembic upgrade head`)
`run_vector_migrations`	`from cognee.run_migrations import run_vector_migrations`	Vector schema only

When to call it

Scenario	Why
After upgrading the `cognee` package	New versions may add tables or columns to the relational schema.
First run against an external database	SQLite is auto-migrated on startup; Postgres and other external databases are not.
Kubernetes / Docker init containers	Run migrations once before starting the main application pods.
Switching to a new relational DB provider	The new database starts empty and needs all migrations applied.

For the default local setup (SQLite + LanceDB), Cognee handles migrations automatically when the API server starts. You only need to call run_startup_migrations() explicitly in server deployments or CI pipelines where you manage database lifecycle yourself.

Example

import asyncio
import cognee

async def main():
    # Apply all pending schema migrations before starting
    await cognee.run_startup_migrations()

    # Normal usage
    await cognee.add("Hello, world!", dataset_name="demo")
    await cognee.cognify()

asyncio.run(main())

Kubernetes init container

Run migrations as a one-shot init container so the main pod only starts after the schema is ready:

initContainers:
  - name: migrate
    image: your-cognee-image:latest
    command: ["python", "-c", "import asyncio, cognee; asyncio.run(cognee.run_startup_migrations())"]
    envFrom:
      - secretRef:
          name: cognee-env

Concurrency

Every migration flow runs under a single cross-process lock, so a host performs at most one migration of any kind at a time. If several processes start at once — multiple workers of the same server, parallel SDK runs, or several init containers — only one acquires the lock and migrates; the others block until it finishes, then re-read the stored revision and skip work that is already done. Nothing runs migrations in parallel. Because of this, startup can block (and time-to-ready can increase) while another process holds the lock and migrates. This is expected under the Kubernetes init container and multi-worker scenarios above — the wait is the coordination working as intended, not a hang. The lock backend depends on your relational database:

Postgres — a session-scoped advisory lock, which also serializes migrations across hosts. Use Postgres metadata when multiple hosts may start and migrate at the same time.
SQLite — an OS advisory file lock placed next to the database file. It serializes multiple processes on a single host (multi-worker servers, parallel SDK runs) but not across hosts or over NFS.

Errors

Error	Cause	Fix
`FileNotFoundError`	`alembic.ini` or the migrations directory is missing from the installed package.	Reinstall `cognee` — the package may be corrupted or partially installed.
`MigrationError`	Alembic exited with a non-zero return code.	Check the error message logged at `ERROR` level; usually a DB connection problem or a SQL conflict.

Set LOG_LEVEL=DEBUG to see the full Alembic output when diagnosing migration failures.

Relational Databases — configure SQLite or Postgres
Deployment Overview — how to structure Cognee in production
Kubernetes (Helm) — full Kubernetes deployment guide

​cognee.run_startup_migrations

​Entrypoints

​When to call it

​Example

​Kubernetes init container

​Concurrency

​Errors

​Related

cognee.run_startup_migrations

Entrypoints

When to call it

Example

Kubernetes init container

Concurrency

Errors

Related