Release History
Help

YMatrix

Quick Start

Deployment

Data Usage

Manage Clusters

Security

Best Practice

Technical Principles

Advanced Features

Guide

SQL Reference

FAQ

mxchangeport

This document describes the master/standby port modification utility mxchangeport.

1 Description

Introduce mxchangeport to safely change MatrixDB ports for master and optionally standby. The workflow performs prechecks, updates catalog and configs, syncs the spec, and completes with a controlled recovery. During revert, a revert-only step restarts replication services to promptly restore connectivity.

2 Steps

  • Precheck: verify target ports are free on affected hosts.
  • Catalog: UpdateSegmentPort on master (and standby when enabled).
  • ConfigModify:
    • postgresql.conf: set port per targeted instance.
    • defaults.conf: update MasterPortBase/StandbyPortBase.
    • cluster.conf: set PGPort for the host.
    • recover_db_cluster.json: refresh DBID→port mappings.
    • standby postgresql.auto.conf: patch primary_conninfo port.
    • update_bash: refresh mxadmin environment (PGPORT).
  • SpecSync: prepend RestartServicesOnRevert (forward no-op; on revert, restart replication targets) before SaveSpecToEtcd.
  • Recovery: restart services across hosts, then mxstart and mxrecover.
  • CollectorReconfigure: update service confs to target port; update matrixmgr DB port; restart mxui/cylinder; probe in revert-test.

3 Usage

  • Master only (change master port)
    mxchangeport run --new-port 6432
  • Master + standby (same port)
    mxchangeport run --new-port 6432 --with-standby
  • Master + standby (different port for standby)
    mxchangeport run --new-port 6432 --with-standby --standby-port 7432
  • Revert test (inject a failure to validate reverts)
    mxchangeport run --new-port 6432 --revert-test

4 Debug

  • Generate init JSON via redirection
    mxchangeport run --new-port 6432 --with-standby --standby-port 7432 --gen-init > init.json
  • Generate plan from an init file, then execute a specified plan Generate plan: 
    mxchangeport run --init-file init.json --gen-plan > plan.json

    Execute plan:

    mxchangeport run --plan-file plan.json

Note!
With --with-standby and no --standby-port, standby uses the same new port.

← Previous
mxbench
Next →
mxdeletesystem