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.0. 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.0, see "Release Notes for MariaDB Xpand 6.1.0".

  • 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 with MariaDB Xpand".

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 Binary Tarball and Upgrade Script

MariaDB distributes MariaDB Xpand as a binary tarball. For upgrading MariaDB Xpand, MariaDB also distributes an upgrade script. When upgrading an Xpand cluster to a new version, both files are required.

  1. Login to the MariaDB Downloads page.

  2. Click the "Show All Files" link.

  3. Download the files:

    • Binary tarball: xpand-6.1.el7.tar.bz2

    • Upgrade script: xpand-xpdnode-6.1-upgrade.el7.sh

Step 2: Copy Binary Tarball and Upgrade Script to a Cluster Node

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

$ scp xpand-6.1.el7.tar.bz2 xpand@xpand-node1:/home/xpand/
$ scp xpand-xpdnode-6.1-upgrade.el7.sh xpand@xpand-node1:/home/xpand/

Step 3: Set File Ownership and Permissions

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

$ chown xpand /home/xpand/xpand-6.1.el7.tar.bz2
$ chmod 640 /home/xpand/xpand-6.1.el7.tar.bz2
$ chown xpand /home/xpand/xpand-xpdnode-6.1-upgrade.el7.sh
$ chmod 750 /home/xpand/xpand-xpdnode-6.1-upgrade.el7.sh

Step 4: Login as xpand OS User

On the one cluster node where the upgrade script 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 script 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 script 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 Script

On the one cluster node where the upgrade script will be executed, run the upgrade script:

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

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

This will upgrade every node in the cluster. 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          |
+--------------------+

Special Cases for Upgrades

Upgrades cannot be run on clusters in read-only mode