ApsaraDB For Oceanbase数据同步能力 - 大数据开发治理平台 DataWorks

ApsaraDB for OceanBase数据源提供读取和写入ApsaraDB for OceanBase数据的双向功能，您可以使用ApsaraDB for OceanBase数据源配置同步任务同步数据。本文为您介绍DataWorks的ApsaraDB for OceanBase数据同步能力支持情况。

支持的版本

离线读写

ApsaraDB For OceanBase Reader和ApsaraDB For OceanBase Writer 支持的 OceanBase 版本。

OceanBase 2.x
OceanBase 3.x
OceanBase 4.x

使用限制

离线读

ApsaraDB For OceanBase包括Oracle和MySQL两种租户模式，您在配置where数据过滤条件、column中的函数列时，需要符合对应租户模式的SQL语法约束，否则SQL语句可能执行失败。
支持读取视图表。
在离线读取OceanBase数据的过程中，请避免对正在同步的数据进行修改操作，否则可能会导致数据质量问题（如数据重复或数据丢失）。

离线写

说明

整个任务需要至少具备insert into...的权限。是否需要其他权限，取决于您配置任务时，在preSql和postSql中指定的语句。

建议您使用batch的方式批量写入数据，当行数累计到预定阈值时，再发起写入请求。
ApsaraDB For OceanBase包括Oracle和MySQL两种租户模式，您在配置preSql、postSql时，需要符合对应租户模式的SQL语法约束，否则SQL语句可能执行失败。

实时读

OceanBase为分布式关系型数据库，可以将物理分布不同的多个数据库上的数据整合为一个完整的逻辑数据库。但实时同步OceanBase的数据至AnalyticDB for MySQL，目前仅支持同步单个物理库的数据，不支持同步逻辑库数据。

说明

在整库实时同步任务中，不支持连接串模式数据源。
在整库实时同步任务中，版本需要在V3.0及以上。

数据同步前准备

在DataWorks上进行数据同步前，您需要参考本文提前在ApsaraDB For OceanBase侧进行数据同步环境准备，以便在DataWorks上进行ApsaraDB For OceanBase数据同步任务配置与执行时服务正常。以下为您介绍ApsaraDB For OceanBase同步前的相关环境准备。

准备工作1：配置白名单

将Serverless资源组或独享数据集成资源组所在的VPC网段添加至OceanBase的白名单中，详情请参见添加白名单。

准备工作2：创建账号并配置账号权限

您需要规划一个数据库的登录账户用于后续执行操作，此账号需要拥有OceanBase的相关操作权限，详情请参见新建账号。

创建数据源

在进行数据同步任务开发时，您需要在DataWorks上创建一个对应的数据源，操作流程请参见创建并管理数据源，详细的配置参数解释可在配置界面查看对应参数的文案提示。

数据同步任务开发

数据同步任务的配置入口和通用配置流程可参见下文的配置指导。

附录：脚本Demo与参数说明

离线任务脚本配置方式

如果您配置离线任务时使用脚本模式的方式进行配置，您需要按照统一的脚本格式要求，在任务脚本中编写相应的参数，详情请参见通过脚本模式配置离线同步任务，以下为您介绍脚本模式下数据源的参数配置详情。

Reader脚本Demo

{
    "type": "job",
    "steps": [
        {
            "stepType": "apsaradb_for_OceanBase", //插件名
            "parameter": {
                "datasource": "", //数据源名
                "where": "",
                "column": [ //字段
                    "id",
                    "name"
                ],
                "splitPk": ""
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "stream",
            "parameter": {
                "print": false,
                "fieldDelimiter": ","
            },
            "name": "Writer",
            "category": "writer"
        }
    ],
    "version": "2.0",
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    },
    "setting": {
        "errorLimit": {
            "record": "0" //错误记录数
        },
        "speed": {
            "throttle": true, //当throttle值为false时，mbps参数不生效，表示不限流；当throttle值为true时,表示限流。
            "concurrent": 1, //作业并发数
            "mbps":"12"//限流，此处1mbps = 1MB/s。
        }
    }
}

Reader脚本参数

参数	描述	是否必选	默认值
datasource	如果您使用的DataWorks版本支持添加ApsaraDB For OceanBase数据源，即可在此处根据数据源名称引用您添加的ApsaraDB For OceanBase数据源。包括jdbcUrl和username两种配置方式。	是	无
jdbcUrl	到对端数据库的JDBC连接信息。使用JSON的数组描述，并支持一个库填写多个连接地址。如果配置了多个，ApsaraDB For OceanBase Reader可以依次探测IP的可连接性，直到选择一个合法的IP。如果全部连接失败，则ApsaraDB For OceanBase Reader报错。说明 jdbcUrl必须包含在connection配置单元中。 jdbcUrl根据ApsaraDB For OceanBase官方规范，可以填写连接附件控制信息。例如`jdbc:oceanbase://127.0.0.1:3306/database`，需要和username配置方式二选一。	否	无
username	数据源的用户名。	否	无
password	数据源指定用户名的密码。	否	无
table	选取的需要同步的表。使用JSON的数组进行描述，支持同时读取多张表。当配置为多张表时，您需要保证多张表的Schema结构一致，ApsaraDB For OceanBase Reader不检查表的逻辑是否统一。说明 table必须包含在connection配置单元中。	是	无
column	所配置的表中需要同步的列名集合，使用JSON的数组描述字段信息。默认使用所有列配置，例如[ * ]。支持列裁剪：可以导出部分列。支持列换序：可以不按照表Schema信息顺序进行导出。支持常量配置：例如`'123'`。支持函数列：例如`date('now')`。 column必须显示指定同步的列集合，不允许为空。	是	无
splitPk	ApsaraDB For OceanBase Reader进行数据抽取时，如果指定splitPk，表示您希望使用splitPk代表的字段进行数据分片，数据同步因此会启动并发任务进行数据同步，提高数据同步的效能。推荐splitPk用户使用表主键，因为表主键通常情况下比较均匀，因此切分出来的分片也不容易出现数据热点。目前splitPk仅支持整型数据切分，不支持字符串、浮点和日期等其它类型。如果您指定其它非支持类型，ApsaraDB For OceanBase Reader将报错。如果设置splitPk值为空，底层将视作您不允许对单表进行切分，因此使用单通道进行抽取。	否	空
where	ApsaraDB For OceanBase Reader根据指定的column、table、where条件拼接SQL，并根据该SQL进行数据抽取。例如，在进行测试时，可以指定where条件为limit 10。在实际业务场景中，通常会选择当天的数据进行同步，指定where条件为`gmt_create>$bizdate`。 where条件可以有效地进行业务增量同步。 where条件不配置或为空，则视作全表同步数据。	否	无
querySql	在部分业务场景中，where配置项不足以描述所筛选的条件，您可以通过该配置型来自定义筛选SQL。配置该项后，数据同步系统会忽略tables、columns和splitPk配置项，直接使用该项配置的内容对数据进行筛选。当您配置querySql时，ApsaraDB For OceanBase Reader直接忽略table、column、where和splitPk条件的配置。	否	无
fetchSize	该配置项定义了插件和数据库服务器端每次批量数据获取条数，该值决定了数据集成和服务器端的网络交互次数，能够较大地提升数据抽取性能。说明 fetchSize值过大（>2048）可能造成数据同步进程OOM。	否	1,024

Writer脚本Demo

{
    "type":"job",
    "version":"2.0",//版本号。
    "steps":[
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"apsaradb_for_OceanBase",//插件名。
            "parameter":{
                "datasource": "数据源名",
                "column": [//字段。
                    "id",
                    "name"
                ],
                "table": "apsaradb_for_OceanBase_table",//表名。
                "preSql": [ //执行数据同步任务之前率先执行的SQL语句。
                    "delete from @table where db_id = -1"
                ],
                "postSql": [//执行数据同步任务之后率先执行的SQL语句。
                    "update @table set db_modify_time = now() where db_id = 1"
                ],
                "obWriteMode": "insert",
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//错误记录数。
        },
        "speed":{
            "throttle":true,//当throttle值为false时，mbps参数不生效，表示不限流；当throttle值为true时,表示限流。
            "concurrent":1, //作业并发数。
            "mbps":"12"//限流，此处1mbps = 1MB/s。
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Writer脚本参数

参数	描述	是否必选	默认值
datasource	如果您使用的DataWorks版本支持添加ApsaraDB For OceanBase数据源，即可在此处根据数据源名称引用您添加的ApsaraDB For OceanBase数据源。包括jdbcUrl和username两种配置方式。	否	无
jdbcUrl	到对端数据库的JDBC连接信息，jdbcUrl包含在connection配置单元中。在一个数据库上只能配置一个值，不支持同一个数据库存在多个主库的情况（双主导入数据情况）。 jdbcUrl的格式和ApsaraDB For OceanBase官方一致，并可连接附加参数信息。例如，`jdbc:oceanbase://127.0.0.1:3306/database`。	是	无
username	数据源的用户名。	是	无
password	数据源指定用户名的密码。	是	无
table	需要同步写出的表名称，使用JSON的数组进行描述。说明 table必须包含在connection配置单元中。	是	无
column	目标表需要写入数据的字段，字段之间用英文所逗号分隔。例如，`"column": ["id", "name", "age"]`。说明 column配置项必须指定，不能为空。	是	无
obWriteMode	控制写入数据至目标表使用的模式，可选配置。 insert：`insert into ...` 当主键或唯一性索引冲突时，无法写入冲突的行。 update：`... on duplicate key update ...` MySQL 租户模式使用，冲突时更新冲突的行。 merge：`merge into ... matched then update ...` Oracle 租户模式使用，冲突时更新冲突的行。	是	insert
onClauseColumns	说明 Oracle租户模式使用，当`obWriteMode`配置为`merge`时必填，未配置时依然会使用`insert`写入数据。配置为主键字段或者唯一约束字段，输入多个字段时使用英文逗号分隔。例如：`ID,C1`。	否	无
obUpdateColumns	说明当`obWriteMode`配置为`merge`或`update`时生效。当数据发生写入冲突时，需要更新的字段，输入多个字段时使用英文逗号分隔。例如：`c2,c3`。	否	所有字段
preSql	写入数据至目标表前，会先执行此处的标准语句。如果SQL中有需要操作的表名称，请使用`@table`表示，以便在实际执行SQL语句时，对变量按照实际表名称进行替换。	否	无
postSql	写入数据至目标表后，会执行此处的标准语句。	否	无
batchSize	一次性批量提交的记录数大小，该值可以极大减少数据同步系统与服务器端的网络交互次数，并提升整体吞吐量。说明 fetchSize值过大（>2048）可能造成数据同步进程OOM。	否	1,024