agentic_huge_data_base / wiki
页面 Cognee · 5.3 关系型数据库适配器·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 5.3

5.3 · 关系型数据库适配器（Relational Database Adapter）

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

项目Cognee 章节5.3 状态全文译文 模块系统架构、存储与持久化、检索、召回与索引、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Relational Database Adapter 上一章5.2 下一章5.4
源码线索
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.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/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/search/operations/get_history.py
模块标签
  • 系统架构
  • 存储与持久化
  • 检索、召回与索引
  • 界面与交互
  • 配置治理

章节正文

关系型数据库适配器

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/5.3-relational-database-adapter

关系型数据库适配器

相关源文件

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

  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.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/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/search/operations/get_history.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 的元数据、用户信息、数据集管理和管线追踪提供了持久化存储。本文档介绍了 SQLAlchemyAdapter 类，该类通过异步操作、模式管理和 CRUD 功能，对 SQLite 和 PostgreSQL 数据库进行了抽象。

范围： 本页面聚焦于关系型适配器的实现。关于向量数据库适配器，请参见向量数据库适配器。关于图数据库适配器，请参见图数据库适配器。关于多租户数据库隔离，请参见多租户访问控制。

架构总览

关系型适配器基于 SQLAlchemy 的异步引擎构建，支持本地 SQLite 和远程 PostgreSQL 后端。

系统映射：自然语言到代码实体

下图将概念性的数据库管理任务映射到负责这些任务的具体代码实体。

标题：数据库实体映射

Cognee · 系统映射：自然语言到代码实体 · 图 1
Cognee · 系统映射：自然语言到代码实体 · 图 1

来源： cognee/infrastructure/databases/relational/config.py:12-25，cognee/infrastructure/databases/relational/create_relational_engine.py:10-20，cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:27-33

数据流与组件

标题：关系型适配器架构

Cognee · 数据流与组件 · 图 2
Cognee · 数据流与组件 · 图 2

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:33-104，cognee/infrastructure/databases/relational/config.py:12-82，cognee/infrastructure/databases/relational/create_relational_engine.py:46-79

配置系统

RelationalConfig 类

RelationalConfig 类通过环境变量管理数据库连接参数，使用 Pydantic Settings 实现 cognee/infrastructure/databases/relational/config.py:12-25。

字段类型默认值描述
db_pathstr""SQLite 数据库文件的目录路径
db_namestr"cognee_db"数据库名称
db_hoststr | NoneNonePostgreSQL 主机地址
db_portstr | NoneNonePostgreSQL 端口号
db_usernamestr | NoneNonePostgreSQL 用户名
db_passwordstr | NoneNonePostgreSQL 密码
db_providerstr"sqlite"提供者类型："sqlite" 或 "postgres"
database_connect_argsstr | NoneNone驱动特定连接参数的 JSON 字符串
pool_argsstr | NoneNone连接池配置的 JSON 字符串

来源： cognee/infrastructure/databases/relational/config.py:12-25

连接与池参数

连接参数（例如 SSL 模式、超时时间）从 JSON 字符串解析为排序后的元组，以确保缓存兼容性 cognee/infrastructure/databases/relational/config.py:38-43。PostgreSQL 的默认池设置包括 pool_size=20、max_overflow=20 和 pool_pre_ping=True cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:88-93。

来源： cognee/infrastructure/databases/relational/config.py:38-57，cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:74-102

工厂函数

create_relational_engine() 函数是获取数据库适配器的主要入口点。它使用 @lru_cache 装饰器，确保对相同参数实现单例行为 cognee/infrastructure/databases/relational/create_relational_engine.py:9-10。

标题：引擎创建逻辑

Cognee · 工厂函数 · 图 3
Cognee · 工厂函数 · 图 3

来源： cognee/infrastructure/databases/relational/create_relational_engine.py:46-79

SQLAlchemyAdapter 类

初始化与 S3 支持

适配器负责创建 SQLAlchemy 的 AsyncEngine 和 async_sessionmaker cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:75-104。对于托管在 S3 上的 SQLite 数据库，它会在建立连接之前，将数据库同步下载到本地临时文件 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:62-72。

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:33-104

会话管理

适配器提供了一个异步上下文管理器 get_async_session()，用于获取数据库会话，确保会话在使用后正确关闭 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:123-132。

# 使用模式
async with adapter.get_async_session() as session:
    # 操作
    pass

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:123-132

模式操作

适配器支持动态创建和删除表：

  • create_table()：执行原始 SQL 以创建模式和表 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:161-181。
  • delete_table()：从指定模式中移除一个表 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:183-191。

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:161-191

CRUD 与数据操作

适配器提供了常见数据操作的方法：

  • get_datasets()：使用 joinedload 加载 data 关系来检索数据集 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:145-159。
  • delete_entity_by_id()：根据 ID 从特定表中删除记录 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:276-285。
  • delete_data_entity()：一个复杂操作，用于删除数据记录及其物理文件，并在删除前检查其他引用 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:306-347。

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:145-347

多租户数据库处理器

Cognee 通过特定的处理器，为每个数据集提供隔离的关系型和向量数据库。

Postgres 和 PGVector 设置

当使用 PostgreSQL 进行向量存储（通过 pgvector）时，Cognee 可以为每个数据集创建一个独立的数据库。这需要一个连接到默认 postgres 数据库的维护引擎，以执行 CREATE DATABASE 等管理任务 cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:32-52。

标题：Postgres 数据库配置

Cognee · Postgres 和 PGVector 设置 · 图 4
Cognee · Postgres 和 PGVector 设置 · 图 4

来源： cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:21-58，cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64

支持的处理器

系统将提供者映射到特定的处理器实例，用于管理数据集级别的生命周期操作 cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py:17-36。

提供者处理器类用途
pgvectorPGVectorDatasetDatabaseHandler创建/删除用于向量存储的 Postgres 数据库 cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:15-20
postgres（图）PostgresGraphDatasetDatabaseHandler管理每个数据集的 Postgres 图实例 cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py:34-36
neo4jNeo4jAuraDevDatasetDatabaseHandler通过 API 配置 Neo4j Aura 实例 cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py:17-31

来源： cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py:17-36

数据库迁移

Cognee 使用 SQLAlchemy 和自定义逻辑管理关系型模式的更新，以支持向量扩展。

扩展管理

对于 PostgreSQL，系统确保安装了 vector 扩展。如果禁用了后端访问控制，它会尝试在当前引擎上创建该扩展 cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:10-18。

删除与清理

在多租户环境中删除数据集时，delete_pg_database 函数会在删除该数据库之前，终止该数据库的所有活动后端连接 cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:91-102。

来源： cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:10-106