agentic_huge_data_base / wiki
页面 Cognee · 5.4 数据库配置与选择·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 5.4

5.4 · 数据库配置与选择（Database Configuration and Selection）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节5.4 状态全文译文 模块存储与持久化、配置治理、检索、召回与索引、图谱与关系
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Database Configuration and Selection 上一章5.3 下一章5.5
源码线索
  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/relational/config.py
  • cognee/infrastructure/databases/relational/create_relational_engine.py
  • cognee/infrastructure/databases/relational/get_relational_engine.py
模块标签
  • 存储与持久化
  • 配置治理
  • 检索、召回与索引
  • 图谱与关系
  • 系统架构

章节正文

数据库配置与选择

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/5.4-database-configuration-and-selection

数据库配置与选择

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/relational/config.py
  • cognee/infrastructure/databases/relational/create_relational_engine.py
  • cognee/infrastructure/databases/relational/get_relational_engine.py
  • cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/config.py
  • cognee/infrastructure/databases/vector/create_vector_engine.py
  • cognee/infrastructure/databases/vector/get_vector_engine.py
  • cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/search/operations/get_history.py
  • cognee/modules/users/models/DatasetDatabase.py
  • cognee/root_dir.py
  • cognee/shared/lru_cache.py
  • cognee/tests/unit/infrastructure/databases/relational/test_RelationalConfig.py
  • cognee/tests/unit/infrastructure/databases/relational/test_SqlAlchemyAdapter.py
  • cognee/tests/unit/infrastructure/databases/relational/test_create_relational_engine.py

本文档说明了如何通过环境变量和工厂函数在 Cognee 中配置和选择数据库提供者。Cognee 采用三数据库架构，将存储分离为关系型、图数据库和向量数据库三层。每一层都支持多种提供者实现，通过配置进行选择。

范围：本页面涵盖通过 BaseSettings 类进行配置的机制、用于实例化数据库适配器的工厂函数（create_vector_engine、create_graph_engine、create_relational_engine），以及提供者选择逻辑。

默认零配置设置

Cognee 设计为开箱即用，默认使用基于文件的数据库。如果未设置特定的数据库环境变量，系统会使用以下默认值：

存储层默认提供者存储位置
关系型sqlite.cognee_system/databases/cognee_db
向量lancedb.cognee_system/databases/cognee.lancedb
图ladybug（Kuzu）.cognee_system/databases/cognee_graph_ladybug

根存储位置来源于 BaseConfig，其默认将 system_root_directory 设置为项目根目录下名为 .cognee_system 的隐藏目录 cognee/base_config.py:13。默认提供者和文件名在各自的配置类中设置 cognee/infrastructure/databases/relational/config.py:18-35、cognee/infrastructure/databases/vector/config.py:30-65、cognee/infrastructure/databases/graph/config.py:45-103。

来源：cognee/base_config.py:12-13、cognee/infrastructure/databases/relational/config.py:18-35、cognee/infrastructure/databases/vector/config.py:30-65、cognee/infrastructure/databases/graph/config.py:45-103

数据库工厂架构

Cognee 使用工厂函数来抽象数据库适配器的实例化过程。这些工厂函数从全局配置对象（例如 RelationalConfig、VectorConfig、GraphConfig）中读取配置，而这些配置对象通过 Pydantic 从环境变量中填充。

代码实体关系图

下图展示了配置类与消费它们以生成特定数据库适配器的工厂函数之间的关系。

Cognee · 代码实体关系图 · 图 1
Cognee · 代码实体关系图 · 图 1

来源：cognee/infrastructure/databases/relational/create_relational_engine.py:10-20、cognee/infrastructure/databases/vector/create_vector_engine.py:48-59、cognee/infrastructure/databases/graph/get_graph_engine.py:115-131、cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:27-31

关系型数据库配置

关系型存储层由 RelationalConfig 管理。它支持 sqlite（通过 aiosqlite）和 postgres（通过 asyncpg）。

实现细节

create_relational_engine 函数会构建一个连接字符串并返回一个 SqlAlchemyAdapter 实例。

  • SQLite：使用 sqlite+aiosqlite:///{db_path}/{db_name} 格式 cognee/infrastructure/databases/relational/create_relational_engine.py:49-50。
  • Postgres：使用 URL.create 来安全处理凭证中的特殊字符，如 # 或 @ cognee/infrastructure/databases/relational/create_relational_engine.py:58-65。

SqlAlchemyAdapter 管理引擎和会话工厂 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:104。它支持高级选项，如 DATABASE_CONNECT_ARGS 和 POOL_ARGS，用于连接池和 SSL 设置 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:41-51。对于非 SQLite 数据库，它默认使用大小为 20 的 QueuePool，并启用 pool_pre_ping cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:88-93。

来源：cognee/infrastructure/databases/relational/config.py:12-25、cognee/infrastructure/databases/relational/create_relational_engine.py:45-79、cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:33-104

向量数据库配置

向量存储通过 VECTOR_DB_PROVIDER 进行选择。create_vector_engine 函数是实例化向量适配器的主要入口点。

提供者选择逻辑

工厂函数会检查 vector_db_provider 与内部支持的提供者映射。

  • LanceDB：默认的基于文件的提供者 cognee/infrastructure/databases/vector/config.py:30。
  • PGVector：需要 PostgreSQL。如果未显式提供，它可以自动从 RelationalConfig 继承连接详情 cognee/infrastructure/databases/vector/create_vector_engine.py:79-96。
  • 统一提供者：如果设置了 USE_UNIFIED_PROVIDER="pghybrid"，系统会强制使用 PGVectorAdapter，并使用关系型数据库的连接字符串 cognee/infrastructure/databases/vector/create_vector_engine.py:78-96。

create_pg_database 函数负责创建 Postgres 数据库和 vector 扩展（如果它们不存在）cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64。

来源：cognee/infrastructure/databases/vector/create_vector_engine.py:48-109、cognee/infrastructure/databases/vector/config.py:11-35、cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64

图数据库配置

图存储通过 GRAPH_DATABASE_PROVIDER 进行选择。get_graph_engine 函数作为 create_graph_engine 的异步包装器，使用 _GraphEngineHandle 来维护跨缓存失效的稳定引用 cognee/infrastructure/databases/graph/get_graph_engine.py:56-112。

图工厂流程
Cognee · 图工厂流程 · 图 2
Cognee · 图工厂流程 · 图 2

来源：cognee/infrastructure/databases/graph/get_graph_engine.py:56-112、cognee/infrastructure/databases/graph/get_graph_engine.py:115-131、cognee/infrastructure/databases/graph/config.py:153-167

支持的图数据库提供者
  • Ladybug（Kuzu）：本地基于文件的图数据库。如果 graph_database_provider 设置为 "ladybug" 或 "kuzu" 则选择此提供者 cognee/infrastructure/databases/graph/config.py:45。
  • Neo4j：通过 Bolt 协议连接的远程图数据库。需要设置 graph_database_url。
  • Postgres：使用 PostgresAdapter 在关系型表中存储图数据。通过 pghybrid 统一提供者启用 cognee/infrastructure/databases/graph/get_graph_engine.py:160-166。

存储与 S3 集成

Cognee 支持 STORAGE_BACKEND 设置（默认为 local）。如果设置为 s3，系统会处理 SQLite 数据库，将其拉取到本地临时文件进行处理，并在操作完成后推送回 S3。

  • S3 SQLite 处理：如果路径包含 s3://，SqlAlchemyAdapter 会在初始化期间使用 pull_from_s3 方法 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:62-72。它还提供了 push_to_s3 方法用于将更改同步回 S3 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:106-111。
  • 路径解析：BaseConfig 确保 data_root_directory、system_root_directory 和 cache_root_directory 被解析为绝对路径或有效的 S3 URI cognee/base_config.py:19-35。

来源：cognee/base_config.py:11-41、cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:58-111

配置参考（环境变量）

变量配置类默认值描述
DB_PROVIDERRelationalConfigsqlitesqlite 或 postgres
DB_NAMERelationalConfigcognee_db关系型数据库名称
GRAPH_DATABASE_PROVIDERGraphConfigladybugladybug、kuzu、neo4j、postgres 等
VECTOR_DB_PROVIDERVectorConfiglancedblancedb、pgvector、qdrant 等
USE_UNIFIED_PROVIDER不适用""设置为 pghybrid 可强制所有存储使用 Postgres
STORAGE_BACKENDBaseConfiglocallocal 或 s3
DATABASE_CONNECT_ARGSRelationalConfigNone数据库驱动参数的 JSON 字符串
POOL_ARGSRelationalConfigNoneSQLAlchemy 连接池参数的 JSON 字符串

来源：cognee/infrastructure/databases/relational/config.py:12-25、cognee/infrastructure/databases/graph/config.py:45-65、cognee/infrastructure/databases/vector/config.py:26-35、cognee/base_config.py:23-30