5.3 · Relational 数据库 Adapter（Relational Database Adapter）

Relational 数据库 Adapter（中文译文）

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

翻译时间：2026-05-27T08:45:17.389Z

翻译模型：deepseek-chat

原文字符数：13549

项目：Cognee (cognee)

---

关系型数据库适配器

相关源文件

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

• 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 后端。

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

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

标题：数据库实体映射

graph TB
    subgraph "自然语言空间"
        CONFIG["'配置连接'"]
        ENGINE_CREATE["'创建数据库引擎'"]
        SESSION_MGMT["'管理异步会话'"]
        DATA_OPS["'执行 CRUD 操作'"]
    end

    subgraph "代码实体空间"
        RelationalConfig["RelationalConfig 类<br/>(config.py)"]
        create_relational_engine["create_relational_engine()<br/>(create_relational_engine.py)"]
        SqlAlchemyAdapter["SQLAlchemyAdapter 类<br/>(SqlAlchemyAdapter.py)"]
        AsyncSession["AsyncSession / async_sessionmaker<br/>(SQLAlchemy)"]
    end

    CONFIG -.-> RelationalConfig
    ENGINE_CREATE -.-> create_relational_engine
    SESSION_MGMT -.-> AsyncSession
    DATA_OPS -.-> SqlAlchemyAdapter

    RelationalConfig -- "提供参数给" --> create_relational_engine
    create_relational_engine -- "实例化" --> SqlAlchemyAdapter
    SqlAlchemyAdapter -- "管理" --> AsyncSession

来源： 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

数据流与组件

标题：关系型适配器架构

graph TB
    subgraph "配置层"
        ENV[".env 文件"]
        RC["RelationalConfig"]
        ENV --> RC
    end

    subgraph "工厂层"
        CRE["create_relational_engine()"]
        RC --> CRE
    end

    subgraph "适配器层"
        SAA["SQLAlchemyAdapter"]
        ENGINE["AsyncEngine"]
        SESSION_MAKER["async_sessionmaker"]

        CRE --> SAA
        SAA --> ENGINE
        SAA --> SESSION_MAKER
    end

    subgraph "数据库提供者"
        SQLITE[("SQLite 数据库<br/>sqlite+aiosqlite")]
        POSTGRES[("PostgreSQL 数据库<br/>postgresql+asyncpg")]

        ENGINE --> SQLITE
        ENGINE --> POSTGRES
    end

    subgraph "存储后端"
        LOCAL["本地文件系统"]
        S3["S3 兼容存储"]

        SQLITE --> LOCAL
        SQLITE --> S3
    end

来源： 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_path	str	""	SQLite 数据库文件的目录路径
db_name	str	"cognee_db"	数据库名称
db_host	`str \	None`	None	PostgreSQL 主机地址
db_port	`str \	None`	None	PostgreSQL 端口号
db_username	`str \	None`	None	PostgreSQL 用户名
db_password	`str \	None`	None	PostgreSQL 密码
db_provider	str	"sqlite"	提供者类型："sqlite" 或 "postgres"
database_connect_args	`str \	None`	None	驱动特定连接参数的 JSON 字符串
pool_args	`str \	None`	None	连接池配置的 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。

标题：引擎创建逻辑

graph LR
    START["create_relational_engine()"] --> CHECK_PROVIDER{"db_provider?"}

    CHECK_PROVIDER -->|"sqlite"| SQLITE_STR["connection_string =<br/>sqlite+aiosqlite:///<br/>db_path/db_name"]
    CHECK_PROVIDER -->|"postgres"| PG_CHECK{"asyncpg<br/>已安装?"}

    PG_CHECK -->|"是"| PG_STR["connection_string =<br/>URL.create()<br/>postgresql+asyncpg"]
    PG_CHECK -->|"否"| ERROR["ImportError"]

    SQLITE_STR --> ADAPTER["SQLAlchemyAdapter(<br/>connection_string,<br/>connect_args,<br/>pool_args)"]
    PG_STR --> ADAPTER

来源： 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 数据库配置

graph TD
    subgraph "PGVector 处理器"
        CREATE["PGVectorDatasetDatabaseHandler.create_dataset()"]
        PROVISION["create_pg_database()"]
    end

    subgraph "Postgres 服务器"
        MAINT_DB[("维护数据库<br/>'postgres'")]
        NEW_DB[("数据集数据库<br/>'uuid'")]
    end

    CREATE --> PROVISION
    PROVISION -- "连接到" --> MAINT_DB
    PROVISION -- "执行 CREATE DATABASE" --> NEW_DB
    PROVISION -- "执行 CREATE EXTENSION vector" --> NEW_DB

来源： 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。

提供者	处理器类	用途
pgvector	PGVectorDatasetDatabaseHandler	创建/删除用于向量存储的 Postgres 数据库 cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:15-20
postgres（图）	PostgresGraphDatasetDatabaseHandler	管理每个数据集的 Postgres 图实例 cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py:34-36
neo4j	Neo4jAuraDevDatasetDatabaseHandler	通过 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