Relational Databases - Cognee Documentation

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

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)

Setup Guides

SQLite (Default)

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

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

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.

SQLite Source
Same Postgres Server
Different Postgres Server

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"

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:

# 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

Use this when your source data lives on a separate Postgres instance:

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

See the Relational Database Migration example for a complete walkthrough of migrating schema and data into a knowledge graph.

Backend Access Control

Enable per-user dataset isolation for multi-tenant scenarios.

ENABLE_BACKEND_ACCESS_CONTROL="true"

This feature is available for both SQLite and Postgres.

Troubleshooting

Common Issues

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

Documentation Index

​Supported Providers

​Configuration

​Setup Guides

​Advanced Options

​Troubleshooting

​When to Use Each

Vector Stores

Graph Stores

Overview

Supported Providers

Configuration

Setup Guides

Advanced Options

Troubleshooting

When to Use Each