DB-GPT 集成 Apache DorisMySQL 协议驱动的实时数仓连接实践【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTApache Doris 作为一款实时的分析型数据仓库在 DB-GPT 中通过dbgpt_ext.datasource.rdbms.conn_doris模块以原生连接器的方式获得完整支持。本文基于 doris_install.md 展开从依赖安装、Doris 实例准备、webserver 启动到连接参数配置逐一落地并结合仓库源码剖析 Doris 连接器的实现原理与关键注意事项。读完本文你将能够独立完成 DB-GPT 与 Apache Doris 的对接并理解为何 Doris 需要复用 MySQL 兼容驱动、为何连接器要绕过 metadata 反射等底层细节。一、集成原理Doris 的 MySQL 兼容协议Apache Doris 对外提供 MySQL 兼容的访问协议这是 DB-GPT 能够以极低成本接入 Doris 的根本前提。在 conn_doris.py 中可以看到这一设计被明确固化class DorisConnector(RDBMSConnector): driver mysqlpymysql db_type doris db_dialect mysqldriver mysqlpymysql底层实际使用 PyMySQL 建立连接db_dialect mysqlSQLAlchemy 方言层面仍按 MySQL 处理db_type doris用于 DB-GPT 侧的类型标识与展示。同样在 schema.py 中Doris 被注册为独立的数据库类型Doris DbInfo(doris)。也就是说DB-GPT 将 Doris 视为协议同 MySQL、身份独立的数据源——既复用了 MySQL 生态的驱动与工具链又在产品形态上保留了 Doris 的独立识别。正因如此安装 Doris 依赖时使用的是 MySQL 的依赖组datasource_mysql而不需要单独的 Doris 驱动包。这一点在后续安装章节会体现。二、安装依赖基于 uv 同步项目依赖Doris 连接器随dbgpt-ext包发布。按照官方文档使用uv同步项目全部依赖并显式声明所需的 extra 组uv sync --all-packages \ --extra base \ --extra datasource_mysql \ --extra rag \ --extra storage_chromadb \ --extra dbgpts各 extra 的作用如下Extra 组作用base安装 DB-GPT 基础运行环境核心框架、服务端等datasource_mysql提供 MySQL 兼容驱动链Doris 连接器依赖此组ragRAG 检索能力知识库、向量化等storage_chromadbChromaDB 向量存储后端dbgptsDB-GPT 内置 Agent / 技能包从 pyproject.toml 可以确认这一依赖映射关系# 基础依赖已包含 PyMySQL pymysql, # datasource_mysql extra datasource_mysql [ # mysqlclient 2.2.x have pkg-config issue on 3.10 # If you want to install psycopg2 and mysqlclient in ubuntu, you should install # libpq-dev and libmysqlclient-dev first. mysqlclient2.1.0, ]需要特别说明的是仓库中预留了一个被注释掉的 Doris 专属驱动依赖# datasource_doris [pydoris1.0.2,2.0.0]这意味着当前版本的连接器走的是 MySQL 兼容路径官方并未启用pydoris原生驱动。如果你在自己的环境中强行引入pydoris并不会被连接器使用——连接器始终通过mysqlpymysql建连。这是一个容易误解的细节务必以本文档描述的方式安装datasource_mysql组。三、准备 Apache Doris 实例在安装依赖之后需要准备一个可用的 Doris 实例。DB-GPT 连接 Doris 时仅要求实例具备以下前提已启动 FEFrontend服务并能通过MySQL 协议端口默认 9030访问存在可登录的用户账号默认root无密码生产环境建议显式创建专用账号已创建目标数据库database并授予该用户对应库的读写与元数据查询权限。由于连接器内部会执行SHOW GRANTS、SHOW DATABASES、查询information_schema等操作详见下文源码剖析请确保连接账号至少具备元数据读取权限否则后续表结构与数据预览功能将无法正常工作。四、启动 DB-GPT WebserverDoris 实例就绪后启动 DB-GPT webserver。官方文档给出的命令为uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml该命令在当前仓库根目录执行--config指向的 dbgpt-proxy-openai.toml 是一个以 OpenAI 兼容接口作为大模型后端的典型配置其中模型相关配置通过环境变量注入[[models.llms]] provider ${env:LLM_MODEL_PROVIDER:-proxy/openai} api_key ${env:OPENAI_API_KEY} [[models.embeddings]] provider ${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai} api_key ${env:OPENAI_API_KEY}也就是说启动前通常需要先设置OPENAI_API_KEY等环境变量。若你本地已部署其他模型如 vLLM、Ollama 或本地模型可替换为configs/目录下对应的配置文件例如 dbgpt-local-vllm.toml 或 dbgpt-proxy-ollama.toml。Doris 连接器本身与模型无关无论使用何种模型后端Doris 数据源的接入方式完全一致。启动成功后通过浏览器访问 webserver 提供的 UI默认端口请以启动日志为准即可进入数据源管理页面。五、配置 Apache Doris 数据源DB-GPT 提供两种配置 Doris 数据源的方式UI 操作在 Web 界面的数据源管理页选择 Apache Doris 类型填写下列字段配置文件 / API通过配置字段或客户端 API 提交相同的参数。核心字段如下字段说明示例hostDoris FE 主机地址127.0.0.1portDoris FE MySQL 协议端口9030user连接用户名rootpassword用户密码按实际填写database目标数据库名example_dbdriver连接驱动mysqlpymysql其中driver固定为mysqlpymysql。在源码 conn_doris.py 的DorisParameters中该字段有默认值与说明dataclass class DorisParameters(RDBMSDatasourceParameters): __type__ doris driver: str field( defaultmysqlpymysql, metadata{ help: _( Driver name for Doris, default is mysqlpymysql (MySQL compatible). ), }, )除上述连接字段外DB-GPT 的 RDBMS 参数基类还提供一组连接池调优参数见 base.py在大量查询或并发场景下值得关注参数默认值说明pool_size5连接池大小max_overflow10连接池溢出上限pool_timeout30获取连接的超时时间秒pool_recycle3600连接回收周期秒pool_pre_pingTrue取连接前执行 ping 探活密码字段默认支持环境变量注入写法${env:DBGPT_DB_PASSWORD}且被标记为privacy属性配置时优先使用环境变量而非明文可降低密钥泄露风险。六、源码剖析Doris 连接器的关键实现Doris 连接器并非简单复用 MySQL 连接器而是基于RDBMSConnector做了大量定制。理解这些实现有助于排查连接问题、评估功能边界。6.1 绕过 metadata.reflect()Doris 类型解析的关键修复在DorisConnector.__init__中源码刻意不调用metadata.reflect()# NOT call reflect() to avoid Doris type parsing issues # self._metadata metadata or MetaData() # self._metadata.reflect(bindself._engine)注释明确说明SQLAlchemy 的反射机制在处理 Doris 的列类型时存在解析问题直接reflect()会导致失败。因此连接器改用手写 SQL 从information_schema拉取表与列信息_sync_tables_from_db()通过SELECT TABLE_NAME FROM information_schema.tables WHERE TABLE_SCHEMAdatabase()同步表清单get_fields()/get_columns()通过information_schema.columns读取列名、类型、默认值、可空性与注释table_simple_info()使用concatgroup_concat生成表名(列1,列2,...)的紧凑摘要供 LLM 构建 schema 上下文。6.2 面向 LLM 的表结构信息构建为了让大模型理解 Doris 表结构get_table_info()与_build_table_info_for_doris()直接用 SQL 组装出近似CREATE TABLE的文本列定义、NOT NULL、DEFAULT、COMMENT、表注释并可选追加采样数据与索引信息_sample_rows_in_table_info默认 3每表最多附带 3 行采样数据放在/* ... */注释块中作为 LLM 生成 SQL 的参考样例_indexes_in_table_info默认 False关闭时不会输出索引信息按需开启get_indexes()通过SHOW INDEX FROM table读取索引。从源码看这类面向 LLM 的建表文本 采样行设计正是 DB-GPT 让模型在 Text-to-SQL / NL2SQL 场景中理解数据模式的核心机制。6.3 元数据与权限相关能力连接器还实现了以下元数据能力get_grants()执行SHOW GRANTS获取账号权限列表返回结构兼容 2 列 / 3 列两种格式get_current_version()通过select current_version()获取 Doris 版本号get_collation()执行SHOW COLLATION获取排序规则get_charset()从information_schema.SCHEMATA读取默认字符集get_database_names()执行SHOW DATABASES并主动过滤系统库if d[0] not in [ information_schema, sys, _statistics_, mysql, __internal_schema, doris_audit_db__, ]这样在 UI 下拉框与 Agent 对话中不会把 Doris 内部库暴露给用户或模型避免干扰。6.4 连接串构造from_uri_db()展示了最直接的连接串构造方式db_url f{cls.driver}://{quote(user)}:{urlquote(pwd)}{host}:{str(port)}/{db_name}其中quote/urlquote用于对用户名与密码中的特殊字符做 URL 编码避免含、:等字符的凭据破坏 URI 解析。七、验证连接与常见问题排查连接配置完成后可通过以下方式验证在数据源管理页面对 Doris 数据源执行测试连接成功后保存在对话场景中引用该数据源观察 Agent 是否正确加载表结构信息直接请求查看表结构 采样行确认information_schema查询权限正常。常见问题与排查思路均基于上述源码行为推导现象可能原因排查方向连接超时 / 拒绝连接端口填错或 FE 未监听 9030核对host、portMySQL 协议端口元数据查询失败账号缺少information_schema读取权限为账号授予库级读权限表结构信息为空目标database不存在或无表确认database字段与实际库名一致采样数据异常表过大或权限受限调整_sample_rows_in_table_info或关闭采样八、小结通过 MySQL 兼容协议DB-GPT 将 Apache Doris 无缝纳入统一数据源体系安装侧复用datasource_mysql依赖组连接侧使用mysqlpymysql驱动元数据侧则通过information_schema手工构建面向 LLM 的表结构描述并针对 Doris 的类型解析问题绕过了 SQLAlchemy 反射机制。从 doris_install.md 到 conn_doris.py整条链路清晰且可独立复现。若你正在建设实时数仓 AI 对话分析平台可以直接照本文步骤将 Doris 作为 DB-GPT 的数据底座投入使用。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DB-GPT 集成 Apache DorisMySQL 协议驱动的实时数仓连接实践【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTApache Doris 作为一款实时的分析型数据仓库在 DB-GPT 中通过dbgpt_ext.datasource.rdbms.conn_doris模块以原生连接器的方式获得完整支持。本文基于 doris_install.md 展开从依赖安装、Doris 实例准备、webserver 启动到连接参数配置逐一落地并结合仓库源码剖析 Doris 连接器的实现原理与关键注意事项。读完本文你将能够独立完成 DB-GPT 与 Apache Doris 的对接并理解为何 Doris 需要复用 MySQL 兼容驱动、为何连接器要绕过 metadata 反射等底层细节。一、集成原理Doris 的 MySQL 兼容协议Apache Doris 对外提供 MySQL 兼容的访问协议这是 DB-GPT 能够以极低成本接入 Doris 的根本前提。在 conn_doris.py 中可以看到这一设计被明确固化class DorisConnector(RDBMSConnector): driver mysqlpymysql db_type doris db_dialect mysqldriver mysqlpymysql底层实际使用 PyMySQL 建立连接db_dialect mysqlSQLAlchemy 方言层面仍按 MySQL 处理db_type doris用于 DB-GPT 侧的类型标识与展示。同样在 schema.py 中Doris 被注册为独立的数据库类型Doris DbInfo(doris)。也就是说DB-GPT 将 Doris 视为协议同 MySQL、身份独立的数据源——既复用了 MySQL 生态的驱动与工具链又在产品形态上保留了 Doris 的独立识别。正因如此安装 Doris 依赖时使用的是 MySQL 的依赖组datasource_mysql而不需要单独的 Doris 驱动包。这一点在后续安装章节会体现。二、安装依赖基于 uv 同步项目依赖Doris 连接器随dbgpt-ext包发布。按照官方文档使用uv同步项目全部依赖并显式声明所需的 extra 组uv sync --all-packages \ --extra base \ --extra datasource_mysql \ --extra rag \ --extra storage_chromadb \ --extra dbgpts各 extra 的作用如下Extra 组作用base安装 DB-GPT 基础运行环境核心框架、服务端等datasource_mysql提供 MySQL 兼容驱动链Doris 连接器依赖此组ragRAG 检索能力知识库、向量化等storage_chromadbChromaDB 向量存储后端dbgptsDB-GPT 内置 Agent / 技能包从 pyproject.toml 可以确认这一依赖映射关系# 基础依赖已包含 PyMySQL pymysql, # datasource_mysql extra datasource_mysql [ # mysqlclient 2.2.x have pkg-config issue on 3.10 # If you want to install psycopg2 and mysqlclient in ubuntu, you should install # libpq-dev and libmysqlclient-dev first. mysqlclient2.1.0, ]需要特别说明的是仓库中预留了一个被注释掉的 Doris 专属驱动依赖# datasource_doris [pydoris1.0.2,2.0.0]这意味着当前版本的连接器走的是 MySQL 兼容路径官方并未启用pydoris原生驱动。如果你在自己的环境中强行引入pydoris并不会被连接器使用——连接器始终通过mysqlpymysql建连。这是一个容易误解的细节务必以本文档描述的方式安装datasource_mysql组。三、准备 Apache Doris 实例在安装依赖之后需要准备一个可用的 Doris 实例。DB-GPT 连接 Doris 时仅要求实例具备以下前提已启动 FEFrontend服务并能通过MySQL 协议端口默认 9030访问存在可登录的用户账号默认root无密码生产环境建议显式创建专用账号已创建目标数据库database并授予该用户对应库的读写与元数据查询权限。由于连接器内部会执行SHOW GRANTS、SHOW DATABASES、查询information_schema等操作详见下文源码剖析请确保连接账号至少具备元数据读取权限否则后续表结构与数据预览功能将无法正常工作。四、启动 DB-GPT WebserverDoris 实例就绪后启动 DB-GPT webserver。官方文档给出的命令为uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml该命令在当前仓库根目录执行--config指向的 dbgpt-proxy-openai.toml 是一个以 OpenAI 兼容接口作为大模型后端的典型配置其中模型相关配置通过环境变量注入[[models.llms]] provider ${env:LLM_MODEL_PROVIDER:-proxy/openai} api_key ${env:OPENAI_API_KEY} [[models.embeddings]] provider ${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai} api_key ${env:OPENAI_API_KEY}也就是说启动前通常需要先设置OPENAI_API_KEY等环境变量。若你本地已部署其他模型如 vLLM、Ollama 或本地模型可替换为configs/目录下对应的配置文件例如 dbgpt-local-vllm.toml 或 dbgpt-proxy-ollama.toml。Doris 连接器本身与模型无关无论使用何种模型后端Doris 数据源的接入方式完全一致。启动成功后通过浏览器访问 webserver 提供的 UI默认端口请以启动日志为准即可进入数据源管理页面。五、配置 Apache Doris 数据源DB-GPT 提供两种配置 Doris 数据源的方式UI 操作在 Web 界面的数据源管理页选择 Apache Doris 类型填写下列字段配置文件 / API通过配置字段或客户端 API 提交相同的参数。核心字段如下字段说明示例hostDoris FE 主机地址127.0.0.1portDoris FE MySQL 协议端口9030user连接用户名rootpassword用户密码按实际填写database目标数据库名example_dbdriver连接驱动mysqlpymysql其中driver固定为mysqlpymysql。在源码 conn_doris.py 的DorisParameters中该字段有默认值与说明dataclass class DorisParameters(RDBMSDatasourceParameters): __type__ doris driver: str field( defaultmysqlpymysql, metadata{ help: _( Driver name for Doris, default is mysqlpymysql (MySQL compatible). ), }, )除上述连接字段外DB-GPT 的 RDBMS 参数基类还提供一组连接池调优参数见 base.py在大量查询或并发场景下值得关注参数默认值说明pool_size5连接池大小max_overflow10连接池溢出上限pool_timeout30获取连接的超时时间秒pool_recycle3600连接回收周期秒pool_pre_pingTrue取连接前执行 ping 探活密码字段默认支持环境变量注入写法${env:DBGPT_DB_PASSWORD}且被标记为privacy属性配置时优先使用环境变量而非明文可降低密钥泄露风险。六、源码剖析Doris 连接器的关键实现Doris 连接器并非简单复用 MySQL 连接器而是基于RDBMSConnector做了大量定制。理解这些实现有助于排查连接问题、评估功能边界。6.1 绕过 metadata.reflect()Doris 类型解析的关键修复在DorisConnector.__init__中源码刻意不调用metadata.reflect()# NOT call reflect() to avoid Doris type parsing issues # self._metadata metadata or MetaData() # self._metadata.reflect(bindself._engine)注释明确说明SQLAlchemy 的反射机制在处理 Doris 的列类型时存在解析问题直接reflect()会导致失败。因此连接器改用手写 SQL 从information_schema拉取表与列信息_sync_tables_from_db()通过SELECT TABLE_NAME FROM information_schema.tables WHERE TABLE_SCHEMAdatabase()同步表清单get_fields()/get_columns()通过information_schema.columns读取列名、类型、默认值、可空性与注释table_simple_info()使用concatgroup_concat生成表名(列1,列2,...)的紧凑摘要供 LLM 构建 schema 上下文。6.2 面向 LLM 的表结构信息构建为了让大模型理解 Doris 表结构get_table_info()与_build_table_info_for_doris()直接用 SQL 组装出近似CREATE TABLE的文本列定义、NOT NULL、DEFAULT、COMMENT、表注释并可选追加采样数据与索引信息_sample_rows_in_table_info默认 3每表最多附带 3 行采样数据放在/* ... */注释块中作为 LLM 生成 SQL 的参考样例_indexes_in_table_info默认 False关闭时不会输出索引信息按需开启get_indexes()通过SHOW INDEX FROM table读取索引。从源码看这类面向 LLM 的建表文本 采样行设计正是 DB-GPT 让模型在 Text-to-SQL / NL2SQL 场景中理解数据模式的核心机制。6.3 元数据与权限相关能力连接器还实现了以下元数据能力get_grants()执行SHOW GRANTS获取账号权限列表返回结构兼容 2 列 / 3 列两种格式get_current_version()通过select current_version()获取 Doris 版本号get_collation()执行SHOW COLLATION获取排序规则get_charset()从information_schema.SCHEMATA读取默认字符集get_database_names()执行SHOW DATABASES并主动过滤系统库if d[0] not in [ information_schema, sys, _statistics_, mysql, __internal_schema, doris_audit_db__, ]这样在 UI 下拉框与 Agent 对话中不会把 Doris 内部库暴露给用户或模型避免干扰。6.4 连接串构造from_uri_db()展示了最直接的连接串构造方式db_url f{cls.driver}://{quote(user)}:{urlquote(pwd)}{host}:{str(port)}/{db_name}其中quote/urlquote用于对用户名与密码中的特殊字符做 URL 编码避免含、:等字符的凭据破坏 URI 解析。七、验证连接与常见问题排查连接配置完成后可通过以下方式验证在数据源管理页面对 Doris 数据源执行测试连接成功后保存在对话场景中引用该数据源观察 Agent 是否正确加载表结构信息直接请求查看表结构 采样行确认information_schema查询权限正常。常见问题与排查思路均基于上述源码行为推导现象可能原因排查方向连接超时 / 拒绝连接端口填错或 FE 未监听 9030核对host、portMySQL 协议端口元数据查询失败账号缺少information_schema读取权限为账号授予库级读权限表结构信息为空目标database不存在或无表确认database字段与实际库名一致采样数据异常表过大或权限受限调整_sample_rows_in_table_info或关闭采样八、小结通过 MySQL 兼容协议DB-GPT 将 Apache Doris 无缝纳入统一数据源体系安装侧复用datasource_mysql依赖组连接侧使用mysqlpymysql驱动元数据侧则通过information_schema手工构建面向 LLM 的表结构描述并针对 Doris 的类型解析问题绕过了 SQLAlchemy 反射机制。从 doris_install.md 到 conn_doris.py整条链路清晰且可独立复现。若你正在建设实时数仓 AI 对话分析平台可以直接照本文步骤将 Doris 作为 DB-GPT 的数据底座投入使用。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
