Schema 版本与回滚
功能概述
Schema 版本与回滚(Schema Versions)为 Agentbase 结构化数据库(Databases / TablesDB)提供生产级的数据库结构快照、差异比对(Schema Diff)、物理结构前置校验、并发变更互斥以及零数据破坏的秒级版本回滚能力。在企业级 AI 与业务系统(如示例项目 企业智能客服与知识中台,Project ID:enterprise-ai-hub-210 下的 企业智能客服业务库 enterprise_biz_db)持续迭代过程中,如果研发人员在生产库上直接零散地手动加列、删列或改索引,极易出现多环境结构漂移、并发 DDL 冲突覆盖或发布中途失败导致服务中断。
通过引入数据库级 Schema 版本控制(Schema Versioning),每一次针对 enterprise_biz_db 内表(Tables)、列(Columns)、索引(Indexes)及业务注释(Comments)的结构变更都以不可变的版本快照(SchemaVersion)形式提交。系统在激活新版本前会自动比对并校验底层 OceanBase 物理结构(兼容 Shared V2 与 JsonTable 两种存储模式):只有当物理表、列与索引完全物化且校验一致时才原子切换生效版本指针;若校验失败(含自动重试一次后仍失败),当前正在生效的 active 版本继续无缝对外提供服务,彻底杜绝“半成品结构”上线引发的生产故障。
核心概念与架构
Schema 版本控制引擎围绕“基线采纳(Baseline)或增量迁移(Migration)→ 规范化与哈希幂等(Schema Hash)→ 数据库级单写者互斥锁 → 异步物化与物理对账 → CAS 原子激活 / 指针回滚”构建闭环。下图展示了 Schema 版本从提交、物理校验到状态转换与回滚的完整架构:
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
核心对象(SchemaVersion)与状态机说明
在 enterprise_biz_db 的 Schema Versions 页签或通过 API 获取的每一个版本记录,均包含以下核心元数据与状态语义:
| 核心字段 / 状态 | 取值与类型 | 架构语义与生产行为说明 |
|---|---|---|
schemaVersion | 正整数(1, 2, 3...) | 数据库内单调递增的版本序号,列表按版本号倒序排列(最新提交的版本在最上方)。 |
schemaHash | 64 位十六进制哈希串 | 对规范化后的目标表、列、索引结构计算的确定性摘要。若重复提交与现有非 failed 版本具有相同 schemaHash 的请求,接口按幂等语义直接返回 200 及已有版本对象。 |
status = pending / running / applying | 处理中中间态 | 表示当前版本正在排队、执行底层结构变更或进行激活前物理对账。当同库存在处于这三个状态之一的版本时,新的结构提交与回滚按钮均自动禁用(API 返回 409)。 |
status = active | 当前生效态 | 同一时刻一个数据库最多只有一个 active 版本。数据面读写请求以当前 active 版本的 schemaJson 作为可见表与列的权威投影基准。 |
status = deprecated | 历史已退役态 | 曾经作为 active 生效、后被新版本替代(或因回滚切走)的历史版本。可随时作为 Rollback(回滚) 的目标版本。 |
status = failed | 失败关闭态 | 迁移执行或激活前物理结构校验失败(系统对可重试错误最多自动重投 1 次,再次失败即定格为 failed)。此时原 active 版本保持不变并继续正常服务,errorMessage 字段记录详细原因供修正后重新提交。 |
stepsTotal / stepsCompleted | 整数进度指标 | 展示当前版本迁移计划(migrationPlanJson)中的总步骤数与已完成步骤数,配合 lastHeartbeatAt 实时反映执行进度。 |
角色、入口与关联关系
控制台入口与权限要求
导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧栏 Databases → 点开数据库企业智能客服业务库(enterprise_biz_db)→ 点击顶部 Schema 版本(Schema Versions) 页签。路由地址:
/console/project-{region}-{project}/databases/database-{databaseId}/schema-versions操作权限门禁:
查看 Schema 版本列表、版本号、结构哈希与差异详情需要
databases.read权限(owner、admin、developer、editor、analyst)。提交新 Schema 版本(Baseline 或 Migration)以及执行版本回滚(Rollback)需要
databases.write权限(owner、admin、developer、editor)。
与其他模块的关联关系
与独立表/列/索引写接口的互斥协调:
同一数据库(
projectId + databaseId)下的建表/删表、建列/改列/删列、建索引/删索引与 Schema 版本创建/回滚严格串行互斥。当数据库已启用并存在
active状态的 Schema 版本时,零散调用单表/单列结构变更接口会返回409保护提示,引导研发通过createSchemaVersion(或传入完整columns/indexes的updateTable)以完整版本方式提交变更。例外(零 DDL 注释更新):修改列注释(
updateColumnComment)不涉及物理 DDL,允许在存在active版本时直接执行,并自动同步生成一个零 DDL 的新active元数据版本。
与双存储模式(
Shared V2&JsonTable)的协同:在
Shared V2模式下,Schema 版本驱动底层 OceanBase 物理列与原生索引的增补及对账。在
JsonTable模式下,Schema 版本管理_jt_table_catalog逻辑目录与侧表索引状态;版本回滚仅切换当前可见的逻辑 Schema 投影,绝不物理抹除_dataJSON 中已写入的历史字段键值。
与数据库备份(Backups)的边界区分:
Schema Versions 保护的是“表结构定义与可见性一致性”(结构级版本控制),回滚版本不会删除或回退业务行数据;若需将表内行记录内容恢复到过去某个时间点,请结合 备份与恢复(Backups) 使用。
功能详解与操作指南
1. 两种版本提交模式:首次基线(baseline)vs 增量演进(migration)
在将业务数据库(如 enterprise_biz_db)纳入 Schema 多版本治理时,Agentbase 提供两种提交模式:
| 提交模式 | 适用时机 | 底层执行与校验机制 | 关键返回码与约束 |
|---|---|---|---|
baseline(基线采纳模式) | 数据库首次开启 Schema 版本控制(当前库尚无任何现存 SchemaVersion 记录),希望将线上已稳定运行的表结构(如 customer_tickets)原样采纳为第 1 个版本(v1)。 | 服务端连续两次读取完整的运行时权威结构(Canonical Schema),并与请求提交的 schema 做严格一致性比对。对账完全一致时,不触发任何物理建表/加列/建索引 Worker,在单事务内直接写入 v1 并置为 active(stepsTotal=0)。 | 若数据库已有版本记录,禁止使用 baseline;若对账发现提交结构与当前实际运行结构不符或导出期间发生并发漂移,返回 409 schema_baseline_stale。 |
migration(常规迁移模式,默认) | 日常迭代演进(如为 customer_tickets 表新增 satisfactionScore 评分列、resolvedAt 结单时间列或新增复合索引)。 | 计算提交的目标 schema 与当前 active 版本快照的结构差异(Diff):若仅含注释等零 DDL 变更则直接激活;若包含新增表/列/索引等物理变更,则生成迁移计划并交由后台 Worker 执行,完成后经物理对账激活为新 active 版本。 | 不允许直接修改已有列的物理类型(Type)或缩小字符串列长度(Size),此类破坏性变更会直接返回 400 拦截,建议采用“新增列 + 迁移数据 + 新版本隐藏旧列”的 Expand-Contract 模式。 |
2. 查看 Schema 版本列表、结构差异与状态诊断
在数据库详情页进入 Schema Versions 页签后:
浏览版本时间线:列表按版本号(
schemaVersion)从高到低倒序展示最近的版本记录(最多返回最近 50 个版本),每行清晰展示 版本号(如v3、v2、v1)、状态徽标(active、deprecated、applying、failed)、结构哈希(schemaHash)、步骤进度(stepsCompleted / stepsTotal) 以及 提交时间($createdAt)。检查版本快照与结构差异(Diff Inspection):
点击任意版本行,可查看该版本完整保存的
schemaJson结构快照(涵盖所有tables[]、columns[]、indexes[]、注释comment以及加密列过滤标记filters: ["encrypt"])。对于因前置校验未通过而处于
failed状态的版本,详情区会直接展示errorMessage(例如某索引构建冲突或异步删表尚未完成),同时您会看到上一个active版本依然保持绿色生效状态,线上业务读写零中断。
并发保护行为说明:
当列表中存在处于
pending、running或applying状态的バージョン,或者库内有正在后台异步执行的删表任务(Pending table deletion)时,页面上的新建提交与回滚操作会自动锁定,防止并发 DDL 竞态破坏元数据一致性。
3. 执行安全回滚(Rollback Schema Version)操作步骤
当新发布的 Schema 版本(例如 v3 新增了若干试验性字段)在业务联调中决定撤回,希望立即切回上一个稳定版本(如 v2)时,可按以下步骤执行回滚:
进入
enterprise_biz_db的 Schema Versions 页签,确认当前没有任何处于pending/running/applying处理中的任务。在历史版本列表中找到状态为
deprecated的目标稳定版本(如v2)。点击该版本右侧的 Rollback(回滚) 按钮,并在确认弹窗中核对目标版本号与结构摘要后确认提交。
回滚的即时效果与物理安全边界(极其重要):
生效指针秒级切换:回滚操作仅在事务内将目标版本(
v2)的状态重新切换为active,并将原版本(v3)标记为deprecated,同步更新列的schemaStatus观测状态与注释快照。绝不执行物理
DROP COLUMN/DROP TABLE:为了彻底杜绝误回滚导致生产数据永久丢失,回滚操作不执行任何破坏性物理 DDL,也不删除底层已写入的行数据。在v3期间写入的新列数据会被安全保留在底层存储中,只是在v2的active投影下对应用层隐藏。如何使物理结构与目标版本再次完全对齐:如果回滚后还需要进一步调整物理索引或新增其他字段,只需基于
v2的结构定义修改后再次提交一个新的migration版本即可。
4. 通过 Server / Console SDK 编排 Schema 版本发布代码示例
在企业 CI/CD 发布流水线中,推荐使用 agentbase-node-sdk@2.10.0(或 agentbase-console-sdk@2.10.0)将数据库结构变更纳入代码仓库进行声明式版本管理:
// 使用版本固定为 @2.10.0 的 Agentbase SDK 执行声明式 Schema 版本发布与回滚
// 对应 REST 端点: POST /v1/tablesdb/{databaseId}/schema/versions
async function deployTicketSchemaVersion(tablesDB) {
// 1. 提交增量 Schema 版本 (mode: "migration")
const version = await tablesDB.createSchemaVersion({
databaseId: 'enterprise_biz_db',
mode: 'migration', // 首次接入无版本库时可传 'baseline'
schema: {
tables: [
{
tableId: 'customer_tickets',
name: '客户工单表',
comment: '企业智能客服工单主表(含 SLA 与满意度评分)',
columns: [
{ key: 'ticketNo', type: 'varchar', size: 64, required: true, comment: '工单唯一业务编号' },
{ key: 'title', type: 'varchar', size: 256, required: true, comment: '工单问题摘要标题' },
{ key: 'priority', type: 'enum', elements: ['P0', 'P1', 'P2'], required: true, comment: '紧急程度' },
{ key: 'status', type: 'enum', elements: ['open', 'processing', 'resolved', 'closed'], required: true, comment: '处理状态' },
{ key: 'creatorUserId', type: 'varchar', size: 36, required: true, comment: '提单终端用户 ID' },
{ key: 'satisfactionScore', type: 'float', required: false, comment: '结单客户满意度评分 (1.0-5.0)' }
],
indexes: [
{ key: 'uk_ticket_no', type: 'unique', attributes: ['ticketNo'], orders: ['ASC'] },
{ key: 'idx_status_priority', type: 'key', attributes: ['status', 'priority'], orders: ['ASC', 'ASC'] },
{ key: 'ft_title', type: 'fulltext', attributes: ['title'] }
]
}
]
}
});
console.log(`已提交 Schema 版本 v${version.schemaVersion},当前状态: ${version.status}`);
// 2. 如需在发布异常时秒级回滚至指定历史版本 versionId:
// const rolledBack = await tablesDB.rollbackSchemaVersion({
// databaseId: 'enterprise_biz_db',
// versionId: '<PREVIOUS_ACTIVE_VERSION_ID>'
// });
}常见问题与排障
Q1:提交新的 Schema 版本或单独调用建列接口时返回 409 Conflict,提示已有正在进行的迁移或已存在 active 版本,该如何处理?
原因分析:
同库存在未完成的异步操作:当前数据库(
enterprise_biz_db)下存在状态为pending、running或applying的 Schema 版本,或者刚刚执行的删除表/创建索引后台 Worker 任务尚未收尾。单列接口受 active 版本门禁保护:当数据库已经通过 Schema Versions 托管并存在
active版本时,直接调用传统的单表/单列物理变更接口会被拦截,以防绕过版本快照产生结构漂移。
解决步骤:
前往 Databases →
enterprise_biz_db→ Schema Versions 页签,查看最新版本的进度(stepsCompleted / stepsTotal)。待其变为active或failed后锁会自动释放。已被 Schema Versions 托管的数据库,请统一通过提交新 Schema 版本(
createSchemaVersion)或包含完整结构的updateTable接口管理结构演进。
Q2:使用 mode: "baseline" 初始化第一个版本时,为什么返回 409 schema_baseline_stale?
原因分析: baseline 模式的设计初衷是“零 DDL 原样采纳当前线上结构为 v1”。服务端在受理 baseline 请求时,会连续读取两次数据库当前的真实运行态结构并与您请求体中传入的 schema 比对。如果请求体里多写了线上还不存在的列/表,或者少写了线上已有的列,又或者在采纳瞬间正好有其他人在修改表结构,服务端就会触发 Fail-Closed 保护并返回 409 schema_baseline_stale。
解决步骤: 请先确保没有其他并发 DDL 操作,如果您的目的是在采纳的同时新增列或修改结构,请先用与线上完全一致的结构执行 baseline 生成 v1,随后再使用默认的 mode: "migration" 提交包含新增列的 v2 版本。
Q3:执行了 Schema 版本回滚(例如从 v4 回滚到 v3),为什么之前在 v4 中误删的一条工单行记录没有恢复回来?
回答: Schema 版本回滚仅针对“表结构与字段可见性(Schema Projection)”,不回退业务行数据(Row Data)。回滚操作只将生效的 Schema 快照指针切回 v3(且不会执行物理 DROP),但不会恢复已经被 DML DELETE 或 UPDATE 修改的业务行记录。如果需要恢复被误删的业务行数据,请前往 备份与恢复(Backups) 选择误操作之前的 Complete 备份点执行恢复。
相关文档
数据库概览(Databases Overview):了解数据库整体架构与
Shared V2/JsonTable存储模式。表、列、行与索引(Tables):查看受 Schema 版本管理的表、列类型、注释与索引细节。
备份与恢复(Backups):结合数据级备份快照与 Schema 版本控制,构建结构与数据双重防线。
SQL 访问面(SQL Proxy):了解受控 DDL 与查询在 SQL 层的执行规则。
