Upgrade to MaxScale 2.5

This page is part of MariaDB's MariaDB Documentation.

The parent of this page is: Upgrades for MariaDB MaxScale

Topics on this page:

Overview
Term Definitions
Backing Up Configuration
Upgrade
Configuration
Upgrades from MaxScale 2.4 and Earlier
Starting the MaxScale Instance
Testing
- Checking MaxScale Status

Overview

These instructions detail the upgrade to MariaDB MaxScale 2.5 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	MariaDB MaxScale running by itself on a single host. It interacts with other hosts, such as deployments using MariaDB Replication MariaDB Replication, Galera Cluster Galera Cluster, and ColumnStore ColumnStore. It serves as the database proxy and load balancer.
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.

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)

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.

Configure the YUM package repository.

Installable versions of MariaDB MaxScale are 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.5.

To configure YUM package repositories:

$ sudo yum install wget

$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup

$ echo "8dfef0ec98eb03a4455df07b33107a6d4601425c9df0ab5749b8f10bf3abdcbb  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.5"

Upgrade MariaDB MaxScale and package dependencies:
```
$ sudo yum update maxscale
```
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)

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.

Configure the APT package repository.

To configure APT package repositories:

$ sudo apt install wget

$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup

$ echo "8dfef0ec98eb03a4455df07b33107a6d4601425c9df0ab5749b8f10bf3abdcbb  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.5"

$ sudo apt update

Upgrade MariaDB MaxScale and package dependencies:
```
$ sudo apt install --only-upgrade maxscale
```
Configure MaxScale.

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

Upgrade via ZYpp (SLES)

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.

Configure the ZYpp package repository.

To configure ZYpp package repositories:

$ sudo zypper install wget

$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup

$ echo "8dfef0ec98eb03a4455df07b33107a6d4601425c9df0ab5749b8f10bf3abdcbb  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.5"

Upgrade MariaDB MaxScale and package dependencies:
```
$ sudo zypper update maxscale
```
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.

Determine which parameters have changed in your specific release.
- If you are upgrading from MaxScale 2.2 or earlier to MaxScale 2.5, then review the configuration parameter changes in the Upgrading to MaxScale 2.3 guide.
- If you are upgrading from MaxScale 2.3 or earlier to MaxScale 2.5, then review the configuration parameter changes in the Upgrading to MaxScale 2.4 guide.
- If you are upgrading from MaxScale 2.4 or earlier to MaxScale 2.5, then review the configuration changes in "Upgrades from MaxScale 2.4 and Earlier".
Change the specific parameters in maxscale.cnf.

Upgrades from MaxScale 2.4 and Earlier

When upgrading from MaxScale 2.4 and earlier, the configuration changes introduced in MaxScale 2.5 must be taken into consideration.

Passwords

MaxScale's password encryption features have been updated to be more secure. Passwords encrypted in old versions will still work, but it is recommended to generate a new encryption key with the maxkeys command and to re-encrypt passwords with the maxpasswd command.

User Account Privileges

MaxScale's user account requires additional privileges in MaxScale 2.5.

Ensure that the user account has the following privileges:

GRANT SHOW DATABASES ON *.*
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.columns_priv
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.db
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.procs_priv
        TO 'mxs'@'192.0.2.1';
GRANT SELECT ON mysql.proxies_priv
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.roles_mapping
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.tables_priv
     TO 'maxscale'@'192.0.2.1';
GRANT SELECT ON mysql.user
     TO 'maxscale'@'192.0.2.1';

MariaDB Monitor

MaxScale 2.5 includes configuration changes for MariaDB Monitor (mariadbmon):

The detect_stale_master and the detect_standalone_master parameters have been deprecated. They can still be used, but they will be removed in a later version of MaxScale. Users should use the master_conditions parameter instead.

For example:

[repl-monitor]
type          = monitor
module        = mariadbmon
servers       = server1,server2,server3
user          = maxscale
password      = max_passwd
auto_failover = ON
auto_rejoin   = ON
master_conditions = connected_slave,running_slave

The detect_stale_slave parameter has been deprecated. It can still be used, but it will be removed in a later version of MaxScale. Users should use the slave_conditions parameter instead.

For example:

[repl-monitor]
type          = monitor
module        = mariadbmon
servers       = server1,server2,server3
user          = maxscale
password      = max_passwd
auto_failover = ON
auto_rejoin   = ON
slave_conditions  = running_master,writable_master

ColumnStore Monitor

MaxScale 2.5 includes configuration changes for ColumnStore Monitor (csmon):

The version parameter was previously optional, but it is now required.

For example:

[col-monitor]
type          = monitor
module        = csmon
servers       = server1,server2,server3
user          = maxscale
password      = max_passwd
version       = 1.2

Binlog Router

MaxScale 2.5 includes a completely re-implemented Binlog Router (binlogrouter):

Thoroughly test your configuration with the new implementation to ensure that the new version meets your needs.

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

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

$ sudo maxctrl show maxscale

┌──────────────┬──────────────────────────────────────────────────────────────────────┐
│ Version      │ 2.5.24                                                               │
├──────────────┼──────────────────────────────────────────────────────────────────────┤
│ 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                                │
│              │ }                                                                    │
└──────────────┴──────────────────────────────────────────────────────────────────────┘