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

# Relational Databases

> Configure relational databases for metadata and state storage in Cognee

Relational databases store metadata, document information, and system state in Cognee. They track documents, chunks, and provenance (where data came from and how it's linked).

<Info>
  **New to configuration?**

  See the [Setup Configuration Overview](./overview) for the complete workflow:

  install extras → create `.env` → choose providers → handle pruning.
</Info>

## Supported Providers

Cognee supports two relational database options:

* **SQLite** — File-based database, works out of the box (default)
* **Postgres** — Production-ready database for multi-process concurrency

## Configuration

<Accordion title="Environment Variables">
  Set these environment variables in your `.env` file:

  * `DB_PROVIDER` — The database provider (sqlite, postgres)
  * `DB_NAME` — Database name
  * `DB_HOST` — Database host (Postgres only)
  * `DB_PORT` — Database port (Postgres only)
  * `DB_USERNAME` — Database username (Postgres only)
  * `DB_PASSWORD` — Database password (Postgres only)
</Accordion>

## Setup Guides

<AccordionGroup>
  <Accordion title="SQLite (Default)">
    SQLite is file-based and requires no additional setup. It's perfect for local development and single-user scenarios.

    ```dotenv theme={null}
    DB_PROVIDER="sqlite"
    DB_NAME="cognee_db"
    ```

    **Installation**: SQLite is included by default with Cognee. No additional installation required.

    **Data Location**: Data is stored under the Cognee system directory. You can override the root with `SYSTEM_ROOT_DIRECTORY` in your `.env` file.
  </Accordion>

  <Accordion title="Postgres">
    Postgres is recommended for production environments, multi-process concurrency, or when you need external hosting.

    ```dotenv theme={null}
    DB_PROVIDER="postgres"
    DB_NAME="cognee_db"
    DB_HOST="127.0.0.1"            # use host.docker.internal when running inside Docker
    DB_PORT="5432"
    DB_USERNAME="cognee"
    DB_PASSWORD="cognee"
    ```

    **Installation**: Install the Postgres extras:

    ```bash theme={null}
    pip install "cognee[postgres]"
    # or for binary version
    pip install "cognee[postgres-binary]"
    ```

    **Docker Setup**: Use the built-in Postgres service:

    ```bash theme={null}
    docker compose --profile postgres up -d
    ```

    **Docker Networking**: When running Cognee in Docker and Postgres on your host, set:

    ```dotenv theme={null}
    DB_HOST="host.docker.internal"
    ```
  </Accordion>
</AccordionGroup>

## Advanced Options

<Accordion title="Migration Configuration">
  The `MIGRATION_DB_*` variables point to a **source** database that you want to extract and migrate **into** Cognee's knowledge graph. This is entirely separate from the application database (`DB_*`) that Cognee uses for its own internal metadata and state.

  | Variable | Application DB (`DB_*`)                        | Migration DB (`MIGRATION_DB_*`)           |
  | -------- | ---------------------------------------------- | ----------------------------------------- |
  | Purpose  | Cognee's internal metadata store               | Source data you want converted to a graph |
  | Contains | Cognee's own tables (documents, chunks, state) | Your application's tables and rows        |

  **Does the migration DB need to be a different database than the application DB?**

  In practice, use a different database (different `DB_NAME` / `MIGRATION_DB_NAME`) unless you intentionally want to migrate Cognee's own internal tables into the knowledge graph. They can still live on the same Postgres server as long as they are different databases.

  <Tabs>
    <Tab title="SQLite Source">
      Use this when your source data is in a SQLite file, regardless of what `DB_PROVIDER` is set to:

      ```dotenv theme={null}
      # Application DB (Cognee's internal store)
      DB_PROVIDER="postgres"
      DB_NAME="cognee_db"
      DB_HOST="127.0.0.1"
      DB_PORT="5432"
      DB_USERNAME="cognee"
      DB_PASSWORD="cognee"

      # Migration DB (your source data — a separate SQLite file)
      MIGRATION_DB_PROVIDER="sqlite"
      MIGRATION_DB_PATH="/path/to/migration/directory"
      MIGRATION_DB_NAME="my_app_data.sqlite"
      ```
    </Tab>

    <Tab title="Same Postgres Server">
      Use this when your source data is in a separate Postgres database on the same server as Cognee's application DB. Set `MIGRATION_DB_NAME` to a **different** database name for the usual case:

      ```dotenv theme={null}
      # Application DB (Cognee's internal store)
      DB_PROVIDER="postgres"
      DB_NAME="cognee_db"
      DB_HOST="127.0.0.1"
      DB_PORT="5432"
      DB_USERNAME="cognee"
      DB_PASSWORD="cognee"

      # Migration DB (your source data — different DB name on the same Postgres server)
      MIGRATION_DB_PROVIDER="postgres"
      MIGRATION_DB_HOST="127.0.0.1"
      MIGRATION_DB_PORT="5432"
      MIGRATION_DB_USERNAME="cognee"
      MIGRATION_DB_PASSWORD="cognee"
      MIGRATION_DB_NAME="my_app_db"   # usually different from DB_NAME above
      ```
    </Tab>

    <Tab title="Different Postgres Server">
      Use this when your source data lives on a separate Postgres instance:

      ```dotenv theme={null}
      # Migration DB (separate Postgres instance)
      MIGRATION_DB_PROVIDER="postgres"
      MIGRATION_DB_HOST="db.example.com"
      MIGRATION_DB_PORT="5432"
      MIGRATION_DB_USERNAME="readonly_user"
      MIGRATION_DB_PASSWORD="readonly_password"
      MIGRATION_DB_NAME="production_db"
      ```
    </Tab>
  </Tabs>

  See the [Relational Database Migration example](/examples/relational-db-migration) for a complete walkthrough of migrating schema and data into a knowledge graph.
</Accordion>

<Accordion title="Backend Access Control">
  Enable per-user dataset isolation for multi-tenant scenarios.

  ```dotenv theme={null}
  ENABLE_BACKEND_ACCESS_CONTROL="true"
  ```

  This feature is available for both SQLite and Postgres.
</Accordion>

## Troubleshooting

<Accordion title="Common Issues">
  **Postgres Connectivity**: Verify the database is listening on `DB_HOST:DB_PORT` and credentials are correct:

  ```bash theme={null}
  psql -h 127.0.0.1 -U cognee -d cognee_db
  ```

  **Docker Networking**: Use `host.docker.internal` for host-to-container access on macOS/Windows.

  **SQLite Concurrency**: SQLite has limited write concurrency; prefer Postgres for heavy multi-user workloads.
</Accordion>

## When to Use Each

* **SQLite**: Local development, single-user applications, simple deployments
* **Postgres**: Production environments, multi-user applications, external hosting, co-location with pgvector

<Columns cols={3}>
  <Card title="Vector Stores" icon="database" href="/setup-configuration/vector-stores">
    Configure vector databases for embedding storage
  </Card>

  <Card title="Graph Stores" icon="network" href="/setup-configuration/graph-stores">
    Set up graph databases for knowledge graphs
  </Card>

  <Card title="Overview" icon="settings" href="/setup-configuration/overview">
    Return to setup configuration overview
  </Card>
</Columns>