DB-GPT v0.5.0 升级指南：从 v0.4.x 完成数据库迁移与依赖更新的完整实操手册

DB-GPT v0.5.0 升级指南从 v0.4.x 完成数据库迁移与依赖更新的完整实操手册【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT导读本指南面向正在使用 DB-GPT v0.4.6 / v0.4.7、计划升级到 v0.5.0 的开发者。v0.5.0 是 DB-GPT 首个进入长期维护周期的稳定版本也是其正式确立 AI 原生数据应用开发框架定位Agentic Workflow Expression Language, AWEL Agents的里程碑版本升级过程中数据库结构发生了显著变化新增 AWEL 工作流表与应用元数据表MySQL 用户必须手动执行脚本完成表结构升级。读完本文你将掌握完整的升级前置检查、备份策略、四张新表的字段语义、两列新增列的用途以及依赖重装与服务重启的完整流程。一、升级概览适用范围与数据库差异升级文档v0.5.0.md明确限定了本次升级的适用范围适用起点版本v0.4.6 与 v0.4.7目标版本v0.5.0数据库处理方式分两种情况使用 SQLite无需升级数据库可直接跳过数据库升级步骤使用 MySQL必须执行数据库升级脚本新增表与新增列缺一不可。之所以 MySQL 必须手动升级与 v0.5.0 版本的一个关键行为变更直接相关官方在发布说明Released_V0.5.0.md中明确提到MySQL 数据库不再支持自动建表和字段自动更新对应 issue #1133。这意味着从 v0.5.0 起MySQL 场景下的表结构变更需要开发者显式、手动地执行迁移 SQL从而把数据库变更的控制权完全交给开发者。SQLite 场景则不受影响表结构会在服务启动时按需自动处理。从仓库的 assets/schema/upgrade 目录可以看到v0.5.0 之后v0.5.1、v0.5.2……直至 v0.8.2每个版本都配套独立的升级 SQL 目录每个目录内包含一份到上一版本的完整快照与一份增量升级脚本说明手工执行 SQL 迁移已成为后续版本的标准升级范式。二、升级前准备务必备份你的数据库升级会执行多条 DDL建表、加列一旦执行失败或版本不兼容存在数据丢失风险。因此官方文档要求升级前必须先备份数据库具体备份方式视你的数据库类型而定MySQL可使用mysqldump对dbgpt库做逻辑备份例如mysqldump -u用户名 -p密码 dbgpt dbgpt_backup_v0407.sqlSQLite直接复制数据库文件默认位于pilot/meta_data/dbgpt.db到安全位置即可例如cp pilot/meta_data/dbgpt.db dbgpt_backup_v0407.db。备份完成后建议先确认备份文件可读取、可恢复再进入升级环节。三、升级主流程共四步第 1 步停止 DB-GPT 服务停止 DB-GPT 服务的方式取决于你启动服务的方式前台python、dbgpt start webserver命令、systemd、Docker 等。必须在服务完全停止后再执行数据库变更避免运行中的进程与 DDL 操作冲突也防止新代码在旧表结构下提前写入数据。第 2 步升级数据库在 MySQL 中执行以下 SQL 完成升级共包含四张新表与两列新增列。2.1 新增表一dbgpt_serve_flowAWEL 工作流定义表CREATE TABLE dbgpt_serve_flow ( id int NOT NULL AUTO_INCREMENT COMMENT Auto increment id, uid varchar(128) NOT NULL COMMENT Unique id, dag_id varchar(128) DEFAULT NULL COMMENT DAG id, name varchar(128) DEFAULT NULL COMMENT Flow name, flow_data text COMMENT Flow data, JSON format, user_name varchar(128) DEFAULT NULL COMMENT User name, sys_code varchar(128) DEFAULT NULL COMMENT System code, gmt_created datetime DEFAULT NULL COMMENT Record creation time, gmt_modified datetime DEFAULT NULL COMMENT Record update time, flow_category varchar(64) DEFAULT NULL COMMENT Flow category, description varchar(512) DEFAULT NULL COMMENT Flow description, state varchar(32) DEFAULT NULL COMMENT Flow state, source varchar(64) DEFAULT NULL COMMENT Flow source, source_url varchar(512) DEFAULT NULL COMMENT Flow source url, version varchar(32) DEFAULT NULL COMMENT Flow version, label varchar(128) DEFAULT NULL COMMENT Flow label, editable int DEFAULT NULL COMMENT Editable, 0: editable, 1: not editable, PRIMARY KEY (id), UNIQUE KEY uk_uid (uid), KEY ix_dbgpt_serve_flow_sys_code (sys_code), KEY ix_dbgpt_serve_flow_uid (uid), KEY ix_dbgpt_serve_flow_dag_id (dag_id), KEY ix_dbgpt_serve_flow_user_name (user_name), KEY ix_dbgpt_serve_flow_name (name) ) ENGINEInnoDB AUTO_INCREMENT15 DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_0900_ai_ci;字段语义与源码印证这张表是 v0.5.0 引入的 AWEL 工作流AWEL Flow的持久化载体。在源码 packages/dbgpt-serve/src/dbgpt_serve/flow/models/models.py 中ServeEntity通过__tablename__ SERVER_APP_TABLE_NAME与之对应关键字段说明uid工作流唯一标识表上有UNIQUE KEY uk_uid保证全局唯一dag_id工作流对应的 DAG有向无环图ID多个版本/条目可关联同一 DAGflow_data以JSON 格式存储完整的流程编排数据节点、算子、连线是核心负载字段state流程状态源码中与dbgpt.core.awel.flow.flow_factory的State枚举联动如INITIALIZING存储的是枚举的字符串值editable是否允许编辑0表示可编辑、1表示不可编辑。源码ServeEntity.parse_editable()负责解析该字段布尔False/整数0解析为可编辑其余为不可编辑to_bool_editable()反向转换为布尔值source/source_url记录流程来源如从应用仓库dbgpts安装时来源标识及下载地址sys_code/user_name多租户与归属信息且均建有索引是列表查询按用户、按系统过滤的高频过滤列。2.2 新增表二gpts_app数据应用 / AI 助手主表CREATE TABLE gpts_app ( id int NOT NULL AUTO_INCREMENT COMMENT autoincrement id, app_code varchar(255) NOT NULL COMMENT Current AI assistant code, app_name varchar(255) NOT NULL COMMENT Current AI assistant name, app_describe varchar(2255) NOT NULL COMMENT Current AI assistant describe, language varchar(100) NOT NULL COMMENT gpts language, team_mode varchar(255) NOT NULL COMMENT Team work mode, team_context text COMMENT The execution logic and team member content that teams with different working modes rely on, user_code varchar(255) DEFAULT NULL COMMENT user code, sys_code varchar(255) DEFAULT NULL COMMENT system app code, created_at datetime DEFAULT NULL COMMENT create time, updated_at datetime DEFAULT NULL COMMENT last update time, icon varchar(1024) DEFAULT NULL COMMENT app icon, url, PRIMARY KEY (id), UNIQUE KEY uk_gpts_app (app_name) ) ENGINEInnoDB AUTO_INCREMENT39 DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_0900_ai_ci;字段语义与源码印证v0.5.0 引入了Data App数据应用概念gpts_app表即应用元数据主表。源码 packages/dbgpt-serve/src/dbgpt_serve/agent/db/gpts_app.py 中GptsAppEntity__tablename__ gpts_app与之对应app_code应用全局唯一编码创建时若未指定源码GptsAppDao.create()会以uuid.uuid1()生成app_name应用名称受UNIQUE KEY uk_gpts_app约束不可重复app_describe应用描述注意其长度为varchar(2255)官方原始定义即如此team_mode团队工作模式是 v0.5.0 的核心概念决定应用如何组织多个 Agent 协作源码中与dbgpt_serve.agent.team.base的TeamMode枚举联动后续版本还出现了native_app等模式值team_context不同工作模式下团队所依赖的执行逻辑与成员编排内容为 text 类型可容纳较长的 JSON 化配置user_code/sys_code应用归属用户与系统编码icon应用图标 URL。2.3 新增表三gpts_app_collection应用收藏表CREATE TABLE gpts_app_collection ( id int(11) NOT NULL AUTO_INCREMENT COMMENT autoincrement id, app_code varchar(255) NOT NULL COMMENT Current AI assistant code, user_code int(11) NOT NULL COMMENT user code, sys_code varchar(255) NOT NULL COMMENT system app code, created_at datetime DEFAULT NULL COMMENT create time, updated_at datetime DEFAULT NULL COMMENT last update time, PRIMARY KEY (id), KEY idx_app_code (app_code), KEY idx_user_code (user_code) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4 COMMENTgpt collections;字段语义与源码印证该表记录哪个用户收藏了哪个应用。源码GptsAppCollectionEntitygpts_app.py通过GptsAppCollectionDao.collect() / uncollect()实现收藏与取消收藏。注意一个已知的原始定义细节user_code列在 DDL 中声明为int(11)而与之配套的收藏查询逻辑中按字符串 user_code 过滤——若你的场景依赖收藏功能且遇到类型异常应结合自身环境评估是否需要将user_code调整为varchar类型。该表通过idx_app_code、idx_user_code两个二级索引支撑用户收藏列表与应用被收藏情况两类高频查询。2.4 新增表四gpts_app_detail应用 Agent 节点明细表CREATE TABLE gpts_app_detail ( id int NOT NULL AUTO_INCREMENT COMMENT autoincrement id, app_code varchar(255) NOT NULL COMMENT Current AI assistant code, app_name varchar(255) NOT NULL COMMENT Current AI assistant name, agent_name varchar(255) NOT NULL COMMENT Agent name, node_id varchar(255) NOT NULL COMMENT Current AI assistant Agent Node id, resources text COMMENT Agent bind resource, prompt_template text COMMENT Agent bind template, llm_strategy varchar(25) DEFAULT NULL COMMENT Agent use llm strategy, llm_strategy_value text COMMENT Agent use llm strategy value, created_at datetime DEFAULT NULL COMMENT create time, updated_at datetime DEFAULT NULL COMMENT last update time, PRIMARY KEY (id), UNIQUE KEY uk_gpts_app_agent_node (app_name,agent_name,node_id) ) ENGINEInnoDB AUTO_INCREMENT23 DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_0900_ai_ci;字段语义与源码印证该表是gpts_app的明细子表一个应用可对应多个 Agent 节点因此gpts_app1对gpts_app_detailN。源码GptsAppDetailEntitygpts_app.py与之对应DAO 层通过_group_app_details()将 detail 按app_code分组后挂载到应用列表返回agent_name应用内某个 Agent 的名称node_id该 Agent 在图编排AWEL中的节点 IDresourcesAgent 绑定的资源数据源、知识库等源码中通过AgentResource.from_json_list_str()反序列化为资源对象列表落库时以 JSON 字符串存储prompt_templateAgent 绑定的提示词模板llm_strategy/llm_strategy_valueAgent 使用 LLM 的策略及其参数值唯一约束uk_gpts_app_agent_node (app_name, agent_name, node_id)保证同一应用内同一 Agent 节点不重复。2.5 新增列gpts_conversations扩展团队协作字段ALTER TABLE gpts_conversations ADD COLUMN team_mode varchar(255) NULL COMMENT agent team work mode; ALTER TABLE gpts_conversations ADD COLUMN current_goal text COMMENT The target corresponding to the current message;字段语义与源码印证gpts_conversations表存储 Agent 团队对话的会话记录。本次为它新增两列team_mode会话所处的Agent 团队工作模式。在源码 packages/dbgpt-serve/src/dbgpt_serve/agent/db/gpts_conversations_db.py 中team_mode Column(...)已作为会话实体字段存在与gpts_app.team_mode呼应——应用定义团队模式会话记录运行时的团队模式current_goal当前消息对应的目标。在 v0.5.0 的多 Agent 协作中会话被拆分为可规划、可追踪的子任务仓库中gpts_plans、gpts_messages表承担了计划与消息明细current_goal记录每一轮对话正在执行的目标为多 Agent 的持续对话与目标拆解提供状态依据。补充说明上述四张新表与两列在仓库 assets/schema/upgrade/v0_5_1/v0.5.0.sql 的 v0.5.0 完整快照中均有完整定义该文件还包含gpts_instance、gpts_messages、gpts_plans、knowledge_space、connect_config等 v0.5.0 全量表结构以及EXAMPLE_1.users示例数据。如果你希望全量重建 v0.5.0 库而非增量升级可以直接参考该快照文件增量升级则严格以本文上述 DDL 为准。第 3 步安装依赖数据库升级完成后需要安装 v0.5.0 对应的依赖。升级文档给出了从源码默认方式安装时的标准命令pip install -e .[default]该命令以可编辑editable模式安装当前源码包及其defaultextra 依赖确保本地源码与pyproject.toml中声明的依赖集保持一致。如果你不是从源码安装例如使用 pip 安装发行包请按你自己的安装方式执行对应的依赖安装命令。第 4 步启动 DB-GPT 服务依赖安装完成后按照你习惯的启动方式重新启动 DB-GPT 服务。启动后建议做如下验证确认服务日志无数据库相关报错登录 Web 界面检查左侧导航是否出现AWEL 工作流AWEL Flow菜单尝试新建/安装一个 AWEL 工作流并创建数据应用Data App验证dbgpt_serve_flow与gpts_app等新表可正常读写。四、源码视角为什么 v0.5.0 需要这些新表升级文档中的四张新表并非孤立存在它们共同支撑 v0.5.0 的核心架构升级。结合 Released_V0.5.0.md 与源码可以还原出以下脉络1. AWELAgentic Workflow Expression Language工作流落地v0.5.0 正式将 DB-GPT 定位为基于 AWEL 与 Agents 的 AI 原生数据应用开发框架。dbgpt_serve_flow表就是 AWEL 工作流定义的持久化层工作流以 JSON 形式flow_data落库运行时由 packages/dbgpt-serve/src/dbgpt_serve/flow 模块service / api / models 三层结构加载并驱动 DAG 执行。工作流的来源既可以是用户自建也可以通过dbgpt app install从官方dbgpts应用仓库安装source/source_url字段即为此设计。2. Data App 应用体系建立gpts_appgpts_app_detailgpts_app_collection三张表构成了 Data App 的主表—明细表—用户收藏完整模型。v0.5.0 之前的六个默认场景ChatData、ChatExcel、ChatDB、ChatKnowledge、ChatAgents、ChatDashboard在后续迭代中逐步被重构为 Data App 形态而应用创建、编辑、列表、收藏、热门排序等能力全部依托这三张表实现。例如源码GptsAppDao.app_list()支持按app_name模糊查询、按team_mode过滤、按is_collected过滤并结合hot_map对应用做热度排序。3. 多 Agent 团队协作会话升级gpts_conversations新增的team_mode与current_goal配合gpts_messages消息明细、gpts_plans子任务计划等表共同支撑 v0.5.0 中多 Agent 协作Team的对话持久化——包括规划—执行—汇报的完整链路这也是数据应用具备持续对话与任务拆解能力的基础。4. 版本边界明确从 v0.5.1 开始仓库将每个版本的升级 SQL 独立归档如 assets/schema/upgrade/v0_5_1/upgrade_to_v0.5.1.sql 即在此次升级后的基础上追加了dbgpt_serve_flow.error_message列因此升级到 v0.5.0 后后续小版本升级同样遵循停止服务 → 执行增量 SQL → 安装依赖 → 启动服务的固定流程。五、升级注意事项与排障建议结合升级文档与仓库实现升级过程中需特别注意以下几点MySQL 必须手动升级v0.5.0 起 MySQL 不再自动建表与自动更新字段跳过 DDL 会导致新功能AWEL 工作流、Data App启动即报表不存在或列不存在错误SQLite 免数据库升级使用默认 SQLite 的用户不需要执行任何 DDL直接进入依赖安装环节即可建表字符集与排序规则升级脚本中dbgpt_serve_flow、gpts_app、gpts_app_detail使用了COLLATEutf8mb4_0900_ai_ci这是 MySQL 8.0 及以上版本的默认排序规则若你的 MySQL 版本低于 8.0如 5.7执行时会报排序规则不存在需要将该 COLLATE 调整为utf8mb4_general_ci后再执行备份先行所有 DDL 操作不可逆务必在升级前完成可验证的备份依赖安装失败排查pip install -e .[default]若因网络或本地 Python 环境失败请先检查 Python 版本是否符合项目pyproject.toml的声明再重试升级失败回滚若升级中途失败可基于第一步的备份恢复数据库回到 v0.4.x 版本继续运行待问题排查后再重新执行升级。结语DB-GPT v0.5.0 的升级本质上是数据库结构的一次关键扩容四张新表为 AWEL 工作流与 Data App 应用体系提供了持久化基础两列新增列为多 Agent 团队会话补上了协作模式与目标追踪能力。只要严格遵循备份 → 停服 → 执行 DDL → 重装依赖 → 启动验证的流程MySQL 用户即可平滑完成从 v0.4.6/v0.4.7 的迁移。升级完成后你就可以在 Web 界面中体验 AWEL 工作流编排、从dbgpts应用仓库安装流程模板并基于多 Agent 构建属于自己的数据应用。【免费下载链接】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），仅供参考