Start a YMatrix Cluster with NUMA Node Binding

This document describes how to bind YMatrix database instances to NUMA Nodes during cluster startup. After mxtool init numa-wrapper generates a NUMA Wrapper script and a NUMA mapping file, mxstart can use the Wrapper to bind each postmaster process to a NUMA Node so that each instance preferentially uses local CPU and memory resources.

Applicable version: YMatrix 6.8.2 or later.

1 Prerequisites

Before running the command, confirm that:

The cluster version is YMatrix 6.8.2 or later.
numactl is installed on every node.
The cluster is running normally.
The current user has permission to write the Wrapper script and NUMA mapping file on each node.

2 Feature Overview

Starting from YMatrix 6.8.2, mxstart can use a Wrapper to bind postmaster processes to NUMA Nodes during startup.

The mxtool init numa-wrapper command automatically generates and can deploy the following files based on the current cluster topology:

A NUMA Wrapper script, for example /home/mxadmin/scripts/mxstart_numa_wrapper.sh.
A NUMA mapping file, for example /home/mxadmin/scripts/mxstart_numa_map.conf.

The default memory policy is preferred:

Memory is allocated from the bound NUMA Node first.
If the local NUMA Node has insufficient memory, memory can be allocated from other NUMA Nodes.

To strictly restrict memory allocation to the specified NUMA Node, use --memory-policy=membind.

Note! mxtool init numa-wrapper only generates and deploys Wrapper files. It does not modify the running cluster or restart database instances automatically. NUMA Node binding takes effect the next time the cluster is started with mxstart.

3 Generate NUMA Wrapper Configuration

3.1 Preview the Generated Files

Run the following command to preview the Wrapper script and NUMA mapping file without changing remote files:

mxtool init numa-wrapper

The following output indicates Dry Run mode:

Mode: DRY RUN (no remote files will be changed)

Example output:

[mxadmin@sdw ~]$ mxtool init numa-wrapper

Mode: DRY RUN (no remote files will be changed)

host=sdw action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw-other action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred

host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
...

host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
...

Each mapping line has the following format:

<data directory> <NUMA Node ID>

For example:

/data/mxdata_20260622122230/primary/mxseg0 1

This means that the instance is bound to NUMA Node 1 when it starts.

3.2 Deploy the Wrapper Files

After confirming that the Dry Run output is correct, deploy the Wrapper script and NUMA mapping file to each node:

mxtool init numa-wrapper --apply

The following output indicates Apply mode:

Mode: APPLY (remote files will be deployed)

Example output:

[mxadmin@sdw ~]$ mxtool init numa-wrapper --apply

Mode: APPLY (remote files will be deployed)

host=sdw action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639

host=sdw-other action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw-other backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639

host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
...

host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
...

If a target file already exists, the command backs it up automatically. Backup paths are displayed after backups=.

3.3 Use the `membind` Memory Policy

To strictly restrict memory allocation to the bound NUMA Node, run:

mxtool init numa-wrapper     --memory-policy=membind     --apply

Note! The membind policy is stricter. If the bound NUMA Node does not have enough memory, the instance may fail to allocate memory. Before using it in production, confirm the memory capacity of each NUMA Node and the instance distribution.

4 Common Parameters

mxtool init numa-wrapper supports the following common parameters:

Parameter	Required	Default	Description
`--apply`	No	Disabled	Deploys the Wrapper script and NUMA mapping file to remote hosts. If omitted, only previews the generated files and does not modify remote files.
`--scope`	No	`all`	Specifies the instance scope used to generate mappings. Supported values are `all`, `master`, `standby`, `primary`, and `mirror`. Comma-separated combinations such as `primary,mirror` are also supported.
`--target-dir`	No	`/home/mxadmin/scripts`	Specifies the remote output directory.
`--script-name`	No	`mxstart_numa_wrapper.sh`	Specifies the Wrapper script file name.
`--map-name`	No	`mxstart_numa_map.conf`	Specifies the NUMA mapping file name.
`--memory-policy`	No	`preferred`	Specifies the NUMA memory policy. Supported values are `preferred` and `membind`.

5 Start the Cluster with the Wrapper

mxtool init numa-wrapper only generates or deploys the Wrapper script and NUMA mapping file. It does not modify running instances or restart the cluster automatically.

After deployment, enable NUMA Node binding the next time you start the cluster by passing --wrapper and --wrapper-args to mxstart:

mxstart -a     --wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh     --wrapper-args=/home/mxadmin/scripts/mxstart_numa_map.conf

After startup succeeds, the log shows the Wrapper parameters, for example:

[mxadmin@mxui ~]$ mxstart -a --wrapper=/home/mxadmin/numa_wrapper.sh --wrapper-args=/home/mxadmin/seg_numa_map.csv
2026-06-24:14:04:07.552 mxstart:mxadmin:mxui:2267293-[INFO]:-Starting MatrixDB cluster with: [no-prompt:true wrapper:/home/mxadmin/numa_wrapper.sh wrapper-args:/home/mxadmin/seg_numa_map.csv].
...
2026-06-24:14:04:14.381 mxstart:mxadmin:mxui:2267293-[INFO]:-MatrixDB cluster successfully started.

6 Verify NUMA Node Binding

After the cluster starts, use /proc information for the postmaster process to verify that binding has taken effect.

6.1 Check CPU Binding

Get the target instance's postmaster process ID and run:

cat /proc/<postmaster_pid>/status | grep Cpus_allowed_list

If CPU binding is effective, Cpus_allowed_list shows the CPU range allowed for the process.

6.2 Check Memory Policy

Run:

cat /proc/<postmaster_pid>/numa_maps

With the default preferred policy, you can see output similar to:

prefer:0

With the membind policy, you can see output similar to:

bind:0

The number is the NUMA Node ID bound to the current instance.

7 FAQ

7.1 What happens if the target script and configuration file already exist?

When --apply is used, if the target Wrapper script or NUMA mapping file already exists, the command backs up the old file before deploying the new one.

The backup file name contains a timestamp, for example:

host=sdw backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639
Tip: mxstart -a --wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh --wrapper-args=/home/mxadmin/scripts/mxstart_numa_map.conf

← Previous

Load Analysis

Statistics Query