Skip to main content

​
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:
  1. Relational schema — executes alembic upgrade head against your configured relational database (SQLite by default, or Postgres).
  2. 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.

​
When to call it

ScenarioWhy
After upgrading the cognee packageNew versions may add tables or columns to the relational schema.
First run against an external databaseSQLite is auto-migrated on startup; Postgres and other external databases are not.
Kubernetes / Docker init containersRun migrations once before starting the main application pods.
Switching to a new relational DB providerThe 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

​
Errors

ErrorCauseFix
FileNotFoundErroralembic.ini or the migrations directory is missing from the installed package.Reinstall cognee — the package may be corrupted or partially installed.
MigrationErrorAlembic 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.