YMatrix 文档

版本发布历史
系统需求

关于 YMatrix

快速上手

标准集群部署

数据建模

连接到数据库

数据写入

数据迁移

数据查询

运维监控

性能调优

故障诊断

参考指南

SQL 参考

常见问题（FAQ）

场景应用

命令行在线扩容

如果你习惯使用代码来完成扩容操作，我们也提供相应的扩容工具以及 SQL 语句来实现灵活、平滑的扩容功能。一般而言，集群扩容主要有两个步骤：增加新节点，数据重分布。
增加新节点是很迅捷的操作，在 YMatrix 中，不用停机便可完成。数据重分布则相对复杂，如果不做特定操作，任何新创建的表会默认被分布在所有的节点上，正在被重新分布的表或者分区会被锁定并且不可读写，造成阻塞。同时，在某些业务场景下，用户并不需要对某些表的数据进行重分布，只对部分旧表或新建表设置新的分布方式即可满足需求。

在 YMatrix 中，我们提供了 平滑扩容 功能来实现这一需求，通过创建 SEGMENT_SET 对象即可自主定义数据节点集合，并指定表的数据分布在该对象上（即仅将数据分布在某个特定的数据节点集合中）。

YMatrix 还支持以下功能：并行执行表数据重分布、连接未重分布表与已重分布表等。

1 系统规划

在进行正式扩容操作前，必不可少的即是对集群进行系统的扩容规划，我们列出以下任务清单，它包含了完整的扩容流程。

序号 任务内容
准备工作
1 为新主机安装同版本的 YMatrix 软件
2 查看集群状态
3 查看软件版本
4 增加主机名到系统文件
扩容
5 执行扩容
扩容后检查
6 查看新集群
7 查看数据分布

扩容完毕，在进行数据重分布前，你需要预先规划数据重分布的方式。
例如，按照时间分区的时序数据通常具有明显的冷热特征（冷热特征是一个相对概念，主要与数据被查询的频率相关，频率高即相对具有热数据特征）。随着时间推移，热数据逐渐转冷，对其查询需求也随之降低，不需要分配更多的资源来完成查询动作，因此对此进行重分布反而赘余。这时，只对即将入库的新数据提前设定分布（在建表时完成）是更佳选择，利用 YMatrix 中平滑扩容特性可以实现这个规划。
反之，如果数据库表通常为非分区表，或分区表的各个分区数据访问较均匀，都有新增数据，那么就比较适合全部数据重分布。

如果你想要对全部数据进行重分布，请参考表格 1 步骤规划。

表格 1

序号 任务内容
数据重分布
1 执行全部数据重分布命令
重分布后任务
2 查看当前重分布状态
3 查看数据分布

如果你想要进行 平滑扩容，请参考下方表格 2。
此表格中我们给出了 4 种不同的方式来实现平滑扩容，任选其一即可。

表格 2

方式 平滑扩容
(1) 创建所需数据节点集合（CREATE SEGMENT_SET），新建表或分区时指定该数据节点集合
(2) 建表时直接指定扩容前已存在的数据节点集合
(3) 新建表不指定数据节点集合，按照 mx_default_segment_set 参数指定的数据节点集合分布，默认值下为全局分布
(4) 除了新数据，部分旧数据也需要重新规划分布，这时需要将新数据与旧数据分开处理，旧数据重分布使用 ALTER TABLE SET SEGMENT_SET 语句，新数据则运用以上（1）、（2）、（3）方法，任选其一

2 准备工作

具体操作说明示例如下。假设你目前有三台服务器：mdw，sdw1，sdw2。预计新增两台机器：sdw3，sdw4。 示例集群中有以下测试表 test，内含 100 条测试数据。

=# CREATE EXTENSION matrixts;
=# CREATE TABLE test (a int,b int) USING MARS3 DISTRIBUTED BY (a) ORDER BY (a);
=# INSERT INTO test SELECT i,i+10 FROM generate_series(1, 100) AS i;

2.1 为新主机安装同版本的 YMatrix 软件

首先，你需要为将要添加到集群中的两台新主机安装和已有主机上版本相同的 YMatrix 软件。具体部署步骤请见在线集群部署 1-3 部分。

2.2 查看集群状态

其次，利用 gp_segment_configuration 表查看一下集群状态，确保所有节点实例都处于健康状态。

=# SELECT * FROM gp_segment_configuration ORDER BY 1 ASC;

dbid | content | role | preferred_role | mode | status | port | hostname | address |                datadir                
------+---------+------+----------------+------+--------+------+----------+---------+---------------------------------------
    1 |      -1 | p    | p              | n    | u      | 5432 | mdw      | mdw     | /data/mxdata/master/mxseg-1
    2 |       0 | p    | p              | n    | u      | 6000 | sdw1     | sdw1    | /data/mxdata/primary/mxseg0
    3 |       1 | p    | p              | n    | u      | 6001 | sdw1     | sdw1    | /data/mxdata/primary/mxseg1
    4 |       2 | p    | p              | n    | u      | 6000 | sdw2     | sdw2    | /data/mxdata/primary/mxseg2
    5 |       3 | p    | p              | n    | u      | 6001 | sdw2     | sdw2    | /data/mxdata/primary/mxseg3
(5 rows)

2.3 查看软件版本

再利用 version() 函数再次确认 YMatrix 版本是否与已有版本相同。

=# SELECT version();
                                                                                                                                    version

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------
 PostgreSQL 12 (MatrixDB 5.0.0-enterprise) (Greenplum Database 7.0.0+dev.17976.g99b559cbeb build commit:99b559cbebca8c47dfb2de58fb10b6e2a04f91a0) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 7.3.1 20180303 (Red Hat 7.3.1-5), 64-bit
compiled on Aug 16 2022 16:18:55
(1 row)

2.4 增加主机名到系统文件

确认好集群状态与软件版本后，你需要在所有节点上使用 root 权限配置好 /etc/hosts 系统文件，添加新增的主机名。过程中请保持网络通畅。

[<普通用户名>@mdw ~]$ sudo vi /etc/hosts
127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6
192.168.247.128 mdw
192.168.247.129 sdw1
192.168.247.130 sdw2
192.168.247.131 sdw3
192.168.247.132 sdw4

3 执行扩容

注意！
以下所有扩容操作都在 Master 上完成。

3.1 采集现有集群信息

$ sudo /opt/ymatrix/matrixdb5/bin/mxctl expand init > /tmp/init_output

现有集群信息会以结构化信息的形式输出到 /tmp/init_output 目录下。

3.2 添加新主机

$ cat /tmp/init_output | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand add --host newhost1 > /tmp/add.1
$ cat /tmp/add.1 | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand add --host newhost2 > /tmp/add.2
...

添加加几台主机就需要执行几次，每次的输出作为下一次的输入。

3.3 进行网络互通测试

$ cat /tmp/add.3 | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand netcheck > /tmp/ncheck

当退出码 exitcode （echo $?）大于 0，意味着未通过测试。

3.4 生成扩容计划

$ cat /tmp/ncheck | sudo /opt/ymatrix/matrixdb5/bin/mxbox deployer expand > /tmp/exandplan

目录创建路径，Segment 数量，Mirror 的分布策略等全部信息都在生成的 /tmp/exandplan 下。高级用户可以直接修改这个文件。

3.5 执行扩容计划

$ cat /tmp/exandplan | sudo /opt/ymatrix/matrixdb5/bin/mxbox deployer exec

恭喜，执行扩容完成。

4 扩容后检查任务

4.1 查看新集群

=# SELECT * FROM gp_segment_configuration ORDER BY 1;
 dbid | content | role | preferred_role | mode | status | port | hostname | address |                datadir                
------+---------+------+----------------+------+--------+------+----------+---------+---------------------------------------
    1 |      -1 | p    | p              | n    | u      | 5432 | mdw      | mdw     | /mxdata_20220331173619/master/mxseg-1
    2 |       0 | p    | p              | n    | u      | 6000 | sdw1     | sdw1    | /mxdata_20220331173619/primary/mxseg0
    3 |       1 | p    | p              | n    | u      | 6001 | sdw1     | sdw1    | /mxdata_20220331173619/primary/mxseg1
    4 |       2 | p    | p              | n    | u      | 6000 | sdw2     | sdw2    | /mxdata_20220331173619/primary/mxseg2
    5 |       3 | p    | p              | n    | u      | 6001 | sdw2     | sdw2    | /mxdata_20220331173619/primary/mxseg3
    6 |       4 | p    | p              | n    | u      | 6000 | sdw3     | sdw3    | /mxdata_20220331173619/primary/mxseg4
    7 |       5 | p    | p              | n    | u      | 6001 | sdw3     | sdw3    | /mxdata_20220331173619/primary/mxseg5
    8 |       6 | p    | p              | n    | u      | 6000 | sdw4     | sdw4    | /mxdata_20220331173619/primary/mxseg6
    9 |       7 | p    | p              | n    | u      | 6001 | sdw4     | sdw4    | /mxdata_20220331173619/primary/mxseg7
(9 rows)

4.2 查看数据分布

你通过以下 SQL 语句，看到了原有的数据表的数据在之前的数据节点上的分布状态。是时候规划数据如何分布了。

=#  SELECT gp_segment_id,count(*) FROM public.test GROUP BY gp_segment_id;

5 规划数据分布

在进行数据分布前，你已经知道集群重分布是集群扩容后的一项重要且耗时的任务。
集群扩容前，业务数据都分布在旧节点上，扩容过程新增了可用节点，此时将旧节点的数据均匀分布到当前集群所有节点上的过程称为数据“重分布”。
符合场景需求时，数据重分布将大大提升业务响应速率；但不符合场景需求时，数据重分布反而会浪费掉大量资源与时间。因此，你认为非常有必要思考、规划一下如何进行数据分布。

有以下两种思路，你根据时序场景的特点选择了其中一种实现。

5.1 重分布全部数据

新增加的数据节点上并没有数据，你使用以下方法将全部旧数据重新分布到新集群中。可以选择预约执行时间，也可立即执行。

注意！
建议选择业务低峰期进行数据重新分布动作。

立即执行：

$ sudo /opt/ymatrix/matrixdb5/bin/mxctl expand redistribute

预约执行：

$ sudo /opt/ymatrix/matrixdb5/bin/mxctl expand redistribute --schedule "2022-07-20 22:00:00"

预约后，在预约的时间到达前，可以随时重新运行上面命令改变预约时间，也可以去掉 --schedule 参数立即触发重分布。

重分布过程中及完成后，你可以用扩容系统目录中的系统表来查看重分布状态。并利用以下语句再次查看集群分布状态。

=# SELECT gp_segment_id,count(*) FROM public.test GROUP BY gp_segment_id;

5.2 重分布部分数据

即 YMatrix 称之为的 平滑扩容。正如前文规划的思路，你准备在 4 种可用方法中根据实际情况选择其一使用。

方式 平滑扩容
(1) 创建所需数据节点集合（CREATE SEGMENT_SET），新建表或分区时指定该数据节点集合
(2) 建表时直接指定扩容前已存在的数据节点集合
(3) 新建表不指定数据节点集合，按照 mx_default_segment_set 参数指定的数据节点集合分布，默认值下为全局分布
(4) 除了新数据，部分旧数据也需要重新规划分布，这时需要将新数据与旧数据分开处理，旧数据重分布使用 ALTER TABLE SET SEGMENT_SET 语句，新数据则运用以上（1）、（2）、（3）方法，任选其一

5.2.1 创建新数据节点集合

在 YMatrix 中使用 SQL 语句 CREATE SEGMENT_SET 创建新数据节点集合。

=# CREATE SEGMENT_SET name SEGMENTS (content_id, ...);

5.2.2 指定已存在的数据节点集合

在 YMatrix 中使用 SQL 语句指定已创建的数据节点集合。例如：

=# CREATE TABLE t1(a int, b int) USING MARS3 DISTRIBUTED BY(a) SEGMENT_SET ss1 ORDER BY (a);
=# CREATE TABLE t1(a int, b int) USING MARS3 DISTRIBUTED REPLICATED SEGMENT_SET ss1 ORDER BY (a);
=# CREATE TABLE t1(a int, b int) USING MARS3 DISTRIBUTED RANDOMLY SEGMENT_SET ss1 ORDER BY (a);

更多用法相关信息请见 CREATE SEGMENT_SET。

5.2.3 使用默认值

在 YMatrix 中创建新表，如果不指定数据节点集合，数据会分布在 mx_default_segment_set 指定的数据节点集合上，默认值下会分布在集群所有节点上。可以通过 SET 语句修改默认使用的数据节点集合，例如：

=# SET mx_default_segment_set TO 'ss1';

5.2.4 重分布部分旧数据

除了新数据，部分旧数据也需要重新规划分布，这时需要将新数据与旧数据分开处理，旧数据重分布使用 ALTER TABLE SET SEGMENT_SET 语句，新数据则运用以上 5.2.1、5.2.2、5.2.3 中说明的方法，任选其一。示例中，扩容前已存在的表 t 被重新分布到数据节点集合 ss1 上。

=# ALTER TABLE t SET SEGMENT_SET ss1;

也可以将表 t 重分布到扩容后的所有节点。

=# ALTER TABLE t SET SEGMENT_SET all_segments;

#or

=# ALTER TABLE t EXPAND TABLE;

至此，一次高效的由命令行实现的集群扩容已完成！