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 MySQL 云数据库实例时，需要将资源所在 VPC 中的 IPv4 CIDR 地址添加到 MySQL 访问白名单中：

     注意

     • 如果 MySQL 数据源实例所在的 VPC 和独享集成资源组所在的 VPC 相同时，您仅需将 VPC 中的 IPv4 CIDR 地址添加到 MySQL 访问白名单中；
     • 如果 MySQL 数据源实例所在的 VPC 和独享集成资源组所在的 VPC 不同时，您需要先通过 CEN 云企业网打通两个 VPC 网络，然后将集成资源组 VPC 和 MySQL 所在 VPC 中的两个 IPv4 CIDR 地址，均添加到 MySQL 访问白名单中。
     1. 确认集成资源组所在的 VPC：
        
     2. 查看 VPC 的 IPv4 CIDR 地址：
        
     3. 将获取到的 IPv4 CIDR 地址添加进 MySQL 数据库白名单中，添加操作详见创建白名单。
        
   • 数据源为公网自建数据源，需通过公网形式访问：
     • 集成资源组开通公网访问能力，操作详见开通公网。
     • 并将公网 IP 地址，添加进 MySQL 数据库白名单中。

3 支持的字段类型

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

4 数据同步任务开发

4.1 数据源注册

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

1. 火山引擎 MySQL 数据源

   注意

   • 离线读 MySQL 数据时，配置的账号需拥有同步表的读 (SELECT) 权限。
   • 离线写 MySQL 数据时，配置的账号需拥有同步表的写（INSERT、DELETE、UPDATE）权限。
   • 数据同步解决方案使用该 MySQL 数据源，配置实时方案读取 Binlog 时，需要先执行以下授权 SQL 命令给配置的账号：GRANT SELECT, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';
   • 数据同步解决方案使用 VeDB 数据源配置时，需给数据源中配置的用户执行以下授权 SQL 命令：GRANT SELECT, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' ;
   • 网络相关配置详见上方2 使用前提说明。

   参数	说明
   基本配置
   数据源类型	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 字段映射

数据来源和目标端配置完成后，需要指定来源和目标端的字段映射关系，根据字段映射关系，数据集成任务将源端字段中的数据，写入到目标端对应字段中。
字段映射支持选择基础模式和转换模式配置映射：

• 转换模式：
  字段映射支持数据转换，您可根据实际业务需求进行配置，将源端采集的数据，事先通过数据转换后，以指定格式输入到目标端数据库中。
  转换模式详细操作说明详见4.1 转换模式
  在转换模式中，你可依次配置：来源节点、数据转换、目标节点信息：

  配置节点	说明
  来源节点	配置数据来源 Source 节点信息： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 数据字段：通过自动添加、手动添加等方式添加数据来源字段信息。 配置完成后，单击确认按钮，完成来源节点配置。
  数据转换	单击数据转换右侧添加按钮，选择 SQL 转换方式，配置转换信息和规则： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 SQL 脚本：输入 SQL 脚本转换规则，目前仅支持添加一个转换的 SQL 语句，且不能包括 “;”。 配置完成后，单击确认按钮，完成数据转换节点配置。SQL 脚本示例详见4.1.2 添加转换节点。
  目标节点	配置目标节点 Sink 信息： 节点名称：自定义输入来源节点名称信息，只允许由数字、字母、下划线、-和.组成；且长度不能超过10。 数据字段：通过自动添加、手动添加等方式添加数据目标字段信息。 配置完成后，单击确认按钮，完成目标节点配置。

• 基础模式：

  您可通过以下三种方式操作字段映射关系：

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

    说明

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

    • 函数：支持您输入 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。