mxmoveseg

This document describes the mirror segment instance (Mirror) migration tool mxmoveseg.

Note!
mxmoveseg is used only to migrate segment instances where the gp_segment_configuration table's role (current role) is m (mirror). It does not consider the preferred_role (preferred role) column.

1 Description

Functionality
- The mxmoveseg tool supports migrating any database segment instance currently serving as a Mirror to another server.
Use Cases
- The current cluster is operational but suffers from unbalanced load, affecting performance and stability. Mirrors can be relocated across machines to rebalance the system.
- A server hosting a Mirror has gone offline. The Mirror must be migrated to a healthy new server to maintain cluster resilience.
Limitations
- The mxmoveseg tool does not support migration of the Standby Master.

Note!
Before using this tool, you must manually verify the health status of all servers in the cluster. If any servers are unhealthy, identify them explicitly to ensure that mxmoveseg collects information only from healthy hosts.

2 Command-Line Options

The following table lists the available command-line options:

Option	Description
`--config`	Creates a configuration file for the Mirror segments to be migrated
`--plan`	Generates a migration plan based on the configuration
`--setup`	Executes the migration plan
`-h / --help`	Displays help information

3 Examples

3.1 Migrate Existing Segment to a New Server

Note!
The new server must have the same version of YMatrix RPM/DEB package installed as per YMatrix deployment documentation, but do not initialize a new cluster via the graphical interface.

Note!
The new server may host a YMatrix cluster with a different major version (e.g., YMatrix 4.8 on the old server and YMatrix 5.1 on the new server).

Collect information about the existing database cluster. Use more /etc/matrixdb5/cluster.conf to view the cluster ID.

[<username>@<master_hostname> ~]$ sudo /opt/ymatrix/matrixdb5/bin/mxctl expand init --cluster-id <clusterid> --unrestrict > /tmp/init

Add the new server.

[<username>@<master_hostname> ~]$ cat /tmp/init | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand add --unrestrict --host <newhost> > /tmp/initadd

Check network connectivity between the discovered servers.

[<username>@<master_hostname> ~]$ cat /tmp/initadd | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand netcheck > /tmp/netcheck

Switch to the mxadmin user.

[<username>@<master_hostname> ~]$ sudo su - mxadmin

Create a migration configuration file and edit it according to the instructions within to specify the instances to migrate.

$ mxmoveseg config --db-cluster-id <clusterid> --filename /tmp/migrate.cfg

# After creating the configuration file, manually edit the dbid (obtained by running SELECT * FROM gp_segment_configuration; after connecting to the database), hostname, etc., of the segments to be migrated. SPEC: If port conflicts exist between the new and old servers, assign new ports in the configuration file.
$ vim /tmp/migrate.cfg

Generate the migration plan.

$ mxmoveseg plan --init-file /tmp/netcheck --config-file /tmp/migrate.cfg > /tmp/plan

Execute the migration.

$ mxmoveseg setup --plan-file /tmp/plan --mode cli

After successful migration, verify the status of the migrated Mirror using the GUI: "Cluster Management" → "Cluster Overview" → "Instance View", or use the SELECT * FROM gp_segment_configuration SQL statement.

Warning!
If the source server was offline during migration, do not restart the old server after migration completes. Restarting will bring up the old management processes, causing service discovery conflicts with the new processes and potentially destabilizing the cluster.

3.2 Migrate Existing Segment to an Old Server

Collect information about the existing database cluster. Use more /etc/matrixdb5/cluster.conf to view the cluster ID.

[<username>@<master_hostname> ~]$ sudo /opt/ymatrix/matrixdb5/bin/mxctl expand init --cluster-id <clusterid> --unrestrict > /tmp/init

Check network connectivity between the discovered servers.

[<username>@<master_hostname> ~]$ cat /tmp/init | sudo /opt/ymatrix/matrixdb5/bin/mxctl expand netcheck > /tmp/netcheck

Switch to the mxadmin user.

[<username>@<master_hostname> ~]$ sudo su - mxadmin

Create a migration configuration file and edit it according to the internal instructions to specify the Mirror instances to migrate.

$ mxmoveseg config --db-cluster-id <clusterid> --filename /tmp/migrate.cfg

# After creating the configuration file, manually edit the dbid (obtained by running SELECT * FROM gp_segment_configuration; after connecting to the database), hostname, etc., of the Mirror segments to be migrated. SPEC: If port conflicts exist between the target and original servers, assign new ports in the configuration file.
$ vim /tmp/migrate.cfg

Generate the migration plan.

$ mxmoveseg plan --init-file /tmp/netcheck --config-file /tmp/migrate.cfg > /tmp/plan

Execute the migration.

$ mxmoveseg setup --plan-file /tmp/plan --mode cli

← Previous

mxinitstandby

mxpacklogs