Version Release History
Platform Requirements

YMatrix

Quick Start

Standard Cluster Deployment

Data Modeling

Connecting to The database

Data Writing

Data Migration

Data Query

Maintenance and Monitoring

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

scenario

mxaddmirrors

This document describes the mirror node (Mirror) addition tool mxaddmirrors.

1 Description

  • Functionality
    • The mxaddmirrors tool enables adding Mirrors to a YMatrix system that was initially deployed without Mirrors, and starts the online replication process between primary segments (Primary) and their corresponding Mirrors.
    • Once all Mirrors are synchronized with their respective Primaries, your YMatrix database system achieves full data redundancy.

Note!
During the mirror addition process, the database must be idle. Workloads and other queries should not be running.

2 Command-line Arguments

Below is a detailed description of the command-line arguments:

Subcommand Parameter Description Optional
config Creates a custom configuration file
--db-cluster-id Database cluster ID. Used to identify a unique database cluster Optional
--filename Saves the generated configuration to this file. If the file does not exist, it will be created automatically. Redirection can also be used Optional
init Converts collected information into a basic plan
--db-cluster-id Database cluster ID. Stored in the /etc/matrixdb5/cluster.conf file. Use the last ClusterID if only one cluster is deployed; otherwise, select the appropriate --db-cluster-id Required
--mirror-port-base Starting port from which to search for an available port for Mirror to listen on. Defaults to searching from 7000 Optional
plan Generates a deployment plan
--init-file Absolute path to the redirected output file from the init command Required
--custom-config Absolute path to the file generated by the config command Optional
setup Executes the deployment
--plan-file Absolute path to the redirected output file from the plan command Required

Note!
Only required parameters need to be specified if default behaviors are acceptable.

3 Usage Examples

The mxaddmirrors tool must be executed by a user with sudo privileges on the master host (except for mxadmin, use absolute path /opt/ymatrix/matrixdb5/bin/mxaddmirrors). If the mxaddmirrors init command is mistakenly run under a non-sudo user, the mxaddmirrors.init file will be generated under that user's context, readable but not writable by others. You must delete this file and re-run the command under a sudo-enabled user to regenerate it.

Two usage examples are provided: one using default behavior and another with custom configuration. Details are as follows:

Note!
Choose either 3.1 or 3.2. The default behavior uses YMatrix’s default Ring mirror distribution policy. With custom configuration, you can adjust to other desired mirror placement strategies. Regardless of choice, a complete mirror addition workflow must be followed.

3.1 Default Behavior

  1. Collect host information and partial deployment details of the existing database.

    $ mxaddmirrors init > /tmp/mxaddmirrors.init

  2. Generate a deployment plan based on the collected information—this outlines the exact deployment steps.

    $ mxaddmirrors plan --init-file /tmp/mxaddmirrors.init > /tmp/mxaddmirrors.plan

  3. Execute the deployment.

    $ mxaddmirrors setup --plan-file /tmp/mxaddmirrors.plan --mode cli

3.2 Custom Configuration

  1. Save the generated configuration to the config file. If the file does not exist, it will be created automatically.

    $ mxaddmirrors config --filename /tmp/config

  2. Edit the config file.

    $ edit config

  3. Collect host information and partial deployment details of the existing database.

    $ mxaddmirrors init > /tmp/mxaddmirrors.init

  4. Generate a deployment plan using the collected data and the custom configuration.

    $ mxaddmirrors plan --init-file /tmp/mxaddmirrors.init --custom-config /tmp/config > /tmp/mxaddmirrors.plan

  5. Execute the deployment.

    $ mxaddmirrors setup --plan-file /tmp/mxaddmirrors.plan --mode cli

The generated configuration file is in CSV format:

0||7000|
1||7000|
  • The file has four columns: content_id, hostname, port, and rootdir of datadir (used to create directories and files for various databases).
  • Empty values indicate no change; defaults will be used.
  • content_id must not be empty and must be unique. All modified options take effect immediately—what you see is what you get.

Note!
YMatrix 5 introduces a new database architecture. The mxaddmirrors tool is introduced for adding Mirrors and is not compatible with gpaddmirrors. Earlier versions used the gpaddmirrors utility.

See Also: mxinitstandby, mxdeletesystem.

← Previous
Glossary
Next →
mxbackup