Upgrade to MaxScale 22.08
This page is part of MariaDB's Documentation.
The parent of this page is: Upgrades for MariaDB MaxScale
Topics on this page:
Overview
These instructions detail the upgrade to MariaDB MaxScale 22.08 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 |
|
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://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the YUM package repository.
Installable versions of MariaDB MaxScale are
24.02
,23.08
,23.02
,22.08
,6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 22.08
.To configure YUM package repositories:
$ sudo yum install curl
$ curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "97e5ef25b4c4a4bd70b30da46b1eae0b57db2f755ef820a28d254e902ab5a879 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="22.08"
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://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the APT package repository.
Installable versions of MariaDB MaxScale are
24.02
,23.08
,23.02
,22.08
,6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 22.08
.To configure APT package repositories:
$ sudo apt install curl
$ curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "97e5ef25b4c4a4bd70b30da46b1eae0b57db2f755ef820a28d254e902ab5a879 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="22.08"
$ 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://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the ZYpp package repository.
Installable versions of MariaDB MaxScale are
24.02
,23.08
,23.02
,22.08
,6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 22.08
.To configure ZYpp package repositories:
$ sudo zypper install curl
$ curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "97e5ef25b4c4a4bd70b30da46b1eae0b57db2f755ef820a28d254e902ab5a879 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="22.08"
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 by reviewing all the changes made between your current release and the upgrade release.
Upgrading from MaxScale 2.2 or earlier to MaxScale 2.3 guide.
"Changes in MaxScale 2.5" compared to MaxScale 2.4
"Changes in MaxScale 6" compared to MaxScale 2.5
"Changes in MaxScale 22.08" compared to MaxScale 6
Change the specific parameters in
maxscale.cnf
.
Changes in MaxScale 2.5
When upgrading from MaxScale 2.4 and earlier to MaxScale 22.08, the changes introduced in MaxScale 2.5 must be taken into consideration.
Passwords
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 thedetect_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 themaster_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 theslave_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.
Changes in MaxScale 6
When upgrading from MaxScale 2.5 and earlier to MaxScale 22.08, the changes introduced in MaxScale 6 must be taken into consideration.
TLS/SSL
MaxScale's
ssl
parameter can no longer be set torequired
ordisabled
:ssl=true
replacesssl=required
ssl=false
replacesssl=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 from1
toauto
(MXS-3537)
ColumnStore
When using MaxScale with ColumnStore 5 and later, MariaDB Monitor (
mariadbmon
) is used instead of ColumnStore Monitor (csmon
).
Changes in MaxScale 22.08
When upgrading from MaxScale 6 and earlier to MaxScale 22.08, the changes introduced in MaxScale 22.08 must be taken into consideration.
Database Firewall Filter
The
dbfwfilter
that was deprecated in MaxScale 6 has been removed in MaxScale 22.08.
Deprecated Parameters
The server parameter
ssl_ca_cert
has been renamed tossl_ca
andssl_ca_cert
has been deprecated.ssl_ca_cert
is now an alias forssl_ca
and can still be used, but MariaDB recommends usingssl_ca
, as support forssl_ca_cert
will be removed in a future release.The server parameter
admin_ssl_ca_cert
has been renamed toadmin_ssl_ca
andadmin_ssl_ca_cert
has been deprecated.admin_ssl_ca_cert
is now an alias foradmin_ssl_ca
and can still be used, but MariaDB recommends usingadmin_ssl_ca
, as support foradmin_ssl_ca_cert
will be removed in a future release.
Removed Parameters
The following MariaDB Monitor (
mariadbmon
) parameters have been removed:ignore_external_masters
detect_replication_lag
detect_standalone_master
detect_stale_master
(replaced bymaster_conditions
)detect_stale_slave
(replaced byslave_conditions
)
Default Changed for Logging Behavior
Prior to MaxScale 22.08.1, by default MaxScale logs to
syslog
in addition to the MaxScale log.Starting with MaxScale 22.08.1, by default MaxScale only logs to the MaxScale log and no longer logs to
syslog
.To retain the behavior of prior releases, in your MaxScale configuration, under the
[maxscale]
section, specifysyslog=true
:[maxscale] syslog=true
REST API Endpoint Removed
The
/v1/maxscale/tasks/
endpoint has been removed from the REST API.
Removed Deprecated maxctrl
Commands
In MariaDB MaxScale 23.02, some deprecated MaxCtrl commands were removed:
maxctrl drain
has been removed and can be replaced withmaxctrl 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:
Command-line Option | Replaced by 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:
Command-line Option | Replaced by Parameter |
---|---|
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 |
|
Stop |
|
Restart |
|
Enable during startup |
|
Disable during startup |
|
Status |
|
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 │ 22.08.12 │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ 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 │ │ │ } │ └──────────────┴──────────────────────────────────────────────────────────────────────┘