Upgrade to MaxScale 2.4

Overview

These instructions detail the upgrade to MariaDB MaxScale 2.4 in a MaxScale Instance configuration on a range of supported Operating Systems.

MariaDB MaxScale is an advanced database proxy and query router.

Term Definitions

Term

Definition

MaxScale instance

upgrade

  • A change from lower-versioned release of MariaDB MaxScale to a higher-versioned release of MariaDB MaxScale.

Backing Up Configuration

Upgrades can move or change configuration files. Before starting an upgrade, always back up your configuration files to ensure you can revert to the working system in the event that you encounter any issues during the upgrade.

To back up a configuration file, create a copy:

$ sudo cp /etc/maxscale.cnf /data/backups/config/maxscale.cnf

Upgrade

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

Stop the MaxScale Process

Before upgrading MariaDB MaxScale, first stop the current 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 maxscale
    

Upgrade via YUM (RHEL, CentOS, Rocky Linux)

  1. Retrieve your Customer Download Token at https://cloud.mariadb.com/csm?id=my_customer_token and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the YUM package repository.

    Installable versions of MariaDB MaxScale are 24.02, 23.08, 23.02, 22.08, 6, 2.5, and 2.4. Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 2.4.

    To configure YUM package repositories:

    $ sudo yum install wget
    
    $ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
    
    $ echo "f8eb9c1b59ccfd979d27e39798d2f2a98447dd29e2149ce92bf606aab4493ad9  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-maxscale-version="2.4"
    
  3. Upgrade MariaDB MaxScale and package dependencies:

    $ sudo yum update maxscale
    
  4. Configure MaxScale.

    The upgrade process only loads MaxScale onto the system. MaxScale requires configuration before MaxScale is ready for use.

Upgrade via APT (Debian, Ubuntu)

  1. Retrieve your Customer Download Token at https://cloud.mariadb.com/csm?id=my_customer_token and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the APT package repository.

    Installable versions of MariaDB MaxScale are 24.02, 23.08, 23.02, 22.08, 6, 2.5, and 2.4. Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 2.4.

    To configure APT package repositories:

    $ sudo apt install wget
    
    $ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
    
    $ echo "f8eb9c1b59ccfd979d27e39798d2f2a98447dd29e2149ce92bf606aab4493ad9  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-maxscale-version="2.4"
    
    $ sudo apt update
    
  3. Upgrade MariaDB MaxScale and package dependencies:

    $ sudo apt install --only-upgrade maxscale
    
  4. Configure MaxScale.

    The upgrade process only loads MaxScale onto the system. MaxScale requires configuration before MaxScale is ready for use.

Upgrade via ZYpp (SLES)

  1. Retrieve your Customer Download Token at https://cloud.mariadb.com/csm?id=my_customer_token and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

  2. Configure the ZYpp package repository.

    Installable versions of MariaDB MaxScale are 24.02, 23.08, 23.02, 22.08, 6, 2.5, and 2.4. Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 2.4.

    To configure ZYpp package repositories:

    $ sudo zypper install wget
    
    $ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
    
    $ echo "f8eb9c1b59ccfd979d27e39798d2f2a98447dd29e2149ce92bf606aab4493ad9  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
       --mariadb-maxscale-version="2.4"
    
  3. Upgrade MariaDB MaxScale and package dependencies:

    $ sudo zypper update maxscale
    
  4. Configure MaxScale.

    The upgrade process only loads MaxScale onto the system. MaxScale requires configuration before MaxScale is ready for use.

Configuration

Configuration parameters can change between releases of MariaDB MaxScale, which can have unexpected results.

  1. Determine which parameters have changed by reviewing all the changes made between your current release and the upgrade release.

  2. Change the specific parameters in maxscale.cnf.

Removed Deprecated maxctrl Commands

In MariaDB MaxScale 23.02, some deprecated MaxCtrl commands were removed:

Removed Deprecated maxctrl Options

In MariaDB MaxScale 23.02, several deprecated MaxCtrl command-line options were removed, since MaxScale previously added the ability to specify module parameters to MaxCtrl as key-value pairs. (MXS-4266)

This change can impact backward compatibility. Some scripts and tools written for previous versions of MaxCtrl will require updates to continue functioning with MaxCtrl from MaxScale 23.02. The old command-line parameters have been deprecated since MaxScale 22.08. The new syntax to specify parameters as key-value pairs has been supported since MariaDB MaxScale 6.2.0.

For example, in previous releases, the following maxctrl create monitor command could be executed:

$ maxctrl create monitor mdb_monitor mariadbmon \
   --monitor-user mxs \
   --monitor-password 'maxscale_passwd' \
   replication_user='repl_user' \
   replication_password='repl_pass' \
   --servers node1 node2 node3

Starting with MariaDB MaxScale 23.02, some deprecated command-line options have been removed and must be replaced with a key-value pair using the corresponding module parameter:

$ maxctrl create monitor mdb_monitor mariadbmon \
   user='mxs' \
   password='maxscale_passwd' \
   replication_user='repl_user' \
   replication_password='repl_pass' \
   --servers node1 node2 node3

For maxctrl create listener, the following deprecated command-line options were removed and must be replaced with a key-value pair using the listed parameter:

Command-line Option

Replaced by Parameter

--authenticator

authenticator

--authenticator-options

authenticator_options

--interface

interface

--protocol

protocol

--tls-ca-cert

ssl_ca

--tls-cert

ssl_cert

--tls-cert-verify-depth

ssl_cert_verify_depth

--tls-crl

ssl_crl

--tls-key

ssl_key

--tls-verify-peer-certificate

ssl_verify_peer_certificate

--tls-verify-peer-host

ssl_verify_peer_host

--tls-version

ssl_version

For maxctrl create monitor, the following deprecated command-line options were removed and must be replaced with a key-value pair using the listed parameter:

Command-line Option

Replaced by Parameter

--monitor-password

password

--monitor-user

user

Starting the MaxScale Instance

MariaDB MaxScale installations includes configuration to start, stop, restart, enable/disable on boot, and check the status of the MaxScale Instance using the operating system default process management system.

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

Operation

Command

Start

sudo systemctl start maxscale

Stop

sudo systemctl stop maxscale

Restart

sudo systemctl restart maxscale

Enable during startup

sudo systemctl enable maxscale

Disable during startup

sudo systemctl disable maxscale

Status

sudo systemctl status maxscale

Testing

When you have MariaDB MaxScale up and running, you should test it to ensure that it is working and that weren't any issues during startup.

Checking MaxScale Status

  1. Check that MaxScale is running properly by using the MaxCtrl utility:

    $ sudo maxctrl show maxscale
    
    ┌──────────────┬──────────────────────────────────────────────────────────────────────┐
    │ Version      │ 2.4.19                                                               │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Commit       │ 61b8bbf7f63c38ca9c408674e66f3627a0b2192e                             │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Started At   │ Fri, 03 Jan 2020 18:05:18 GMT                                        │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Activated At │ Fri, 03 Jan 2020 18:05:18 GMT                                        │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Uptime       │ 109                                                                  │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Parameters   │ {                                                                    │
    │              │     "libdir": "/usr/lib/x86_64-linux-gnu/maxscale",                  │
    │              │     "datadir": "/var/lib/maxscale",                                  │
    │              │     "process_datadir": "/var/lib/maxscale/data3850",                 │
    │              │     "cachedir": "/var/cache/maxscale",                               │
    │              │     "configdir": "/etc",                                             │
    │              │     "config_persistdir": "/var/lib/maxscale/maxscale.cnf.d",         │
    │              │     "module_configdir": "/etc/maxscale.modules.d",                   │
    │              │     "piddir": "/var/run/maxscale",                                   │
    │              │     "logdir": "/var/log/maxscale",                                   │
    │              │     "langdir": "/var/lib/maxscale",                                  │
    │              │     "execdir": "/usr/bin",                                           │
    │              │     "connector_plugindir": "/usr/lib/x86_64-linux-gnu/mysql/plugin", │
    │              │     "threads": 1,                                                    │
    │              │     "thread_stack_size": 8388608,                                    │
    │              │     "writeq_high_water": 0,                                          │
    │              │     "writeq_low_water": 0,                                           │
    │              │     "auth_connect_timeout": 3,                                       │
    │              │     "auth_read_timeout": 1,                                          │
    │              │     "auth_write_timeout": 2,                                         │
    │              │     "skip_permission_checks": false,                                 │
    │              │     "admin_auth": true,                                              │
    │              │     "admin_enabled": true,                                           │
    │              │     "admin_log_auth_failures": true,                                 │
    │              │     "admin_host": "127.0.0.1",                                       │
    │              │     "admin_port": 8989,                                              │
    │              │     "admin_ssl_key": "",                                             │
    │              │     "admin_ssl_cert": "",                                            │
    │              │     "admin_ssl_ca_cert": "",                                         │
    │              │     "admin_pam_readwrite_service": "",                               │
    │              │     "admin_pam_readonly_service": "",                                │
    │              │     "passive": false,                                                │
    │              │     "query_classifier": "",                                          │
    │              │     "query_classifier_cache_size": 155008819,                        │
    │              │     "retain_last_statements": 0,                                     │
    │              │     "dump_last_statements": "never",                                 │
    │              │     "session_trace": 0,                                              │
    │              │     "load_persisted_configs": true,                                  │
    │              │     "max_auth_errors_until_block": 10                                │
    │              │ }                                                                    │
    └──────────────┴──────────────────────────────────────────────────────────────────────┘