Upgrade Multi-Node MariaDB Enterprise ColumnStore from 5 to 6

These instructions detail the upgrade from MariaDB Enterprise ColumnStore 5 to MariaDB Enterprise ColumnStore 6 in a Multi-Node topology on a range of supported Operating Systems.

Set Replicas to Maintenance Mode

This action is performed for each replica server on the MaxScale node.

Prior to upgrading, the replica servers must be set to maintenance mode in MaxScale. The replicas can be set to maintenance mode in MaxScale using MaxScale's REST API. If you are using MaxCtrl, the replicas can be set to maintenance mode using the set server command:

$ maxctrl set server \
   mcs2 \
   maintenance
  • As the first argument, provide the name for the server

  • As the second argument, provide maintenance as the state

Confirm Maintenance Mode is Set for Replicas

This action is performed on the MaxScale node.

Confirm that the replicas are set to maintenance mode in MaxScale using MaxScale's REST API. If you are using MaxCtrl, the state of the replicas can be viewed using the list servers command:

$ maxctrl list servers
┌────────┬───────────────┬──────┬─────────────┬──────────────────────┬────────┐
│ Server │ Address       │ Port │ Connections │ State                │ GTID   │
├────────┼───────────────┼──────┼─────────────┼──────────────────────┼────────┤
│ mcs3   │ 192.0.2.3     │ 3306 │ 0           │ Maintenance, Running │ 0-1-17 │
├────────┼───────────────┼──────┼─────────────┼──────────────────────┼────────┤
│ mcs2   │ 192.0.2.2     │ 3306 │ 0           │ Maintenance, Running │ 0-1-17 │
├────────┼───────────────┼──────┼─────────────┼──────────────────────┼────────┤
│ mcs1   │ 192.0.2.1     │ 3306 │ 0           │ Master, Running      │ 0-1-17 │
└────────┴───────────────┴──────┴─────────────┴──────────────────────┴────────┘

If the node is properly in maintenance mode, then the State column will show Maintenance as one of the states.

Disable GTID Strict Mode

This action is performed on each replica server.

The gtid_strict_mode system variable must be disabled for this upgrade procedure. If the gtid_strict_mode system variable is enabled in any configuration files, disable it temporarily until the upgrade procedure is complete.

You can check if the gtid_strict_mode system variable is set in a configuration file by executing my_print_defaults command with the mysqld option:

$ my_print_defaults --mysqld \
   | grep "gtid[-_]strict[-_]mode"
--gtid_strict_mode=1

If the gtid_strict_mode system variable is set, you can temporarily disable it by adding # in front of it in the configuration file, so that it will be treated as a comment and ignored:

[mariadb]
...
# temporarily commented out for upgrade
# gtid_strict_mode=1

Shutdown ColumnStore

This action is performed on the primary server.

Prior to upgrading, MariaDB Enterprise ColumnStore must be shutdown. MariaDB Enterprise ColumnStore can be shutdown using CMAPI with the shutdown endpoint.

If you are calling CMAPI on the primary server from a local shell, the mcsShutdown alias can be used to call the shutdown endpoint:

$ mcsShutdown

If you are calling CMAPI on the primary server from a remote node, you can call the shutdown endpoint using curl or another REST client:

$ curl -k -s -X PUT https://mcs1:8640/cmapi/0.4.0/cluster/shutdown \
   --header 'Content-Type:application/json' \
   --header 'x-api-key:CMAPI_API_KEY' \
   --data '{"timeout":60}' \
   | jq

Stop Services

This action is performed on each ColumnStore node.

Prior to upgrading, several services must be stopped on each ColumnStore node:

  1. Stop the CMAPI service:

    $ sudo systemctl stop mariadb-columnstore-cmapi
    
  2. Stop the MariaDB Enterprise ColumnStore service:

    $ sudo systemctl stop mariadb-columnstore
    
  3. Stop the MariaDB Enterprise Server service:

    $ sudo systemctl stop mariadb
    

Uninstall the Old Version

When upgrading to a new major release of MariaDB Enterprise ColumnStore, it is necessary to remove the existing installation of MariaDB Enterprise Server and MariaDB Enterprise ColumnStore, before installing the new version of MariaDB Enterprise Server and MariaDB Enterprise ColumnStore. Otherwise, the package manager will refuse to install the new version.

Stop the MariaDB Server Process

Before the old version can be uninstalled, we first need to stop the current MariaDB Server process.

  1. Stop the server process:

    For distributions that use systemd (most supported OSes), you can manage the Server process using the systemctl command:

    $ sudo systemctl stop mariadb
    
  2. Stop the server process using the systemctl command:

    $ sudo systemctl stop mariadb
    

Uninstall via YUM (RHEL/CentOS)

  1. Uninstall all of the MariaDB Enterprise Server and Enterprise ColumnStore packages. Note that a wildcard character is used to ensure that the packages are all uninstalled:

    $ sudo yum remove "MariaDB-*"
    

    Be sure to check that this wildcard does not unintentionally refer to any of your custom applications:

  2. Uninstall the Galera package as well.

    The name of the package depends on the specific version of MariaDB Enterprise Server.

    When upgrading from MariaDB Enterprise Server 10.4 or later, the package is called galera-enterprise-4:

    $ sudo yum remove galera-enterprise-4
    

    When upgrading from MariaDB Enterprise Server 10.3 or earlier, the package is called galera:

    $ sudo yum remove galera
    
  3. Before proceeding, verify that all MariaDB Enterprise Server and MariaDB Enterprise ColumnStore packages are uninstalled. The following command should not return any results:

    $ rpm --query --all | grep -i -E "mariadb|galera"
    

Uninstall via APT (Debian/Ubuntu)

  1. Uninstall all of the MariaDB Enterprise Server and MariaDB Enterprise ColumnStore packages. Note that a wildcard character is used to ensure that the packages are all uninstalled:

    $ sudo apt-get remove "mariadb-*"
    

    Be sure to check that this wildcard does not unintentionally refer to any of your custom applications.

  2. Uninstall the Galera package as well.

    The name of the package depends on the specific version of MariaDB Enterprise Server.

    When upgrading from MariaDB Enterprise Server 10.4 or later, the package is called galera-enterprise-4:

    $ sudo apt remove galera-enterprise-4
    

    When upgrading from MariaDB Enterprise Server 10.3 or earlier, the package is called galera-3:

    $ sudo apt remove galera-3
    
  3. Before proceeding, verify that all MariaDB Enterprise Server and MariaDB Enterprise ColumnStore packages are uninstalled. The following command should not return any results:

    $ apt list --installed | grep -i -E "mariadb|galera"
    

Uninstall via ZYpp (SLES)

  1. Uninstall all of the MariaDB Enterprise Server and MariaDB Enterprise ColumnStore packages. Note that a wildcard character is used to ensure that the packages are all uninstalled:

    $ sudo zypper remove "MariaDB-*"
    

    Be sure to check that this wildcard does not unintentionally refer to any of your custom applications.

  2. Uninstall the Galera package as well.

    The name of the package depends on the specific version of MariaDB Enterprise Server.

    When upgrading from MariaDB Enterprise Server 10.4 or later, the package is called galera-enterprise-4:

    $ sudo zypper remove galera-enterprise-4
    

    When upgrading from MariaDB Enterprise Server 10.3 or earlier, the package is called galera:

    $ sudo zypper remove galera
    
  3. Before proceeding, verify that all MariaDB Enterprise Server and MariaDB Enterprise ColumnStore packages are uninstalled. The following command should not return any results:

    $ rpm --query --all | grep -i -E "mariadb|galera"
    

Install the New Version

MariaDB Corporation provides package repositories for YUM (RHEL/CentOS), APT (Debian/Ubuntu), and ZYpp (SLES).

Install via YUM (RHEL/CentOS)

  1. Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the YUM package repository.

    To configure YUM package repositories:

    $ sudo yum install wget
    
    $ wget <%mariadb_es_repo_setup_url%>
    
    $ echo "<%mariadb_es_repo_setup_checksum%>  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-server-version="<%es_ver%>"
    
  3. Install MariaDB Enterprise ColumnStore and package dependencies:

    $ sudo yum install MariaDB-server \
          MariaDB-backup \
          MariaDB-shared \
          MariaDB-client \
          MariaDB-columnstore-engine \
          mariadb-columnstore-cmapi
    

Install via APT (Debian/Ubuntu)

  1. Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the APT package repository.

    To configure APT package repositories:

    $ sudo apt install wget
    
    $ wget <%mariadb_es_repo_setup_url%>
    
    $ echo "<%mariadb_es_repo_setup_checksum%>  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-server-version="<%es_ver%>"
    
    $ sudo apt update
    
  3. Install MariaDB Enterprise Server and package dependencies:

    $ sudo apt install mariadb-server \
          mariadb-backup \
          libmariadb3 \
          mariadb-client \
          mariadb-plugin-columnstore \
          mariadb-columnstore-cmapi
    

Install via ZYpp (SLES)

  1. Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the ZYpp package repository.

    To configure ZYpp package repositories:

    $ sudo zypper install wget
    
    $ wget <%mariadb_es_repo_setup_url%>
    
    $ echo "<%mariadb_es_repo_setup_checksum%>  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-server-version="<%es_ver%>"
    
  3. Install MariaDB Enterprise ColumnStore and package dependencies:

    $ sudo zypper install MariaDB-server \
          MariaDB-backup \
          MariaDB-shared \
          MariaDB-client \
          MariaDB-columnstore-engine \
          mariadb-columnstore-cmapi
    

Disable ColumnStore Service

This action is performed on each ColumnStore node.

After upgrading, the MariaDB Enterprise ColumnStore service should be stopped and disabled, since it will be controlled by CMAPI:

$ sudo systemctl stop mariadb-columnstore
$ sudo systemctl disable mariadb-columnstore

Start Services

This action is performed on each ColumnStore node.

After upgrading, the CMAPI service and the MariaDB Enterprise Server service must be started on each ColumnStore node:

  1. Start the CMAPI service:

    $ sudo systemctl start mariadb-columnstore-cmapi
    
  2. Start the MariaDB Enterprise Server service:

    $ sudo systemctl start mariadb
    

Write Binary Log

On the primary server, run mariadb-upgrade to upgrade the data directory with binary logging enabled to update the system tables:

$ mariadb-upgrade --write-binlog

Start ColumnStore

This action is performed on the primary server.

After upgrading, MariaDB Enterprise ColumnStore must be started. MariaDB Enterprise ColumnStore can be started using CMAPI with the start endpoint.

If you are calling CMAPI on the primary server from a local shell, the mcsStart alias can be used to call the start endpoint:

$ mcsStart

If you are calling CMAPI on the primary server from a remote node, you can call the start endpoint using curl or another REST client:

$ curl -k -s -X PUT https://mcs1:8640/cmapi/0.4.0/cluster/start \
   --header 'Content-Type:application/json' \
   --header 'x-api-key:CMAPI_API_KEY' \
   --data '{"timeout":60}' \
   | jq .

Enable GTID Strict Mode

This action is performed on each replica server.

If you temporarily disabled the gtid_strict_mode system variable in the Disable GTID Strict Mode step, it can be re-enabled. If the gtid_strict_mode system variable was temporarily disabled in any configuration files, re-enable it.

Confirm ColumnStore Version

This action is performed on each ColumnStore node.

After upgrading, it is recommended to confirm the Enterprise ColumnStore version on each ColumnStore node. Connect to the node using MariaDB Client and query the Columnstore_version status variable with SHOW GLOBAL STATUS:

SHOW GLOBAL STATUS LIKE 'Columnstore_version';
+---------------------+-------+
| Variable_name       | Value |
+---------------------+-------+
| Columnstore_version | 6.1.1 |
+---------------------+-------+

Confirm ES Version

This action is performed on each ColumnStore node.

After upgrading, it is recommended to confirm the ES version on each ColumnStore node. Connect to the node using MariaDB Client and query the version system variable with SHOW GLOBAL VARIABLES:

SHOW GLOBAL VARIABLES LIKE 'version';
+---------------+----------------------------------+
| Variable_name | Value                            |
+---------------+----------------------------------+
| version       | 10.6.4-1-MariaDB-enterprise-log  |
+---------------+----------------------------------+

Clear Maintenance Mode for Replicas

This action is performed for each replica server on the MaxScale node.

After the upgrade, maintenance mode for each replica has been cleared in MaxScale using MaxScale's REST API. If you are using MaxCtrl, maintenance mode can be cleared using the clear server command:

$ maxctrl clear server \
   mcs2 \
   maintenance
  • As the first argument, provide the name for the server

  • As the second argument, provide maintenance as the state

Confirm Maintenance Mode is Cleared for Replicas

This action is performed for each replica server on the MaxScale node.

Confirm that maintenance mode in MaxScale has been cleared for each replica using MaxScale's REST API. If you are using MaxCtrl, the state of the replicas can be viewed using the list servers command:

$ maxctrl list servers
┌────────┬───────────────┬──────┬─────────────┬─────────────────┬─────────┐
│ Server │ Address       │ Port │ Connections │ State           │ GTID    │
├────────┼───────────────┼──────┼─────────────┼─────────────────┼─────────┤
│ mcs3   │ 192.0.2.3     │ 3306 │ 0           │ Slave, Running  │ 0-3-159 │
├────────┼───────────────┼──────┼─────────────┼─────────────────┼─────────┤
│ mcs2   │ 192.0.2.2     │ 3306 │ 0           │ Slave, Running  │ 0-1-88  │
├────────┼───────────────┼──────┼─────────────┼─────────────────┼─────────┤
│ mcs1   │ 192.0.2.1     │ 3306 │ 0           │ Master, Running │ 0-1-88  │
└────────┴───────────────┴──────┴─────────────┴─────────────────┴─────────┘

If the node is no longer in maintenance mode, then the State column will no longer show Maintenance as one of the states.