> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# run_startup_migrations

> Apply pending relational and vector database schema migrations

# cognee.run\_startup\_migrations

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

```python theme={null}
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

| 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.                    |

<Note>
  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.
</Note>

## Example

```python theme={null}
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:

```yaml theme={null}
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

| 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. |

<Tip>
  Set `LOG_LEVEL=DEBUG` to see the full Alembic output when diagnosing migration failures.
</Tip>

## Related

* [Relational Databases](/setup-configuration/relational-databases) — configure SQLite or Postgres
* [Deployment Overview](/how-to-guides/cognee-sdk/deployment/index) — how to structure Cognee in production
* [Kubernetes (Helm)](/how-to-guides/cognee-sdk/deployment/helm) — full Kubernetes deployment guide