Skip to main content
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).
New to configuration?See the Setup Configuration Overview for the complete workflow:install extras → create .env → choose providers → handle pruning.

​
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

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)

​
Setup Guides

SQLite is file-based and requires no additional setup. It’s perfect for local development and single-user scenarios.
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.
Postgres is recommended for production environments, multi-process concurrency, or when you need external hosting.
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:
pip install "cognee[postgres]"
# or for binary version
pip install "cognee[postgres-binary]"
Docker Setup: Use the built-in Postgres service:
docker compose --profile postgres up -d
Docker Networking: When running Cognee in Docker and Postgres on your host, set:
DB_HOST="host.docker.internal"

​
Advanced Options

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.
VariableApplication DB (DB_*)Migration DB (MIGRATION_DB_*)
PurposeCognee’s internal metadata storeSource data you want converted to a graph
ContainsCognee’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.
Use this when your source data is in a SQLite file, regardless of what DB_PROVIDER is set to:
# 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"
Enable per-user dataset isolation for multi-tenant scenarios.
ENABLE_BACKEND_ACCESS_CONTROL="true"
This feature is available for both SQLite and Postgres.

​
Troubleshooting

Postgres Connectivity: Verify the database is listening on DB_HOST:DB_PORT and credentials are correct:
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.

​
When to Use Each

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

Vector Stores

Configure vector databases for embedding storage

Graph Stores

Set up graph databases for knowledge graphs

Overview

Return to setup configuration overview