Scale-Out with MariaDB Xpand 5.3 and 6


MariaDB Xpand is a scale-out distributed database. Scale-out means to add nodes to the cluster, which increases the compute, storage, and memory capacity of the cluster.


Information provided here applies to:

  • MariaDB Xpand 5.3

  • MariaDB Xpand 6.0

Use Cases

Scale-out can be used in certain situations to expand your Xpand cluster's capacity, such as:

  • To prepare for a peak event, such as Black Friday or Cyber Monday

  • To improve performance

  • To handle increased workload


  1. Check your Xpand license. Your MariaDB Xpand license is limited to a maximum number of nodes and a maximum number of CPU cores per node. If you need an expanded license, contact MariaDB.

  2. Provision the node and deploy Xpand on each host, using the same version and installation configuration.

    • If zones are in use, ensure that the target configuration has an equal number of node in each zone.

    • If you are using encrypted connections, ensure that certificates in keys are present in the same location with the correct permissions.

  3. Connect to an Xpand node that is already in the cluster.

    For additional information, see "Connect and Query".

  4. Add nodes to the cluster.

    Execute the ALTER CLUSTER ADD statement and specify the IP addresses of the new nodes to add them to the cluster:

    ALTER CLUSTER ADD "", "", "";

    Xpand will perform a group change to add new node(s).

    MariaDB recommends running this command during non-peak periods or during a scheduled maintenance window.

    There will be a short disruption of service while the node(s) are being added.

    You may also notice a slight degradation of performance while the Rebalancer moves data to the new node(s).

  5. When using zones, use the ALTER CLUSTER ZONE statement to add the new nodes to their respective zones.

    Clusters that are only partially configured for zones are not fault tolerant in the face of a zone loss.

  6. Verify successful node addition using one of the methods shown below.

    • Run this query from a SQL prompt. New node(s) are automatically assigned consecutive node number(s).

      SELECT * FROM system.nodeinfo ORDER BY instance_id;
    • You can also use the clx Command-Line Administration Tool.

      $ /opt/clustrix/bin/clx status

      You should see that all nodes appear OK on the display. If zones are in use, all nodes should have a non-zero zone assigned. If zones are not in use, all nodes will be assigned to zone 0.

      The data distribution might not be balanced among your nodes. Be patient. It will be, soon.

      If the node you are trying to add does not appear in the list above, see section below on Errors during Scale-Out.

  7. Monitor Rebalancer Activity

    Your new node(s) have been successfully added to your Xpand cluster but they do not yet contain data. The Rebalancer will now automatically work in the background to move data onto the new node(s).

    For additional information about how to monitor the Rebalancer, see "Manage the Rebalancer for MariaDB Xpand".

SQL Errors During Scale-Out

As part of adding nodes to your cluster, Xpand performs some checks to ensure the nodes have the same configuration. This section describes errors that can be encountered with ALTER CLUSTER ADD and how to resolve those issues.

The following are errors you may encounter at the SQL prompt:


ERROR 1 (HY000): [26633] Bad parameter.: Host "xxx" already in cluster

This error occurs if you attempt to add an node that is already part of the cluster.


ERROR 1 (HY000): [55300] Multiple nodes cannot be added when an existing addition is pending

This error occurs when a node addition is in a pending state due to:

  • An node is still in the process of being added

  • An node running a different version of Xpand was added to the cluster

  • An node with a different multi-port setting was added to the cluster

System Tables

The following system tables are relevant to the scale-out procedure.


The system.pending_invites system table contains a list of nodes with pending invitations:

SELECT * FROM system.pending_invites;

The cluster periodically attempts to send invitations to nodes in system.pending_invites. For each invitation that is sent, there will be entries in clustrix.log:

sending invitation response(no error) to ""


If the same node is in system.pending_invites and system.problem_nodes, you may want to remove the node from system.pending_invites before resolving the issue with system.problem_nodes. Doing this will prevent the node from being automatically added to the cluster once the problem is resolved, causing a premature group change. Instead, you may prefer to complete the node addition during off-peak hours.

Remove a pending node addition from PENDING_INVITES

DELETE FROM system.pending_invites;


The system.problem_nodes system table shows why a node could not be added:

SELECT * FROM system.problem_nodes;

Here is the list of reasons provided in system.problem_nodes and how to resolve those issues:



Software binaries differ

Make sure all nodes are running the same version of Xpand

Multiport settings mismatched

Check the multiport settings. For additional information, see "TCP Ports for MariaDB Xpand".