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

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