Docs
文档目录

Schema 版本与回滚

功能概述

Schema 版本与回滚(Schema Versions)为 Agentbase 结构化数据库(Databases / TablesDB)提供生产级的数据库结构快照、差异比对(Schema Diff)、物理结构前置校验、并发变更互斥以及结构版本回滚能力。在企业级 AI 与业务系统(如示例项目 企业智能客服与知识中台,Project ID:enterprise-ai-hub-210 下的 企业智能客服业务库 enterprise_biz_db)持续迭代过程中,如果研发人员在生产库上直接零散地手动加列、删列或改索引,极易出现多环境结构漂移、并发 DDL 冲突覆盖或发布中途失败导致服务中断。

通过数据库级 Schema 版本控制(Schema Versioning),可以提交并管理表、列、索引和注释的结构快照(SchemaVersion)。已有普通表或列并不意味着已经创建了结构版本;首次使用时可按实际结构采纳基线。新版本激活前会检查目标结构;操作失败时应查看版本状态和错误信息,再决定后续处理。

数据库结构版本列表:已生效的示例版本

示例展示版本列表中已生效的版本 1。


核心概念与架构

Schema 版本控制引擎围绕“基线采纳(Baseline)或增量迁移(Migration)→ 规范化与哈希幂等(Schema Hash)→ 数据库级单写者互斥锁 → 异步物化与物理对账 → CAS 原子激活 / 指针回滚”构建闭环。下图展示了 Schema 版本从提交、物理校验到状态转换与回滚的完整架构:

Schema 版本与回滚:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心对象(SchemaVersion)与状态机说明

在 enterprise_biz_db 的 Schema 版本 页签或通过 API 获取的每一个版本记录,均包含以下核心元数据与状态语义:

核心字段 / 状态取值与类型架构语义与生产行为说明
schemaVersion正整数(1, 2, 3...)数据库内单调递增的版本序号,列表按版本号倒序排列(最新提交的版本在最上方)。
schemaHash64 位十六进制哈希串对规范化后的目标表、列、索引结构计算的确定性摘要。若重复提交与现有非 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 实时反映执行进度。

角色、入口与关联关系

控制台入口与权限要求

与其他模块的关联关系

  1. 与独立表/列/索引写接口的互斥协调:

    • 同一数据库(projectId + databaseId)下的建表/删表、建列/改列/删列、建索引/删索引与 Schema 版本创建/回滚严格串行互斥。

    • 当数据库已启用并存在 active 状态的 Schema 版本时,零散调用单表/单列结构变更接口会返回 409 保护提示,引导研发通过 createSchemaVersion(或传入完整 columns/indexes 的 updateTable)以完整版本方式提交变更。

    • 例外(零 DDL 注释更新):修改列注释(updateColumnComment)不涉及物理 DDL,允许在存在 active 版本时直接执行,并自动同步生成一个零 DDL 的新 active 元数据版本。

  2. 与双存储模式(Shared V2 & JsonTable)的协同:

    • 在 Shared V2 模式下,Schema 版本驱动底层 OceanBase 物理列与原生索引的增补及对账。

    • 在 JsonTable 模式下,Schema 版本管理 _jt_table_catalog 逻辑目录与侧表索引状态;版本回滚仅切换当前可见的逻辑 Schema 投影,绝不物理抹除 _data JSON 中已写入的历史字段键值。

  3. 与数据库备份(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 版本 页签后:

  1. 浏览版本时间线:列表按版本号(schemaVersion)倒序分页展示版本记录,列出版本号、状态、创建时间和操作;可通过版本号或详情操作查看结构快照与差异。

  2. 检查版本快照与结构差异(Diff Inspection):

    • 点击任意版本行,可查看该版本完整保存的 schemaJson 结构快照(涵盖所有 tables[]、columns[]、indexes[]、注释 comment 以及加密列过滤标记 filters: ["encrypt"])。

    • 对于因前置校验未通过而处于 failed 状态的版本,详情区会直接展示 errorMessage(例如某索引构建冲突或异步删表尚未完成),若已有上一个 active 版本,它仍为生效版本。实际业务读写是否受影响还需结合迁移失败原因与环境验证。

  3. 并发保护行为说明:

    • 当列表中存在处于 pending、running 或 applying 状态的版本,或者库内有正在后台异步执行的删表任务(Pending table deletion)时,页面上的新建提交与回滚操作会自动锁定,防止并发 DDL 竞态破坏元数据一致性。

3. 执行安全回滚(Rollback Schema Version)操作步骤

当新发布的 Schema 版本(例如 v3 新增了若干试验性字段)在业务联调中决定撤回,希望立即切回上一个稳定版本(如 v2)时,可按以下步骤执行回滚:

  1. 进入 enterprise_biz_db 的 Schema 版本 页签,确认当前没有任何处于 pending / running / applying 处理中的任务。

  2. 在历史版本列表中找到状态为 deprecated 的目标稳定版本(如 v2)。

  3. 点击该版本右侧的 Rollback(回滚) 按钮,并在确认弹窗中核对目标版本号与结构摘要后确认提交。

  4. 回滚的即时效果与物理安全边界(极其重要):

    • 切换生效版本:回滚在事务内将目标版本(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.12.0(或 agentbase-console-sdk@2.12.0)将数据库结构变更纳入代码仓库进行声明式版本管理:

// 使用版本固定为 @2.12.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 版本,该如何处理?

原因分析:

  1. 同库存在未完成的异步操作:当前数据库(enterprise_biz_db)下存在状态为 pending、running 或 applying 的 Schema 版本,或者刚刚执行的删除表/创建索引后台 Worker 任务尚未收尾。

  2. 单列接口受 active 版本门禁保护:当数据库已经通过 Schema Versions 托管并存在 active 版本时,直接调用传统的单表/单列物理变更接口会被拦截,以防绕过版本快照产生结构漂移。

解决步骤:

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 备份点执行恢复。


相关文档