---
title: "无锁结构变更 - 开发者中心 ODC V4.3.2 | OceanBase 文档中心"
description: 无锁结构变更 为解决变更数据库表结构时的锁表问题，ODC V4.2.0 及之后的版本提供了无锁结构变更功能，该功能可以较好地规避因锁表以致于阻塞业务。本文档旨在介绍如何通过提交无锁变更工单实现数据库无锁结构变更。 注意 无锁结构变更任务仅支持 OceanBase 数据库的 MySQL 模式，并且需要使用企业版或者社区…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*lqS5SYzz_YEAAAAAAAAAAAAADiGDAQ/original) 开发者中心 ODCV 4.3.2

# 无锁结构变更

更新时间：2026-04-13 15:31:21

[编辑](https://github.com/oceanbase/odc-doc/edit/V4.3.2/zh-CN/700.database-change-management/700.lock-free-schema-change.md)  

为解决变更数据库表结构时的锁表问题，ODC V4.2.0 及之后的版本提供了无锁结构变更功能，该功能可以较好地规避因锁表以致于阻塞业务。本文档旨在介绍如何通过提交无锁变更工单实现数据库无锁结构变更。

#### 注意

无锁结构变更任务仅支持 OceanBase 数据库的 MySQL 模式，并且需要使用企业版或者社区版的 OMS。

## 背景信息

### 原理介绍

无锁结构变更的原理是创建临时表，将原表数据拷贝到临时表中，将临时表结构变更，再全量拷贝数据到原表，最后切换新旧表。

无锁结构变更的执行过程如下图所示：

![1](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/420/sql-development/10.table%20structure%20change/1.png)

1. 创建临时表。
 2. 变更临时表结构。
 3. 全量拷贝数据。
 4. 增量数据同步。
 5. 数据一致性校验。
 6. Kill Session。
 7. 切换新旧表。

### 无锁结构变更工单执行流程

![2](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/420/sql-development/10.table%20structure%20change/2.png)

1. 用户提交无锁结构变更工单。
 2. 对用户输入的 SQL 语句进行预检查。
 3. 审批任务流程。
 4. 执行无锁结构变更任务。

### 支持的变更范围

| **分类** | **操作** | **是否支持** | **备注** |
| --- | --- | --- | --- |
| 列操作 | 列类型修改 | 是 | |
|  | 重排列（before/after/first） | 是 | |
|  | 转换字符集 | 是 | |
|  | 列重命名 | 否 |
|  | 增加列 | 是 |
|  | 删除列 | 否 |
|  | 增加主键列 | 否 |
| 主键 | 增加主键 | 是 | 表存在非空唯一键 |
|  | 修改主键 | 是 | 表存在非空唯一键 |
|  | 删除主键 | 是 | 表存在非空唯一键 |
| 分区 | 删除分区 | 是 | |
|  | truncate 分区 | 是 | |
|  | 重分区 | 是 | |
|  | 非分区表改为分区表 | 是 | |

## 注意事项

- 确保数据库磁盘空间充足。
 - 表中必须**存在主键或非空唯一键**且表中**不存在外键**。
 - 当前表在执行无锁结构变更同时，执行其它 DDL 操作会导致任务失败。
 - OceanBase MySQL 模式下的表名称不超过 54 个字符。
 - ODC 连接 OceanBase 社区版数据库时，数据源配置信息中需包含集群名和 SYS 租户账号。
 - 如果 OceanBase MySQL 模式版本小于 4.3.0，ODC 通过锁定用户且关闭会话的方式避免表名切换过程中数据的写入。
 - 无锁结构变更期间，发起其它关于该表的 DDL 变更将导致任务失败。

## 新建无锁结构变更任务

本文以 OceanBase 社区版和企业版 OMS 为例，演示场景为将表 student 中的列 birth 类型修改为 date。该示例所使用的项目名称为 odc_4.2.0，数据库名称为 odc_test，表名称为 student。

1. （可选）安装 OceanBase 社区版集群。如已完成集群配置，可跳过此步骤。

   #### 说明

   通过企业版 OMS 创建 OceanBase 数据源时需包含集群名，单机无法创建数据源。具体部署集群的方法请参见 [方案二：部署 OceanBase 集群环境](https://open.oceanbase.com/quickStart)。
 2. [安装 ConfigServer](https://github.com/oceanbase/oceanbase/tree/master/tools/ob-configserver)。ConfigServer 为 OceanBase 和 OBProxy 存取 OceanBase rs_list 的接口, 完成配置 OceanBase ConfigServer 地址后，OceanBase 会自动注册 rs_list 到 ConfigServer。

   #### 说明

   通过 OCP（非 OCP-express）部署集群时，可忽略此步骤。OCP 创建的集群会自动设置 OCP 的地址作为 OceanBase ConfigServer。
 3. [安装企业版 OMS](https://www.oceanbase.com/docs/enterprise-oms-doc-cn-1000000000987946)。本文以企业版 OMS 为例，您可以通过 Docker 获取，您也可以按需选择社区版 OMS 并完成配置。
 4. [部署 Web 版 ODC](https://www.oceanbase.com/docs/common-odc-1000000001418151)。
 5. 配置 ODC 元数据信息，启用无锁结构变更。

   a. ODC 配置企业版 OMS 信息。

   连接 ODC 的元数据库，配置企业版 OMS 的 URL 和登录授权信息。 oms_url 的构成为 `http://${oms_host}: ${oms_port}`，oms_authornazition 的构成为 `username:password` 的 Base64 编码。配置完成后，重启 ODC 使配置的企业版 OMS 信息生效。

      - 语法格式：

       ```shell
       #配置 oms_url
       update config_system_configuration set `value` = '${oms_url}' where `key` = 'odc.osc.oms.url';

       #配置 oms_authornazition
       update config_system_configuration set `value` = '${oms_authornazition}' where  `key` = 'odc.osc.oms.authorization';

       #配置 oms_region，例如 cn-anhui
       update config_system_configuration set value = '${oms_region}' where `key` = 'odc.osc.oms.region'

       ```
      - 示例：

       ```shell
       #配置 oms_url，填写 oms 的访问地址：http://localhost:8089
       update config_system_configuration set `value` = 'http://localhost:8089' where `key` = 'odc.osc.oms.url';

       #配置 oms_authornazition，如账户为 test，密码为 123456，将 `test:123456` 进行 Base64 编码后为：dGVzdDoxMjM0NTY=
       update config_system_configuration set `value` = 'dGVzdDoxMjM0NTY=' where `key` = 'odc.osc.oms.authorization';

       #配置 oms_region，如安装 oms 时输入的 region 为 cn-anhui，详情见 oms 安装过程
       update config_system_configuration set value = 'cn-anhui' where `key` = 'odc.osc.oms.region'

       ```

   b. 打开无锁结构变更。目前阿里云数据库 OceanBase 已开放无锁结构变更，而对于 OceanBase 社区版，ODC 默认未启用无锁结构变更，需要配置 ODC 元数据库，通过 SQL 语句打开配置。

   ```
   ```shell
   update config_system_configuration set value = 'true' where `key` = 'odc.features.task.osc.enabled';
   ```

   ```
 6. [在 ODC 中创建和同步数据源](https://www.oceanbase.com/docs/common-odc-1000000001418082)。

   #### 注意

   对于 OceanBase 社区版， 在使用 ODC 创建数据源时，需配置 sys 租户。  
   ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/431/700.database-change-management/700.table-structure-change/2.2.png)
 7. [创建项目并在项目中添加数据库](https://www.oceanbase.com/docs/common-odc-1000000001418149)。
 8. 在 SQL 窗口中，编辑 SQL 语句以创建表 student 到数据库 odc_test 中。

   ![3](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/3.png)
 9. 锁定账号/锁表。

      - 对于 OceanBasese MySQL V4.2.5 之前的版本，变更数据库表结构时不支持锁表，您需要指定将要锁定的账号，切换新旧表（`Rename`）时，ODC 会对锁定的账号执行 `alter table user lock account` 命令并关闭会话操作，以关闭锁定账号下的所有进程。

        ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/432/700.database-change-management/700.lock-free-schema-change/3.0.png)
      - 对于 OceanBasese MySQL V4.2.5 及之后的版本，变更数据库表结构时不再通过锁定账号进行锁表，您需要确认 OBProxy 版本为 V4.3.1 及之后，并在无锁结构变更任务前执行以下操作进行锁表，否则锁表失败。

            1. 修改 OBProxy 参数。

              ```sql
              alter proxyconfig set proxy_id=1;
              alter proxyconfig set client_session_id_version=2;
              alter proxyconfig set enable_single_leader_node_routing = false;

              ```
            2. 修改租户级别参数。

              ```sql
              alter system set enable_lock_priority=true;

              ```
            3. 验证锁表是否成功，通过 ODC 执行 `lock table` 命令锁定一个临时表后，使用新链接尝试插入数据到临时表中，插入数据被阻塞则表示锁表任务生效。

              ```sql
              create table test_table(id int not null primary key);
              session 1:                                      session 2
              lock table test_table;
                                                              insert into test_table values(1);
                                                              阻塞中...
              unlock table test_table;
                                                              插入成功

              ```
 10. 新建无锁结构变更任务。

       1. 在 **工单** 页签中单击 **无锁结构变更** > **新建无锁结构变更**。

          ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/420/sql-development/10.table%20structure%20change/4.png)
       2. 在 **新建无锁结构变更** 页面中，输入以下信息。

          ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/5.png)

         | 信息项 | 说明 |
         | --- | --- |
         | 数据库 | 选择需变更的数据库。 |
         | 锁定用户 | - 如果指定锁定用户，则表名切换之前 ODC 会锁定所指定的数据库账号，并关闭该账号对应的所有会话信息，以保障表名切换期间数据一致性的同时尽可能降低对业务的影响。     - 如果未指定任何账号，ODC 将不会进行任何账号锁定及关闭会话操作，需自主确保切换期间数据的一致性。  #### 注意    执行无锁结构变更任务期间，执行该任务的用户不可执行与无锁结构变更相关表的变更操作。 |
         | 变更定义 | - CREATE TABLE：OceanBasese 不支持的语法需要使用 CREATE 语句。     - ALTER TABLE：OceanBasese V4.0.0 及之后的版本，ALTER TABLE OFFLINE 模式可以使用 ALTER 语句。 |
         | SQL 内容 | 在编辑区中录入 SQL 脚本。 |
         | 切换表设置 | 数据一致后将原表切换为目标表。      - 锁表超时时间：切换表过程会锁表，超时未切换完成可能导致执行失败。     - 失败重试次数：超过锁表时间后，未切换完成可自动重试。     - 完成后源表清理策略：选择 **重命名不处理**，重命名源表，不删除。选择 **立即删除**，无锁结构变更完成后删除源表。 |
         | 任务设置 | - 选择 **立即执行** / **定时执行** 设置任务执行方式。     - 无锁结构变更工具提供两种任务错误处理方式：              - **停止任务**：停止任务为默认方式，运行脚本的过程中出现错误时会停止运行。             - **忽略错误继续任务**：选择忽略错误继续任务方式，在运行脚本出现错后将跳过错误语句继续执行。     - 选择 **自动切换**/**手动切换** 表名。     - 配置限流策略：              - 行限流：每秒操作数据总行限制。             - 数据大小限流：每秒操作数据总大小限制。        #### 注意          仅阿里云数据库 OceanBase 版支持配置限流策略。 |
         | 描述 | 可在 **描述** 文本框中输入不超过 200 个字符的描述信息，该项为选填项。 |
       3. 单击 **新建**，完成新建无锁结构变更。
       4. 任务生成后可以在 **工单** > **无锁结构变更** 列表中查看任务信息。

          ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/6.png)

## 查看无锁结构变更任务

### 查看任务信息

1. 在 **任务中心** 的无锁结构变更列表中，单击操作列中的 **查看** 按钮。
 2. 在弹出的任务详情面板中，单击 **任务信息** 页签查看所属数据库、任务类型、风险等级、SQL 内容和回滚内容等信息。
 3. 单击 **再次发起**，可重新发起无锁结构变更任务。

### 查看任务流程

 ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/8.png)

在任务详情面板中，单击 **任务流程** 页签查看发起任务状态、审批状态、执行状态和执行结果等信息。

### 查看执行记录

 ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/9.png)

在任务详情面板中，单击 **执行记录** 页签查看新表和源表 DDL。

### 查看任务日志

 ![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/odc/423/700.database-change-management/700.table-structure-change/10.png)

在任务详情面板中，单击 **任务日志** 页签查看任务的全部日志和告警日志。

| 信息项 | 说明 |
| --- | --- |
| 全部日志 | 全部日志显示任务的 **INFO** 、 **ERROR** 和 **WARN** 日志等全量信息。 单击 **查找** 、 **下载** 和 **复制** 按钮，可查找信息、下载或复制全部日志信息。 |
| 告警日志 | 告警日志单独显示任务的 **ERROR** 和 **WARN** 日志。当任务失败时，可通过告警日志查看错误信息。 单击 **查找** 、 **下载** 和 **复制** 按钮，可查找信息、下载或复制告警日志信息。 |

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线