Release History
Requirements

Introduction

Quick onboard

Deployment

Data Modeling

Connecting

Write data

Migration

Query

Operations and Maintenance

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

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 segment instances (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
--init-file Initializes the config template Required
--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 corresponding --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 mxadmin, use absolute path /opt/ymatrix/matrixdb6/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. See below:

Note!
Choose either 3.1 or 3.2. The default behavior follows YMatrix’s Ring mirroring distribution policy. Custom configuration allows you to adjust to other desired mirroring strategies. Regardless of choice, a complete mirror addition workflow must be performed.

3.1 Default Behavior

  1. Collect host and partial database deployment information.

    $ mxaddmirrors init > /tmp/mxaddmirrors.init

  2. Generate a deployment plan based on the collected information.

    $ 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. Collect host and partial database deployment information.

    $ mxaddmirrors init > /tmp/mxaddmirrors.init

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

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

    Note!
    Balanced and unbalanced clusters both generate reasonable configurations, but manual verification is still required.

  3. Edit the config file.

    $ edit config

  4. Generate a deployment plan using the collected data and 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 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!
For unbalanced deployments, refer to the relevant section in asymmetric cluster deployment for configuration rules.

Note!
Starting from YMatrix 5, a new database architecture has been introduced. The mxaddmirrors tool is now used to add Mirrors and is no longer compatible with gpaddmirrors. Previous versions may continue to use gpaddmirrors.

See Also: mxinitstandby, mxdeletesystem.

← Previous
Glossary
Next →
mxbackup