Upgrades for MariaDB Xpand

Overview

This page describes how to upgrade Xpand.

The examples on this page show how to upgrade to MariaDB Xpand 6.1.1. The examples can be adapted when upgrading to other versions of MariaDB Xpand.

If you experience any issues or have any questions, please contact MariaDB Support.

Prerequisites

  • All nodes must be online. The output of clx stat should indicate a cluster status of OK

  • Review the changes in the release notes for the new version. For information about the changes in MariaDB Xpand 6.1.1, see "Release Notes for MariaDB Xpand 6.1.1".

  • All upgrades should be run as the Xpand daemon user (xpand). For additional information, see "Operating System User Accounts for MariaDB Xpand".

  • If password authentication is not enabled, then passwordless SSH authentication must be configured for the Xpand daemon user (xpand). To verify this, confirm that the clx command returns successfully with no passwords requested:

    /opt/clustrix/bin/clx cmd date

    For additional information, see "SSH Configuration".

  • Ensure that the clocks are synchronized between nodes. For additional information, see "Chronyd for Clock Synchronization with MariaDB Xpand".

  • MariaDB recommends performing a backup before all upgrades. For information about how to perform a backup, see "Backup and Restore".

Upgrade Procedure

The Xpand upgrade packages will upgrade the database and XpandGUI. The upgrade should be run from a single node and will upgrade all nodes in the cluster.

Performing an upgrade will incur a short period of downtime.

Note

Xpand does not support downgrades.

Step 1: Download Upgrade Package

For upgrading MariaDB Xpand, MariaDB distributes a self-extracting upgrade package. The upgrade package is a bash script that is packed with the compressed binaries. When the upgrade package is executed, the script self-extracts the binaries and copies them to each node.

  1. Login to the MariaDB Downloads page.

  2. Click the "Show All Files" link.

  3. Download the upgrade package: xpand-xpdnode-6.1.1-upgrade.el7.sh

Step 2: Copy Upgrade Package to a Cluster Node

Copy the upgrade package for the new Xpand version to the Xpand daemon user's (xpand) home directory on the one cluster node where the upgrade package will be executed:

$ scp xpand-xpdnode-6.1.1-upgrade.el7.sh xpand@xpand-node1:/home/xpand/

Step 3: Set File Ownership and Permissions

On the one cluster node where the upgrade package will be executed, set the owner and file system permissions for the upgrade package:

$ chown xpand /home/xpand/xpand-xpdnode-6.1.1-upgrade.el7.sh
$ chmod 750 /home/xpand/xpand-xpdnode-6.1.1-upgrade.el7.sh

Step 4: Login as xpand OS User

On the one cluster node where the upgrade package will be executed, login to a terminal owned by the Xpand daemon user (xpand):

  • If the xpand user has a password defined, then password authentication can be used, so you can switch to the user by directly executing su and typing the user's password:

    $ su - xpand
Password:

  • If the xpand user does not have a password defined, but your current user has permissions to use sudo, then you can switch to the user using sudo:

    $ sudo su xpand

    Because of an issue with the mysql client included with CentOS 7 and RHEL 7, the command sudo -u xpand COMMAND does not use the correct user for database logins, which causes the upgrade procedure to fail with an error. To upgrade successfully you must use sudo to switch to a terminal owned by that user, as shown in the example above.

For additional information about this user account, see "Operating System User Accounts for MariaDB Xpand".

Step 5: Specify SSH Port (Optional)

On the one cluster node where the upgrade package will be executed, if you are using a non-default SSH port, use the CLX_SSH_PORT environment variable to set the SSH port:

$ export CLX_SSH_PORT=1234

Step 6: Run Upgrade Package

On the one cluster node where the upgrade package will be executed, run the upgrade package and provide the install argument:

$ ./xpand-xpdnode-6.1.1-upgrade.el7.sh install

If passwordless SSH access has not been configured for the node, the upgrade procedure will prompt for a password.

This will upgrade every node in the cluster. The new Xpand binaries are extracted from the upgrade package and copied to each node. While the upgrade is in progress, there is a brief period during which the database is unavailable.

Step 7: Check Version

Once the database portion of the upgrade is complete, the cluster is online. The XpandGUI portion of the upgrade will continue but the database is available.

On any cluster node, verify that the cluster has been upgraded successfully by examining the value of the clustrix_version system variable:

SELECT @@clustrix_version;

+--------------------+
| @@clustrix_version |
+--------------------+
| Xpand-6.1.1          |
+--------------------+

Special Cases for Upgrades

Upgrades cannot be run on clusters in read-only mode