Upgrading MariaDB MaxScale
Upgrading MariaDB MaxScale
For more information about what has changed, please refer to the ChangeLog and to the release notes.
Before starting the upgrade, any existing configuration files should be backed up.
- Upgrading MariaDB MaxScale
- Upgrading MariaDB MaxScale from 21.06 to 22.08
- Upgrading MariaDB MaxScale from 2.5 to 21.06
- Upgrading MariaDB MaxScale from 2.4 to 2.5
- Upgrading MariaDB MaxScale from 2.3 to 2.4
- Upgrading MariaDB MaxScale from 2.2 to 2.3
- Upgrading MariaDB MaxScale from 2.1 to 2.2
- Upgrading MariaDB MaxScale from 2.0 to 2.1
- Upgrading MariaDB MaxScale from 1.4 to 2.0
- Upgrading MaxScale from 1.3 to 1.4
- Upgrading MaxScale from 1.2 to 1.3
- Upgrading MaxScale from 1.1 to 1.2
- Upgrading MaxScale from 1.0 to 1.1
Upgrading MariaDB MaxScale from 21.06 to 22.08
Removed Features
-
The support for legacy encryption keys generated with
maxkeys
from pre-2.5 versions has been removed. This feature was deprecated in MaxScale 2.5 when the new key storage format was introduced. To migrate to the new key storage format, create a new key file withmaxkeys
and re-encrypt the passwords withmaxpasswd
. -
The deprecated Database Firewall filter has been removed.
Upgrading MariaDB MaxScale from 2.5 to 21.06
NOTE MaxScale 6.4 was renamed to 21.06 in May 2024. Thus, what would have been released as 6.4.16 in June, was released as 21.06.16. The purpose of this change is to make the versioning scheme used by all MaxScale series identical. 21.06 denotes the year and month when the first 6 release was made.
Duration Type Parameters
Using duration type parameters without an explicit suffix has been deprecated in
MaxScale 2.4. In MaxScale 6 they are no longer allowed when used with the REST
API or MaxCtrl. This means that any create
or alter
commands in MaxCtrl that
use a duration type parameter must explicitly specify the suffix of the unit.
For example, the following command:
maxctrl alter service My-Service connection_keepalive 30000
should be replaced with:
maxctrl alter service My-Service connection_keepalive 30000ms
Duration type parameters can still be defined in the configuration file without an explicit suffix but this behavior is deprecated. The recommended approach is to add explicit suffixes to all duration type parameters when upgrading to MaxScale 6.
Changed Parameters
threads
The default value of threads
was changed to auto
.
Removed Parameters
Core Parameters
The following deprecated core parameters have been removed:
thread_stack_size
Schemarouter
The deprecated aliases for the schemarouter parameters ignore_databases
and
ignore_databases_regex
have been removed. They can be replaced with
ignore_tables
and ignore_tables_regex
.
In addition, the preferred_server
parameter that was deprecated in 2.5 has
also been removed.
mariadbmon
- MariaDBMonitor settings
ignore_external_masters
,detect_replication_lag
detect_standalone_master
,detect_stale_master
anddetect_stale_slave
have been removed. The first two were ineffective, the latter three are replaced bymaster_conditions
andslave_conditions
.
Session Command History
The prune_sescmd_history
, max_sescmd_history
and disable_sescmd_history
have been made into generic service parameters that are shared between all
routers that support it.
The default value of prune_sescmd_history
was changed from false
to
true
. This was done as most MaxScale installations either benefit from it
being enabled or are not affected by it.
Upgrading MariaDB MaxScale from 2.4 to 2.5
MaxAdmin
The deprecated MaxAdmin interface has been removed in 2.5.0 in favor of the REST
API and the MaxCtrl command line client. The cli
and maxscaled
modules can
no longer be used.
Authentication
The credentials used by services now require additional grants. For a full list of required grants, refer to the protocol documentation.
MariaDB-Monitor
The settings detect_stale_master
, detect_standalone_master
and
detect_stale_slave
are replaced by master_conditions
and
slave_conditions
. The old settings may still be used, but will be removed in
a later version.
Password encryption
The encrypted passwords feature has been updated to be more secure. Users are
recommended to generate a new encryption key and and re-encrypt their passwords
using the maxkeys
and maxpasswd
utilities. Old passwords still work.
Default Server State
The default state of servers in 2.4 was Running
and in 2.5 it is now
Down
. This was done to prevent newly added servers from being accidentally
used before they were monitored.
Columnstore Monitor
It is now mandatory to specify in the configuration what version the monitored Columnstore cluster is.
[CSMonitor] type=monitor module=csmon version=1.5 ...
Please see the documentation for details.
New binlog router
The binlog router delivered with MaxScale 2.5 is completely new and not 100% backward compatible with the binlog router delivered with earlier MaxScale versions. If you use the binlog router, carefully assess whether the functionality provided by the new one fulfills your requirements, before upgrading MaxScale.
Tee Filter
The tee filter parameter service
has been deprecated in favor of the target
parameter. All usages of service
can be replaced with target
.
Upgrading MariaDB MaxScale from 2.3 to 2.4
Section Names
Reserved Names
Section and object names starting with @@
are now reserved for
internal use by MaxScale.
In case such names have been used, they must manually be changed in all configuration files of MaxScale, before MaxScale 2.4 is started.
Those files are:
- The main configuration file; typically
/etc/maxscale.cnf
. - All nested configuration files; typically
/etc/maxscale.cnf.d/*
. - All dynamic configuration files; typically
/var/lib/maxscale/maxscale.cnd.d/*
.
Whitespace in Names
Whitespace in section names that was deprecated in MaxScale 2.2 will now be rejected, which will cause the startup of MaxScale to fail.
To prevent that, section names like
[My Server] ... [My Service] ... servers=My Server
must be changed, for instance, to
[MyServer] ... [MyService] ... servers=MyServer
Durations
Durations can now be specified using one of the suffixes h
, m
, s
and ms
for specifying durations in hours, minutes, seconds and
milliseconds, respectively.
Not providing an explicit unit has been deprecated in MaxScale 2.4, so it is adviseable to add suffixes to durations. For instance,
some_param=60s some_param=60000ms
Improved Admin User Encryption
MaxScale 2.4 will use a SHA2-512 hash for new admin user passwords. To upgrade a
user to use the better hashing algorithm, either recreate the user or use the
maxctrl alter user
command.
MariaDB-Monitor
The following settings have been removed and cause a startup error if defined:
mysql51_replication
multimaster
allow_cluster_recovery
.
ReadWriteSplit
-
If multiple masters are available for a readwritesplit service, the one with the lowest connection count is selected.
-
If a master server is placed into maintenance mode, all open transactions are allowed to gracefully finish before the session is closed. To forcefully close the connections, use the
--force
option formaxctrl set server
. -
The
lazy_connect
feature can be used as a workaround to MXS-619. It also reduces the overall load on the system when connections are rapidly opened and closed. -
Transaction replays now have a limit on how many times a replay is attempted. The default values is five attempts and is controlled by the
transaction_replay_attempts
parameter. -
If transaction replay is enabled and a deadlock occurs (SQLSTATE 40XXX), the transaction is automatically retried.
Upgrading MariaDB MaxScale from 2.2 to 2.3
Increased Memory Use
Starting with MaxScale 2.3.0 up to 40% of the memory can be used for caching parsed queries. The most noticeable change is that it improves performance in almost all cases where queries need to be parsed. Most of the time this happens when the readwritesplit router or filters are used.
The amount of memory that MaxScale uses can be controlled with the
query_classifier_cache_size
parameter. For example, to limit the total
memory to 1GB, add query_classifier_cache_size=1G
to your
configuration. To disable it, set the value to 0
.
In addition to the aforementioned query classifier caching, the readwritesplit session command history is enabled by default in 2.3 but is limited to a maximum of 50 commands after which the history is disabled. This is unlikely to show in any metrics but it contributes to the increased memory foorprint of MaxScale.
Unknown Global Parameters
All unknown parameters are now treated as errors. Check your configuration for errors if MaxScale fails to start after upgrading to 2.3.1.
passwd
is deprecated
In the configuration file, passwords for monitors and services should be
specified using password
; the support for the deprecated
passwd
will be removed in the future. That is, the following
[The-Service] type=service passwd=some-service-password ... [The-Monitor] type=monitor passwd=some-monitor-password ...
should be changed to
[The-Service] type=service password=some-service-password ... [The-Monitor] type=monitor password=some-monitor-password ...
authenticator_options
for servers is ignored
Authenticator options are now only used with listeners.
Upgrading MariaDB MaxScale from 2.1 to 2.2
Administrative Users
The file format for the administrative users used by MaxScale has been
changed. Old style files are automatically upgraded and a backup of the old file is
stored in /var/lib/maxscale/passwd.backup
.
Regular Expression Parameters
Modules may now use a built-in regular expression string parameter type instead
of a normal string when accepting patterns. The modules that use the new regex
parameter type are qlafilter and tee. When inputting pattern, enclose the
string in slashes, e.g. match=/^select/
defines the pattern ^select
.
Binlog Server
Binlog server automatically accepts GTID connection from MariaDB 10 slave servers by saving all incoming GTIDs into a SQLite map database.
MaxCtrl Included in Main Package
In the 2.2.1 beta version MaxCtrl was in its own package whereas in 2.2.2
it is in the main maxscale
package. If you have a previous installation
of MaxCtrl, please remove it before upgrading to MaxScale 2.2.2.
Upgrading MariaDB MaxScale from 2.0 to 2.1
IPv6 Support
MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to
was changed from the IPv4 address 0.0.0.0
to the IPv6 address ::
. To bind to the old IPv4 address,
add address=0.0.0.0
to the listener definition.
Persisted Configuration Files
Starting with MaxScale 2.1, any changes made with the newly added
runtime configuration change
will be persisted in a configuration file. These files are located in /var/lib/maxscale/maxscale.cnf.d/
.
MaxScale Log Files
The name of the log file was changed from maxscaleN.log to maxscale.log. The default location for the log file is /var/log/maxscale/maxscale.log.
Rotating the log files will cause MaxScale to reopen the file instead of renaming them. This makes the MaxScale logging facility logrotate compatible.
ReadWriteSplit
The disable_sescmd_history
option is now enabled by default. This means that
slaves will not be recovered mid-session even if a replacement slave is
available. To enable the legacy behavior, add the disable_sescmd_history=true
parameter to the service definition.
Persistent Connections
The MariaDB session state is reset in MaxScale 2.1 for persistent connections. This means that any modifications to the session state (default database, user variable etc.) will not survive if the connection is put into the connection pool. For most users, this is the expected behavior.
User Data Cache
The location of the MariaDB user data cache was moved from
/var/cache/maxscale/<Service>
to /var/cache/maxscale/<Service>/<Listener>
.
Galeramon Monitoring Algorithm
Galeramon will assign the master status only to the node which has a wsrep_local_index value of 0. This will guarantee consistent writes with multiple MaxScales but it also causes slower changes of the master node.
To enable the legacy behavior, add root_node_as_master=false
to the Galera
monitor configuration.
MaxAdmin Editing Mode
The default editing mode was changed from vim to emacs mode. To start
maxadmin in the legacy mode, use the -i
option.
Upgrading MariaDB MaxScale from 1.4 to 2.0
MaxAdmin
The default way the communication between MaxAdmin and MariaDB MaxScale is handled has been changed from an internet socket to a Unix domain socket. The former alternative is still available but has been deprecated.
If no arguments are given to MaxAdmin, it will attempt to connect to
MariaDB MaxScale using a Unix domain socket. After the upgrade you will
need to provide at least one internet socket related flag - -h
, -P
,
-u
or -p
- to force MaxAdmin to use the internet socket approach.
E.g.
user@host $ maxadmin -u admin
MySQL Monitor
The MySQL Monitor now assigns the stale state to the master server by default. In addition to this, the slave servers receive the stale slave state when they lose the connection to the master. This should not cause changes in behavior but the output of MaxAdmin will show new states when replication is broken.
Upgrading MaxScale from 1.3 to 1.4
Service user permissions
The service users now also need SELECT privileges on mysql.tables_priv. This is required for the resolution of table level grants. To grant SELECT privileges for the service user, replace the user and hostname in the following example.
GRANT SELECT ON mysql.tables_priv TO 'username'@'maxscalehost';
Password encryption
MaxScale 1.4 upgrades the used password encryption algorithms to more secure ones.
This requires that the password files are recreated with the maxkeys
tool.
For more information about how to do this, please read the installation guide:
MariaDB MaxScale Installation Guide
SSL
The SSL configuration parameters are now a part of the listeners. If a service used the old style SSL configuration parameters, the values should be moved to the listener which is associated with that service.
Here is an example of an old style configuration.
[RW-Split-Router] type=service router=readwritesplit servers=server1,server2,server3,server4 user=jdoe passwd=BD26E4139A15280CA882264AA1551C70 ssl=required ssl_cert=/home/user/certs/server-cert.pem ssl_key=/home/user/certs/server-key.pem ssl_ca_cert=/home/user/certs/ca.pem ssl_version=TLSv12 [RW-Split-Listener] type=listener service=RW-Split-Router port=3306
And here is the new, 1.4 compatible configuration style.
[RW-Split-Router] type=service router=readwritesplit servers=server1,server2,server3,server4 user=jdoe passwd=BD26E4139A15280CA882264AA1551C70 [RW-Split-Listener] type=listener service=RW-Split-Router port=3306 ssl=required ssl_cert=/home/user/certs/server-cert.pem ssl_key=/home/user/certs/server-key.pem ssl_ca_cert=/home/user/certs/ca.pem ssl_version=TLSv12
Please also note that the enabled
SSL mode is no longer supported due to
the inherent security issues with allowing SSL and non-SSL connections on
the same port. In addition to this, SSLv3 is no longer supported due to
vulnerabilities found in it.
Upgrading MaxScale from 1.2 to 1.3
Binlog Router
The master server details are now provided with a master.ini file located in the binlog directory and it can be changed using a CHANGE MASTER TO command issued via a MySQL connection to MaxScale.
This file, properly filled, is now mandatory and without it the binlog router cannot connect to the master database.
Before starting binlog router after MaxScale 1.3 upgrade, please add relevant information to master.ini, example:
[binlog_configuration] master_host=127.0.0.1 master_port=3308 master_user=repl master_password=somepass filestem=repl-bin
Additionally, the option servers=masterdb
in the service definition is no
longer required.
Upgrading MaxScale from 1.1 to 1.2
This document describes upgrading MaxScale from version 1.1.1 to 1.2 and
the major differences in the new version compared to the old version. The
major changes can be found in the Changelog.txt
file in the installation
directory and the official release notes in the ReleaseNotes.txt
file.
Installation
Upgrading MaxScale will copy the MaxScale.cnf
file in
/usr/local/mariadb-maxscale/etc/
to /etc/
and renamed to maxscale.cnf
.
Binary log files are not automatically copied and should be manually moved
from /usr/local/mariadb-maxscale
to /var/lib/maxscale/
.
File location changes
MaxScale 1.2 follows the FHS-standard and
installs to /usr/
and /var/
subfolders. Here are the major changes and
file locations.
- Configuration files are located in
/etc/
and use lowercase letters:/etc/maxscale.cnf
- Binary files are in
/usr/bin/
- Libraries and modules are in
/usr/lib64/maxscale/
. If you are using custom modules, please make sure they are in this directory before starting MaxScale. - Log files are in the
var/log/maxscale/
folder - MaxScale's PID file is located in
/var/run/maxscale/maxscale.pid
- Data files and other persistent files are in
/var/lib/maxscale/
Running MaxScale without root permissions
MaxScale can run as a non-root user with the 1.2 version. RPM and DEB
packages install the maxscale
user and maxscale
group which are used
by the init scripts and systemd configuration files. If you are installing
from a binary tarball, you can run the postinst
script included in it to
manually create these groups.
Upgrading MaxScale from 1.0 to 1.1
This document describes upgrading MaxScale from version 1.0.5 to 1.1.0 and
the major differences in the new version compared to the old version. The
major changes can be found in the Changelog.txt
file in the installation
directory and the official release notes in the ReleaseNotes.txt
file.
Installation
If you are installing MaxScale from a RPM package, we recommend you back
up your configuration and log files and that you remove the old installation
of MaxScale completely. If you choose to upgrade MaxScale instead of removing
it and re-installing it afterwards, the init scripts in /etc/init.d
folder
will be missing. This is due to the RPM packaging system but the script can
be re-installed by running the postinst
script found in the
/usr/local/mariadb-maxscale
folder.
# Re-install init scripts cd /usr/local/mariadb-maxscale ./postinst
The 1.1.0 version of MaxScale installs into /usr/local/mariadb-maxscale
instead of /usr/local/skysql/maxscale
. This will cause external references
to MaxScale's home directory to stop working so remember to update all
paths with the new version.
MaxAdmin changes
The MaxAdmin client's default password in MaxScale 1.1.0 is mariadb
instead of skysql
.