使用手册

使用手册

环境要求

纯 JAVA 开发，JDK 建议 1.8 以上版本。

支持迁移场景如下：

源端目标端
MySQL(5.1.15 ~ 5.7.x)MySQL(5.1.15 ~ 5.7.x)
PostgreSQL(9.4 ~ )PostgreSQL(9.4 ~ )
openGauss(2.1.0)openGauss(2.1.0)

注意：

如果后端连接以下数据库，请下载相应JDBC驱动jar包，并将其放入 ${shardingsphere-proxy}/lib 目录。

数据库JDBC驱动参考
MySQLmysql-connector-java-5.1.47.jarConnector/J Versions
openGaussopengauss-jdbc-2.0.1-compatibility.jar

功能支持情况：

功能MySQLPostgreSQLopenGauss
全量迁移支持支持支持
增量迁移支持支持支持
自动建表支持不支持支持
DATA_MATCH一致性校验支持支持支持
CRC32_MATCH一致性校验支持不支持不支持

注意：

还没开启自动建表的数据库需要手动创建分表。

权限要求

MySQL

  1. 开启 binlog

MySQL 5.7 my.cnf 示例配置：

  1. [mysqld]
  2. server-id=1
  3. log-bin=mysql-bin
  4. binlog-format=row
  5. binlog-row-image=full
  6. max_connections=600

执行以下命令，确认是否有开启binlog：

  1. show variables like '%log_bin%';
  2. show variables like '%binlog%';

如以下显示，则说明binlog已开启

  1. +-----------------------------------------+---------------------------------------+
  2. | Variable_name                           | Value                                 |
  3. +-----------------------------------------+---------------------------------------+
  4. | log_bin                                 | ON                                    |
  5. | binlog_format                           | ROW                                   |
  6. | binlog_row_image                        | FULL                                  |
  7. +-----------------------------------------+---------------------------------------+
  1. 赋予 MySQL 账号 Replication 相关权限。

执行以下命令，查看该用户是否有迁移权限：

  1. SHOW GRANTS 'user';

示例结果：

  1. +------------------------------------------------------------------------------+
  2. |Grants for ${username}@${host}                                                |
  3. +------------------------------------------------------------------------------+
  4. |GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO ${username}@${host}     |
  5. |.......                                                                       |
  6. +------------------------------------------------------------------------------+

PostgreSQL

  1. 开启 test_decoding

  2. 调整 WAL 配置

postgresql.conf 示例配置：

  1. wal_level = logical
  2. max_replication_slots = 10

详情请参见 Write Ahead Log 和 Replication。

DistSQL 自动模式接口

预览当前分片规则

示例：

  1. preview select count(1) from t_order;

返回信息：

  1. mysql> preview select count(1) from t_order;
  2. +------------------+--------------------------------+
  3. | data_source_name | sql                            |
  4. +------------------+--------------------------------+
  5. | ds_0             | select count(1) from t_order_0 |
  6. | ds_0             | select count(1) from t_order_1 |
  7. | ds_1             | select count(1) from t_order_0 |
  8. | ds_1             | select count(1) from t_order_1 |
  9. +------------------+--------------------------------+
  10. 4 rows in set (0.00 sec)

创建迁移任务

  1. 添加新的数据源

详情请参见RDL#数据源资源。

先在底层数据库系统创建需要的分库，下面的 DistSQL 需要用到。

示例：

  1. ADD RESOURCE ds_2 (
  2.     URL="jdbc:mysql://127.0.0.1:3306/scaling_ds_2?serverTimezone=UTC&useSSL=false",
  3.     USER=root,
  4.     PASSWORD=root,
  5.     PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000")
  6. ), ds_3 (
  7.     URL="jdbc:mysql://127.0.0.1:3306/scaling_ds_3?serverTimezone=UTC&useSSL=false",
  8.     USER=root,
  9.     PASSWORD=root,
  10.     PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000")
  11. ), ds_4 (
  12.     URL="jdbc:mysql://127.0.0.1:3306/scaling_ds_4?serverTimezone=UTC&useSSL=false",
  13.     USER=root,
  14.     PASSWORD=root,
  15.     PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000")
  16. );
  1. 修改所有表的分片规则

目前只有通过执行 ALTER SHARDING TABLE RULE DistSQL 来触发迁移。

详情请参见RDL#数据分片。

SHARDING TABLE RULE支持2种类型：TableRule和AutoTableRule。以下是两种分片规则的对比：

类型AutoTableRule（自动分片）TableRule（自定义分片）
定义自动化分片算法自定义分片算法

DistSQL 字段含义和 YAML 配置保持一致，详情请参见YAML配置#数据分片。

AutoTableRule修改示例：

  1. ALTER SHARDING TABLE RULE t_order (
  2. RESOURCES(ds_2, ds_3, ds_4),
  3. SHARDING_COLUMN=order_id,
  4. TYPE(NAME=hash_mod,PROPERTIES("sharding-count"=6)),
  5. GENERATED_KEY(COLUMN=order_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
  6. );

RESOURCES 从 (ds_0, ds_1) 改为了 (ds_2, ds_3, ds_4)，sharding-count 从 4 改为了 6，会触发迁移。

TableRule修改示例：

  1. ALTER SHARDING ALGORITHM database_inline (
  2. TYPE(NAME=INLINE,PROPERTIES("algorithm-expression"="ds_${user_id % 3 + 2}"))
  3. );
  5. ALTER SHARDING TABLE RULE t_order (
  6. DATANODES("ds_${2..4}.t_order_${0..1}"),
  7. DATABASE_STRATEGY(TYPE=standard,SHARDING_COLUMN=user_id,SHARDING_ALGORITHM=database_inline),
  8. TABLE_STRATEGY(TYPE=standard,SHARDING_COLUMN=order_id,SHARDING_ALGORITHM=t_order_inline),
  9. GENERATED_KEY(COLUMN=order_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
  10. ), t_order_item (
  11. DATANODES("ds_${2..4}.t_order_item_${0..1}"),
  12. DATABASE_STRATEGY(TYPE=standard,SHARDING_COLUMN=user_id,SHARDING_ALGORITHM=database_inline),
  13. TABLE_STRATEGY(TYPE=standard,SHARDING_COLUMN=order_id,SHARDING_ALGORITHM=t_order_item_inline),
  14. GENERATED_KEY(COLUMN=order_item_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
  15. );

database_inline 的 algorithm-expression 从 ds_${user_id % 2} 改为 ds_${user_id % 3 + 2}，t_order 的 DATANODES 从 ds_${0..1}.t_order_${0..1} 改为 ds_${2..4}.t_order_${0..1}，会触发迁移。

目前 ALTER SHARDING ALGORITHM 会即时生效、但是规则还没生效，可能会导致源端 insert 异常，所以建议优先修改为 AutoTableRule。

查询所有迁移任务

详情请参见RAL#弹性伸缩。

示例：

  1. show scaling list;

返回信息：

  1. mysql> show scaling list;
  2. +--------------------+-----------------------+----------------------+--------+---------------------+---------------------+
  3. | id                 | tables                | sharding_total_count | active | create_time         | stop_time           |
  4. +--------------------+-----------------------+----------------------+--------+---------------------+---------------------+
  5. | 659853312085983232 | t_order_item, t_order | 2                    | false  | 2021-10-26 20:21:31 | 2021-10-26 20:24:01 |
  6. | 660152090995195904 | t_order_item, t_order | 2                    | false  | 2021-10-27 16:08:43 | 2021-10-27 16:11:00 |
  7. +--------------------+-----------------------+----------------------+--------+---------------------+---------------------+
  8. 2 rows in set (0.04 sec)

查询迁移任务进度

示例：

  1. show scaling status {jobId};

返回信息：

  1. mysql> show scaling status 660152090995195904;
  2. +------+-------------+----------+-------------------------------+--------------------------+
  3. | item | data_source | status   | inventory_finished_percentage | incremental_idle_minutes |
  4. +------+-------------+----------+-------------------------------+--------------------------+
  5. | 0    | ds_1        | FINISHED | 100                           | 2834                     |
  6. | 1    | ds_0        | FINISHED | 100                           | 2834                     |
  7. +------+-------------+----------+-------------------------------+--------------------------+
  8. 2 rows in set (0.00 sec)

当前迁移任务已完成，新的分片规则已生效。如果迁移失败，新的分片规则不会生效。

status的取值：

取值描述
PREPARING准备中
RUNNING运行中
EXECUTE_INVENTORY_TASK全量迁移中
EXECUTE_INCREMENTAL_TASK增量迁移中
FINISHED已完成（整个流程完成了，新规则已生效）
PREPARING_FAILURE准备阶段失败
EXECUTE_INVENTORY_TASK_FAILURE全量迁移阶段失败
EXECUTE_INCREMENTAL_TASK_FAILURE增量迁移阶段失败

如果status出现失败的情况，可以查看proxy的日志查看错误堆栈分析问题。

预览新的分片规则是否生效

示例：

  1. preview select count(1) from t_order;

返回信息：

  1. mysql> preview select count(1) from t_order;
  2. +------------------+--------------------------------+
  3. | data_source_name | sql                            |
  4. +------------------+--------------------------------+
  5. | ds_2             | select count(1) from t_order_0 |
  6. | ds_2             | select count(1) from t_order_1 |
  7. | ds_3             | select count(1) from t_order_0 |
  8. | ds_3             | select count(1) from t_order_1 |
  9. | ds_4             | select count(1) from t_order_0 |
  10. | ds_4             | select count(1) from t_order_1 |
  11. +------------------+--------------------------------+
  12. 6 rows in set (0.01 sec)

其他DistSQL

详情请参见RAL#弹性伸缩。

DistSQL 手动模式接口

数据校验、切换配置等操作可以手动执行。详情请参见：RAL#弹性伸缩。

注意：目前还在开发中，功能还不完善。