配置 MySQL 数据源

MySQL 数据源为您提供读取和写入 MySQL 的双向通道数据集成能力，实现不同数据源与 MySQL 之间进行数据传输。
本文为您介绍 DataSail 的 MySQL 数据同步的能力支持情况。

1 支持的版本

• MySQL 离线读写：
  • 支持火山引擎云数据库 MySQL 版；
  • 支持自建 MySQL 5.6.x、MySQL 5.7.x、MySQL 8.0.x。
• VeDB MySQL 离线读写
  • 支持火山引擎云数据库 VeDB MySQL 版。

2 使用前提

1. 子账号新建数据源时，需要有项目的管理员角色，方可以进行新建数据源操作。各角色对应权限说明，详见：管理成员
2. 确保集成同步任务使用的独享数据集成资源组，具有 MySQL 数据库节点的网络访问能力。网络互通方案详见网络连通解决方案。
   • 数据源为 RDS 云数据库实例时，需要将集成资源组所在 VPC 中的 IPv4 CIDR 地址添加到 MySQL 访问白名单中：
     1. 确认集成资源组所在的 VPC：
        
     2. 查看 VPC 的 IPv4 CIDR 地址：

        注意

        若考虑安全因素，减少 IP CIDR 的访问范围，您至少需要将集成资源组绑定的子网下的 IPv4 CIDR 地址加入到数据库白名单中。

        
     3. 将获取到的 IPv4 CIDR 地址添加进 MySQL 数据库白名单中，添加操作详见创建白名单。
        
   • 数据源为公网自建数据源，需通过公网形式访问：
     • 集成资源组开通公网访问能力，操作详见开通公网。
     • 并将公网 IP 地址，添加进 MySQL 数据库白名单中。

3 支持的字段类型

当前主要字段类型支持情况如下:

4 数据同步任务开发

4.1 数据源注册

新建数据源操作详见配置数据源，以下为您介绍不同接入方式的 MySQL 数据源配置相关信息：

1. 火山引擎 MySQL 数据源

   注意

   • 离线读 MySQL 数据时，配置的账号需拥有同步表的读 (SELECT) 权限。
   • 离线写 MySQL 数据时，配置的账号需拥有同步表的写（INSERT、DELETE、UPDATE）权限。
   • 需要将资源组关联 VPC 中的 IPv4 CIDR 地址添加进数据库白名单中。

   参数	说明
   基本配置
   数据源类型	MySQL
   接入方式	火山引擎 MySQL
   数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
   参数配置
   RDS 实例 ID	火山引擎云数据库MySQL的实例ID，下拉选择。
   数据库名	下拉选择实例下，已创建的 MySQL 数据库名称。
   用户名	有权限访问数据库的用户名信息。
   密码	输入用户名对应的密码信息。

2. 连接串形式 MySQL 数据源

   注意

   MySQL 侧如果是白名单访问机制，则不同网络环境的连接串地址，需要添加不同的 IP 地址到数据库白名单中，确保集成资源组使用的 VPC 与 MySQL 网络能互通：

   • 如果使用的是公网连接串访问，则需要给集成资源组添加公网 IP，并将公网 IP 地址加入到白名单中。
   • 如果使用的是私网连接串访问，则需要将资源组 VPC 下的 IPv4 CIDR 地址加入到白名单中。

   详见网络连通解决方案。

   参数	说明
   基本配置
   数据源类型	MySQL
   接入方式	连接串
   数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
   参数配置
   主机名或IP地址	MySQL 数据库的主机名称或者 IP 地址。
   端口	主机的端口号。
   数据库名	输入已创建的 MySQL 数据库名称。
   用户名	有权限访问数据库的用户名信息。
   密码	输入用户名对应的密码信息。

4.2 新建任务

MySQL 数据源测试连通性成功后，进入到数据开发界面，开始新建 MySQL 相关通道任务。
新建任务方式详见离线数据同步、流式数据同步。

4.3 可视化配置说明

任务创建成功后，您可根据实际场景，配置MySQL 批式读、MySQL 批式写或 MySQL 流式写等通道任务。

4.3.1 MySQL 批式读

数据来源选择 MySQL，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

4.3.2 MySQL 批式写

数据目标端选择 MySQL，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

4.3.3 MySQL 流式写

支持可视化方式配置流式写入 MySQL 单表。MySQL Writer 通过 JDBC 远程连接 MySQL 数据库，并执行相应的 SQL 语句，将数据写入 MySQL。流式写入 MySQL 配置方式如下：

数据目标端选择 MySQL，并完成以下相关参数配置：
其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

4.3.4 字段映射

数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
您可通过以下三种方式操作字段映射关系：

• 自动添加：单击自动添加按钮，根据两端数据表信息，可以自动填充来源和目标的字段信息。
• 手动添加：单击手动添加按钮，可以手动编辑来源和目标的字段信息，可以逐个添加。

  说明

  来源端字段信息支持输入数据库函数和常量配置，单击手动添加按钮，在源表字段中输入需添加的值，并选择函数或常量类型，例如：

  • 函数：支持您输入 now()、current_timestamp()、unix_timestamp() 等 MySQL 数据库支持的函数。
  • 常量：您可自定义输入常量值，'123'、'${DATE}'、'${hour}' 等，输入值两侧需要加上英文单引号，支持结合平台时间变量与常量说明使用。
• 移动\删除字段：您也可以根据需要移动字段映射顺序或删除字段。

  说明

  对于来源是分库分表形式时，会拉取配置的第一张表的元数据信息。

4.4 DSL 配置说明

MySQL 数据源支持使用脚本模式（DSL）的方式进行配置。
在某些复杂场景下，您可通过任务脚本的方式，按照统一的 Json 格式，编写 MySQL Reader 和 MySQL Writer 参数脚本代码，来运行数据集成任务。

4.4.1 进入 DSL 模式

1. 在可视化任务编辑界面，单击上方工具栏切换至脚本模式按钮，进入编辑界面。

   注意

   切换脚本模式将清空现有可视化界面配置，一旦切换无法撤销。

   
2. 首次使用 DSL 模式配置时，您可通过单击界面导入脚本模板按钮，在模板的基础上，进行相应配置的修改，提升任务配置效率。
   

   注意

   导入新的脚本模版将清空现有内容，一旦导入无法撤销。

   以下分别为您介绍 MySQL 数据源批式读和批式写的示例脚本，您可根据实际情况替换相应参数：

4.4.1 MySQL 批式读

MySQL 批式读脚本示例如下：

// 变量使用规则如下:
// 1.自定义参数变量: {{}}, 比如{{number}}
// 2.系统时间变量${}, 比如 ${date}、${hour}
// **************************************
{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] execution mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        // [required] datasource type
        "type": "mysql",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": 12345,
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
            "columns": [
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ],
            "filter": "id > 10",
            "split_pk": "split_pk_sample",
            "table_name": "table_name_sample"
        }
    },
    // writer config
    "writer": {
    },
    // common config
    "common": {
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
        }
    }
}

Reader 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

4.4.2 MySQL 批式写

MySQL 批式写脚本示例如下：

// **************************************
// 变量使用规则如下:
// 1.自定义参数变量: {{}}, 比如{{number}}
// 2.系统时间变量${}, 比如 ${date}、${hour}
// **************************************
{
    // [required] dsl version, suggest to use latest version
    "version": "0.2",
    // [required] execution mode, supoort streaming / batch now
    "type": "batch",
    // reader config
    "reader": {
        // [required] datasource type
        "type": "xx",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": null,
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
          
        }
    },
    // writer config
    "writer": {
        // [required] datasource type
        "type": "mysql",
        // [optional] datasource id, set it if you have registered datasource
        "datasource_id": 12345,
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
            "table_name":"table_1",
            "pre_sql_list":[""],
            "post_sql_list":[""],
            "write_mode":"overwrite",
            "columns": [
                {
                    "name": "name_sample",
                    "type": "type_sample"
                }
            ]
        }
    },
    // common config
    "common": {
        // [required] user parameter
        "parameter": {
            // ********** please write here **********
            // "key" : value
        }
    }
}

Writer 参数说明，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：

4.5 高级参数说明

• 对于通道任务，读参数需要加上 job.reader. 前缀，写参数需要加上 job.writer. 前缀，如下图所示：
  
• 对于 DSL 任务，读参数请配置到 reader.parameter 下，写参数请配置到 writer.parameter 下，直接输入参数名称和参数值。如下图所示：
  

4.5.1 MySQL 批式读

批式读支持以下高级参数，您可根据实际情况进行配置：

4.5.2 MySQL 批式写

批式写支持以下高级参数，您可根据实际情况进行配置：

5 最佳实践

5.1 MySQL 离线写实现 TTL

离线任务写入 MySQL 方式，MySQL 数据表中只保存最近一天的数据：

1. 配置写入前语句:
   假设表名为 table_name , TTL 字段为 date，只保存最近一天的数据，您需输入以下语句：delete from table_name wheredate<= "${date-1}"

   说明

   date 为数据库关键字，故需要用 ` 括起转义。

   
2. 数据写入方式配置为 insert into。

5.2 MySQL 离线写实现幂等

对于 MySQL 离线写，使用 insert into 写入方式时，重跑任务可能产生两种结果：

1. 重跑失败：写入字段中配置主键或者唯一键字段，任务由于 duplicate key 写入失败；
2. 数据重复：写入字段中没有配置主键，数据重复写入。

因此为了任务重跑时可实现幂等，可以有以下几种解决方案：

1. 将数据写入方式修改为 on duplicate key update 或者 replace into 。
2. 使用 insert into ，并配置高级参数 job.writer.is_insert_ignore 为 true。