Upgrade to MaxScale 6

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://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

2. Configure the YUM package repository.

   Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 6.

   To configure YUM package repositories:

   $ sudo yum install curl
   

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

   $ echo "99ea6c55dbf32bfc42cdcd05c892aebc5e51b06f4c72ec209031639d6e7db9fe  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="6"
   

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://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

2. Configure the APT package repository.

   Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 6.

   To configure APT package repositories:

   $ sudo apt install curl
   

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

   $ echo "99ea6c55dbf32bfc42cdcd05c892aebc5e51b06f4c72ec209031639d6e7db9fe  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="6"
   

   $ 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://customers.mariadb.com/downloads/token/ and substitute for CUSTOMER_DOWNLOAD_TOKEN in the following directions.

2. Configure the ZYpp package repository.

   Pass the version you want to install using the --mariadb-maxscale-version flag to the mariadb_es_repo_setup script. The following directions reference 6.

   To configure ZYpp package repositories:

   $ sudo zypper install curl
   

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

   $ echo "99ea6c55dbf32bfc42cdcd05c892aebc5e51b06f4c72ec209031639d6e7db9fe  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="6"
   

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.

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.

TLS/SSL

• MaxScale's ssl parameter can no longer be set to required or disabled:

  • ssl=true replaces ssl=required

  • ssl=false replaces ssl=disabled

Deprecated Features

• dbfwfilter is deprecated (but not removed) in MaxScale 6.

• Multi-line configuration parameters are deprecated (but not removed) in MaxScale 6.

Defaults Changed

• The default value of threads has changed from 1 to auto (MXS-3537)

ColumnStore

• When using MaxScale with ColumnStore 5 and later, MariaDB Monitor (mariadbmon) is used instead of ColumnStore Monitor (csmon).

Removed Deprecated maxctrl Commands

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

• maxctrl cluster

• maxctrl drain has been removed and can be replaced with maxctrl set server SERVER_NAME drain

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:

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:

Checking MaxScale Status

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

   $ sudo maxctrl show maxscale
   

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