Setup Configuration
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).
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
Environment Variables
Set these environment variables in your
.env file:DB_PROVIDER— The database provider (sqlite, postgres)DB_NAME— Database nameDB_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 (Default)
SQLite is file-based and requires no additional setup. It’s perfect for local development and single-user scenarios.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
Postgres is recommended for production environments, multi-process concurrency, or when you need external hosting.Installation: Install the Postgres extras:Docker Setup: Use the built-in Postgres service:Docker Networking: When running Cognee in Docker and Postgres on your host, set:
Advanced Options
Migration Configuration
Migration Configuration
Use migration settings to extract data from a relational database and load it into the graph store.
Backend Access Control
Backend Access Control
Enable per-user dataset isolation for multi-tenant scenarios.This feature is available for both SQLite and Postgres.
Troubleshooting
Common Issues
Common Issues
Postgres Connectivity: Verify the database is listening on Docker Networking: Use
DB_HOST:DB_PORT and credentials are correct: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