MySQL Router 8.0 Release Notes

Abstract

This document contains release notes for the changes in each release of MySQL Router 8.0.

For additional MySQL Router documentation, see https://dev.mysql.com/doc/mysql-router/en/.

Updates to these notes occur as new product features are added, so that everybody can follow the development

process. If a recent version is listed here that you cannot find on the download page (https://dev.mysql.com/

downloads/), the version has not yet been released.

The documentation included in source and binary distributions may not be fully up to date with respect to release note

entries because integration of the documentation occurs at release build time. For the most up-to-date release notes,

please refer to the online documentation instead.

For legal information, see the Legal Notices.

For help with using MySQL, please visit the MySQL Forums, where you can discuss your issues with other MySQL

users.

Document generated on: 2024-08-23 (revision: 28896)

Table of Contents

Preface and Legal Notices ................................................................................................................. 2

Changes in MySQL Router 8.0.39 (2024-07-23, General Availability) .................................................... 3

Changes in MySQL Router 8.0.38 (2024-07-01, General Availability) .................................................... 4

Changes in MySQL Router 8.0.37 (2024-04-30, General Availability) .................................................... 4

Changes in MySQL Router 8.0.36 (2024-01-16, General Availability) .................................................... 5

Changes in MySQL Router 8.0.35 (2023-10-25, General Availability) .................................................... 6

Changes in MySQL Router 8.0.34 (2023-07-18, General Availability) .................................................... 7

Changes in MySQL Router 8.0.33 (2023-04-18, General Availability) .................................................... 8

Changes in MySQL Router 8.0.32 (2023-01-17, General Availability) .................................................. 10

Changes in MySQL Router 8.0.31 (2022-10-11, General Availability) .................................................. 12

Changes in MySQL Router 8.0.30 (2022-07-26, General Availability) .................................................. 13

Changes in MySQL Router 8.0.29 (2022-04-26, General Availability) .................................................. 14

Changes in MySQL Router 8.0.28 (2022-01-18, General Availability) .................................................. 15

Changes in MySQL Router 8.0.27 (2021-10-19, General Availability) .................................................. 16

Changes in MySQL Router 8.0.26 (2021-07-20, General Availability) .................................................. 17

Changes in MySQL Router 8.0.25 (2021-05-11, General Availability) .................................................. 18

Changes in MySQL Router 8.0.24 (2021-04-20, General Availability) .................................................. 18

Changes in MySQL Router 8.0.23 (2021-01-18, General Availability) .................................................. 19

Changes in MySQL Router 8.0.22 (2020-10-19, General Availability) .................................................. 20

Changes in MySQL Router 8.0.21 (2020-07-13, General Availability) .................................................. 21

Changes in MySQL Router 8.0.20 (2020-04-27, General Availability) .................................................. 22

Changes in MySQL Router 8.0.19 (2020-01-13, General Availability) .................................................. 24

Changes in MySQL Router 8.0.18 (2019-10-14, General Availability) .................................................. 25

Changes in MySQL Router 8.0.17 (2019-07-22, General Availability) .................................................. 25

Changes in MySQL Router 8.0.16 (2019-04-25, General Availability) .................................................. 27

Changes in MySQL Router 8.0.15 (2019-02-01, General Availability) .................................................. 29

Changes in MySQL Router 8.0.14 (2019-01-21, General Availability) .................................................. 29

MySQL Router 8.0 Release Notes

Changes in MySQL Router 8.0.13 (2018-10-22, General Availability) .................................................. 30

Changes in MySQL Router 8.0.12 (2018-07-27, General Availability) .................................................. 31

Changes in MySQL Router 8.0.11 (2018-04-19, General Availability) .................................................. 33

Changes in MySQL Router 8.0.5 - 8.0.10 (Skipped version numbers) ................................................. 33

Changes in MySQL Router 8.0.4 (2018-02-07, Release Candidate) .................................................... 33

Changes in MySQL Router 8.0.3 (2017-09-29, Development Milestone) .............................................. 35

Preface and Legal Notices

This document contains release notes for the changes in each release of MySQL Router 8.0.

Legal Notices

License Restrictions

This software and related documentation are provided under a license agreement containing restrictions

on use and disclosure and are protected by intellectual property laws. Except as expressly permitted

in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,

modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any

means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for

interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free.

If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software, software documentation, data (as defined in the Federal Acquisition Regulation), or

related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S.

Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated

software, any programs embedded, installed, or activated on delivered hardware, and modifications

of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed

by U.S. Government end users are "commercial computer software," "commercial computer software

documentation," or "limited rights data" pursuant to the applicable Federal Acquisition Regulation and

agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display,

disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including

any operating system, integrated software, any programs embedded, installed, or activated on delivered

hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle

data, is subject to the rights and limitations specified in the license contained in the applicable contract.

The terms governing the U.S. Government's use of Oracle cloud services are defined by the applicable

contract for such services. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management

applications. It is not developed or intended for use in any inherently dangerous applications, including

applications that may create a risk of personal injury. If you use this software or hardware in dangerous

applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other

MySQL Router 8.0 Release Notes

measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages

caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle, Java, MySQL, and NetSuite are registered trademarks of Oracle and/or its affiliates. Other names

may be trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks

are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,

Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a

registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content,

products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and

expressly disclaim all warranties of any kind with respect to third-party content, products, and services

unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its

affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of

third-party content, products, or services, except as set forth in an applicable agreement between you and

Oracle.

Use of This Documentation

This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the

following terms:

You may create a printed copy of this documentation solely for your own personal use. Conversion to other

formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish

or distribute this documentation in any form or on any media, except if you distribute the documentation in

a manner similar to how Oracle disseminates it (that is, electronically for download on a Web site with the

software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated

together with the software on the same medium. Any other use, such as any dissemination of printed

copies or use of this documentation, in whole or in part, in another publication, requires the prior written

consent from an authorized representative of Oracle. Oracle and/or its affiliates reserve any and all rights

to this documentation not expressly granted above.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support for Accessibility

Oracle customers that have purchased support have access to electronic support through My Oracle

Support. For information, visit

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/

lookup?ctx=acc&id=trs if you are hearing impaired.

Changes in MySQL Router 8.0.39 (2024-07-23, General Availability)

This release contains no functional changes and is published to align the version number with the MySQL

Server 8.0.39 release.

MySQL Router 8.0 Release Notes

Changes in MySQL Router 8.0.38 (2024-07-01, General Availability)

Important

This release is no longer available for download. It was removed due to a

dependency on a version of the server which is also no longer available for

download. See MySQL 8.0.38 Release Notes. Please upgrade to MySQL Router

8.0.39 instead.

Bugs Fixed

• MySQL Router always updates the last_check_in in the Metadata Schema when it starts, even if the

Cluster is INVALIDATED, leading to an errant transaction. As of this release, MySQL Router does not

update last_check_in if the Cluster is INVALIDATED. (Bug #36563430)

• Increased the maximum router_id value from 999999 to 4294967295 (2^32-1). This also affects how

the internal metadata_cache user name is defined. (Bug #36393211)

Changes in MySQL Router 8.0.37 (2024-04-30, General Availability)

Bugs Fixed

• If a hostname was not resolved, due to a DNS failure, MySQL Router did not check if that host became

available again, later. (Bug #36246652)

• MySQL Router's bootstrap process checks the mysql.user table for the unsupported

mysql_native_password authentication plugin. If the bootstrap user had no access to the table, the

following error was returned:

Failed checking the Router account authentication plugin: Error executing MySQL query "select host, plugin from mysql.user where user =

'user'": SELECT command denied to user 'user'@'host'

for table 'user' (1142)

As of this release, this error is not returned. (Bug #36225456)

• The following error was displayed if MySQL Router was closed before the metadata cache started:

Error: routing:_: Metadata Cache not initialized

(Bug #36151125)

• If an incoming port is opened and closed by a TCP connection, such as a load balancer or a service-

monitoring utility performing a health check, the connection counts towards the limit defined by

max_connect_errors, even though the connection was not established. This could lead to MySQL

Router closing the incoming port when the error limit is reached.

As of this release, max_connect_errors is not incremented if the Router's incoming port is opened

and closed without establishing a connection. (Bug #36104070)

• The following error did not provide enough information for troubleshooting:

timestamp routing ERROR [code] connecting to backend failed: Connection timed out (generic:110)

As of this release, it contains the following details:

MySQL Router 8.0 Release Notes

• Route name and client source.

• resolve() errors.

• Hostname, IP addresses, and errors for each connection attempt.

• The amount of time spent on the connection attempt.

(Bug #35503245)

Changes in MySQL Router 8.0.36 (2024-01-16, General Availability)

Bugs Fixed

• It was not possible to build MySQL Router on 32-bit Linux platforms. (Bug #36040942)

• If MySQL Router was bootstrapped over an existing configuration, the existing user's credentials were

retrieved from the keyring and reused, even if the user used the deprecated authentication plugin,

mysql_native_password.

As of this release, MySQL Router checks the user's authentication method and, if it is set to

mysql_native_password, changes it to the Cluster's default if there are no other user@host entries for

the MySQL Router user. If there is more than one such entry, a warning is returned, advising the user to

manually correct the authentication configuration. (Bug #35943415)

• If MySQL Router was bootstrapped against an InnoDB Cluster, without using an existing account or

using the --force-password-verification parameter, the auto-created metadata user was

created using the mysql_native_password plugin. This plugin was deprecated in MySQL Server 8.1

and is subject to removal in a future release.

As of this release, the metadata user is created using the default authorization plugin defined on the

InnoDB Cluster. (Bug #35737357)

• It was not possible to connect to MySQL Router with PHP and an account with an empty password using

a command similar to the following:

php -r 'mysqli_real_connect(mysqli_init(), "127.0.0.1", "empty", "");'

Authentication failed with the following error:

PHP Warning: mysqli_real_connect(): Premature end of data

(mysqlnd_wireprotocol.c:703) in Command line code on line 1

PHP Warning: mysqli_real_connect(): AUTH_RESPONSE packet 1 bytes

shorter than expected in Command line code on line 1

(Bug #35493871)

• If a client aborted a TLS handshake due to a certificate which cannot be verified, the following was

incorrectly logged as an ERROR by MySQL Router:

ERROR ... classic::loop() processor failed:

error:0A000418:SSL routines::tlsv1 alert unknown ca

(tls_err:167773208)

MySQL Router 8.0 Release Notes

As of this release, the connection is closed without a processor failed error and an INFO message

is logged explaining why the TLS handshake failed. (Bug #35443773)

• MySQL Router disconnected all connections to a Cluster if the user added a new instance to an existing

Cluster with only one remaining member. This occurred because the new instance was present in the

Group Replication metadata but not yet in the Cluster's metadata. MySQL Router assumed there was no

quorum and disconnected. It was possible to reconnect after the new instance was represented in the

Cluster's metadata.

As of this release, MySQL Router relies only on the Group Replication metadata for quorum reporting.

(Bug #33989165)

Changes in MySQL Router 8.0.35 (2023-10-25, General Availability)

• Deprecation and Removal Notes

• Functionality Added or Changed

• Bugs Fixed

Deprecation and Removal Notes

• The allow_primary_reads parameter of the destinations URI is now deprecated and subject to

removal in a future version of MySQL Router. Use the PRIMARY_AND_SECONDARY parameter instead.

For example:

[routing:example]

destinations=metadata-cache://cache-name/default?role=PRIMARY_AND_SECONDARY

(WL #15871)

• Metadata Schema v1.x support is now deprecated and subject to removal in a future version of MySQL

Router. Connecting to a Cluster which uses this version now triggers a warning stating that the metadata

version is deprecated and the Cluster metadata should be upgraded. (WL #15876)

Functionality Added or Changed

• MySQL Router now recognizes accounts with empty password sent from PHP over the classic MySQL

protocol. (Bug #35463338)

Bugs Fixed

• Queries larger than 16MB were not properly handled if Connection Sharing was enabled. (Bug

#35769702)

• Unclosed comments, /* without a corresponding closing /*, caused MySQL Router to close

unexpectedly if Connection Sharing was enabled. (Bug #35769610)

• Authentication failed for third-party clients using non-SSL connections, with caching-sha2-password and

the following SSL options configured:

• client_ssl_mode set to PREFERRED or PASSTHROUGH

• server_ssl_mode=AS_CLIENT

MySQL Router 8.0 Release Notes

An error similar to the following was returned:

Couldn't read RSA public key from server

(Bug #35737521)

• MySQL Router closed unexpectedly when attempting to connect to a ClusterSet but only had access to

members without quorum. (Bug #35705590)

• If the directory used for bootstrapping contained a symlink, the keyring's master key could not be

located. An error similar to the following was returned:

Error: Master key for keyring at '/bootstrapPath/data/keyring'

could not be read

(Bug #35630329)

• Under certain circumstances, MySQL Router did not shutdown when closed with SIGTERM or SIGINT. It

was possible for a connection to be in an intermediate state and block the shutdown until that remaining

connection was closed by the user. (Bug #35574557)

• If an invalid client greeting was received, the following message was logged:

loop(): Input too short

This message was not helpful to the user. As of this release, an error message is returned to the client

and no error message is logged if the packet is invalid. (Bug #35523018)

• MySQL Router maintained the router-server connection until the transaction was complete, even when

the client-router connection had closed. This could result in a max-connection error.

As of this release, MySQL Router checks the client-router connection status while waiting for the

transaction response. (Bug #35515899)

• Routing on named sockets did not resume after Cluster recovery. Error 2002 was logged. (Bug

#35503286)

• MySQL Router error log did not contain MySQL Router version information. (Bug #35503191)

• MySQL Router did not reject ambiguous port configuration. For example, if both bind_address and

bind_port were specified with different port numbers. (Bug #34972789)

• Under certain circumstances, on Microsoft Windows platforms, it was not possible to run MySQL Router

as a service. An error message stating the MySQL Router configuration file could not be found was

logged even though the configuration file was present and correct. (Bug #33301070)

Changes in MySQL Router 8.0.34 (2023-07-18, General Availability)

Bugs Fixed

• Deprecated ciphers were removed from the default cipher lists of client_ssl_cipher and

server_ssl_cipher. Triple-DES ciphers and DSS ciphers are no longer permitted. (Bug #35489217)

• MySQL Router failed to start if configured to use ECC certificates. The following error was displayed: no

RSA certificate. (Bug #35317484)

MySQL Router 8.0 Release Notes

• Connections were not shared if the client enabled CLIENT_MULTI_STATEMENTS with

COM_SET_OPTION. (Bug #35263986)

• If USE SCHEMA was sent by query instead of by the dedicated command, connection sharing was

blocked. (Bug #35245250)

• If a client connected to the server through MySQL Router, while a SUPER connection was already

established, and the server's max_connections was reached, the connection was dropped and an

error similar to the following was erroneously returned to the client: Lost connection to MySQL

server during query. This error was also sent twice.

As of this release, the correct error message is returned. (Bug #35239607)

• SHOW WARNINGS did not behave as expected if connection sharing was enabled. It did not return all the

status-flags, such as autocommit. (Bug #35213196)

• Client authentication failed if the client authenticated with a password and a default authentication

method other than caching_sha2_password. The error message included: using password: NO.

(Bug #35195287)

• Connection sharing was disabled if a change-user operation occurred, resetting the user's stored

password. As of this release, if a change-user operation is called, the existing connection is updated with

the new credentials. (Bug #35189721)

• The client's character set was not restored when their connection was restored from the connection pool.

(Bug #35184765)

• Router is now compatible with older metadata, such as metadata created by MySQL Shell 8.0.11. This

allows upgrading from these older versions. (Bug #35078886)

• It was not possible to create an InnoDB Cluster with the latest version of MySQL Router, and MySQL

Server, and an older version of MySQL Shell, such as 8.0.11. MySQL Router failed to start as a result of

a failure to recognize an older version of the metadata view used by MySQL Router. (Bug #35067083)

Changes in MySQL Router 8.0.33 (2023-04-18, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• MySQL Router now reuses SSL connections to the metadata server when reconnecting for metadata

updates. (Bug #35057590)

• Multiple performance improvements were made in connection management, memory management,

and statement processing. (Bug #34964415, Bug #34863113, Bug #34921527, Bug #34977233, Bug

#35006489, Bug #35011055, Bug #35019415)

Bugs Fixed

• Under certain circumstances, if an ENOENT system error was returned while MySQL Router was

establishing connections to a routing destination, the accepting port was closed for that routing

destination, and MySQL Router stopped accepting connections on that port. An error similar to the

following was displayed:

routing ERROR [...] no backend available to connect to

MySQL Router 8.0 Release Notes

routing INFO [...] Stop accepting connections for routing

routing:bootstrap_rw listening on 6446

As of this release, the port is not closed and additional logging is added for such errors. (Bug

#35157953)

• It was not possible to connect to MySQL Router with PHP and an account with an empty password.

Authentication failed with the following error:

AUTH_RESPONSE packet 1 bytes shorter than expected.

(Bug #35125466)

• Under certain circumstances, if connection sharing was enabled and the establishment of a new

connection failed, the resulting server connection was left in an invalid state; the socket was closed, but

the connection was kept alive.

As a result, multiple TLS connection alerts were logged. (Bug #35072554)

• Passwords longer than 20 characters failed authentication through MySQL Router if the client

connection was not encrypted and requested the server key. (Bug #35028666)

• It was not possible to connect with pymysql. An error similar to the following was returned:

pymysql.err.OperationalError: caching sha2: Unknown packet for public key: b'-'

(Bug #35015376)

• The server logs recorded Aborted connection if a pooled connection was idle for longer than the

value of idle_timeout and was closed. (Bug #34983883)

• MySQL Router did not correctly handle requests for compression over unencrypted connections, by

clients such as PHP+PDO and pymysql, for example. An error similar to the following was returned:

Packets out of order. Expected 1 received 5. Packet size=26 in

pdo-compressed.php on line 3

As of this release, MySQL Router returns an appropriate error stating that compression is not supported.

(Bug #34960959)

• Under certain circumstances, on Mac OS, Cluster endpoints were not removed from quarantine, even if

they were valid and it was possible to connect to them. (Bug #34909071)

• Under certain circumstances, MySQL Router did not close gracefully on Solaris, but crashed while

closing. (Bug #34904367)

• MySQL Router did not immediately detect connections to unresponsive ports on Mac OS. As a result,

the connection reported a timeout instead of a failed connection. (Bug #34861635)

• MySQL Router queried the metadata from the first server listed regardless of the role of that server. As

a result, MySQL Router could retrieve metadata from a current secondary, which had been a primary,

instead of the current primary. As of this release, MySQL Router takes the metadata server's current role

into account.

This fix also correct an issue where MySQL Router did not discard configuration metadata relating to

offline cluster members. (Bug #34835509, Bug #34857112)

MySQL Router 8.0 Release Notes

• If an X Protocol client or connector closed a connection, MySQL Router did not respond as expected. As

a result, if the client waited for a response, the connection could remain open and unusable.

(Bug #34428430)

• It was not possible to connect to the server through MySQL Router using older PHP clients if the MySQL

account used caching_sha2_password and MySQL Router was configured to use PASSTHROUGH/

AS_CLIENT or PREFERRED/AS_CLIENT options. (Bug #110161, Bug #35112431)

• Renaming a cluster, using cluster.setOption(), caused routing to fail due to an issue with MySQL

Router configuration. This issue was caused by MySQL Router using the cluster name written to the

MySQL Router configuration file during bootstrapping. The cluster name was then used in queries to the

metadata cache, which failed when the cluster was renamed.

As of this release, the cluster name is not used, the UUID is used instead. That is, Group Replication

UUID for group replication clusters, ClusterSet UUID for ClusterSets, and Cluster UUID for ReplicaSet

clusters. The UUID is written to MySQL Router's JSON state file.

Note

For backward compatibility, the cluster name is still written to the configuration file

and will be used if UUIDs are not available.

(Bug #95010, Bug #29642686)

Changes in MySQL Router 8.0.32 (2023-01-17, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• CPU usage was optimized by reducing the number of system calls per read/write operation. (Bug

#34787879, Bug #34788019)

• A new option, use_replica_primary_as_rw is added to the MySQL Shell option

<ClusterSet>.setRoutingOption().

This option is read by MySQL Router and enables it to open or close a read-write (R/W) port on a router

targeting a specific Cluster (where target_cluster is not set to primary), enabling you to use a R/

W port on a ReplicaCluster. The ReplicaCluster continues to only accept R/O traffic. In the event of a

switchover or failover, the R/W port remains unchanged.

See MySQL Router Status for InnoDB ClusterSet. (WL #15321)

• The following configuration options are added to a new configuration section,

[destination_status], in this release:

• error_quarantine_interval: Defines the interval, in seconds, between checks on quarantined

destination connectivity. If a connection is possible, the destination is moved out of quarantine and

made available for connections.

• error_quarantine_threshold: Defines the threshold of consecutive, failed attempts to connect to

a routing destination before MySQL Router adds the destination to quarantine and stops using it as a

destination until it is cleared by the quarantine mechanism. For example, if set to 5, the destination is

quarantined after 5 consecutive, failed attempts to connect to it.

MySQL Router 8.0 Release Notes

The option unreachable_destination_refresh_interval is deprecated in this release. (WL

#15329)

• Connection sharing is introduced in this release, extending upon the Connection Pool introduced in

MySQL Router 8.0.29.

Enabling connection sharing (connection_sharing) lets you define how long a server connection is

idle (connection_sharing_delay) before it is reset and added to the connection pool, where it can

be reused by another client connection.

See Connection Sharing and Reuse. (WL #12772)

Bugs Fixed

• Connections made over Unix socket were not shared, even though connection sharing was enabled.

(Bug #34806320)

• Configuring MySQL Router with client_ssl_mode=PREFERRED and

server_ssl_mode=AS_CLIENT resulted in an unencrypted connection over Unix socket connections.

(Bug #34801929)

• Connections through MySQL Router were not closed with COM_QUIT, incrementing the server's

Aborted_clients count. (Bug #34801356)

• Under certain circumstances, such as MySQL Router running on an under-resourced server, traffic on

one connection could be unfairly prioritized over other connections. (Bug #34787854)

• Pooled connections were not used if the [io] option threads value was larger than 1. (Bug

#34781248)

• It was not possible to connect to the server over Unix socket, through MySQL Router, with a user

configured to use caching_sha2_password. An error similar to the following was returned:

HY000 (2013) Lost connection to MySQL server at 'reading final

connect information', system error: 95

(Bug #34778017)

• Under certain circumstances, when the MySQL Router was setting up the x-protocol connection, if the

client sent a valid, but unexpected message (unexpected for this phase of the setup process), the router

attempted to forward it to the server, even though the server connection was not yet ready. This caused

the router to close unexpectedly.

As of this release, MySQL Router returns a Bad message error to the client, in response to the out-of-

sequence message. (Bug #34597056)

• If a routing destination was removed from quarantine, reopening the bind_port could fail. If the router

is part of an InnoDB cluster, an attempt is made to reopen it during a metadata cache refresh, but this is

not available to statically-defined bind_port in standalone installations.

As of this release, for standalone router installations, if reopening the bind_port fails, MySQL Router

attempts to reopen it every 1 second. (Bug #34569676)

• Under certain circumstances, if max_connections was configured, attempting to connect to MySQL

Router with X-Protocol resulted in an error, MySQL server has gone away, instead of the expected

message: Too many connections to MySQL Router.

MySQL Router 8.0 Release Notes

This issue only occurred on Microsoft Windows platforms. (Bug #34548367)

• MySQL Router did not close connections if they were closed by the server, but not closed by the client.

The connection persisted indefinitely.

As of this release, MySQL Router closes the client connection when the server connection is closed.

(Bug #34401798)

• If a socket was unexpectedly shutdown on both ends of the connection, but not closed, and the socket

was still monitored by EPOLL_WAIT, EPOLLHUP or EPOLLERR events were returned. Neither event was

handled, leading to a loop and high CPU usage until the socket was closed. (Bug #33674644)

• MySQL Router's logrotate did not send a HUP signal to the router process. As of this release, logrotate

uses native systemctl commands when systemd is enabled. (Bug #108360, Bug #34565239)

• Under certain circumstances, on Microsoft Windows platforms, MySQL Router crashed repeatedly. (Bug

#108228, Bug #34536085)

Changes in MySQL Router 8.0.31 (2022-10-11, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• You can now configure MySQL Router to write a core file in the event the MySQL Router process fails.

See Configuration File Options for information on the --core-file. option. (WL #15185)

• MySQL Router periodically updates the last_check_in of the Cluster metadata schema. Under

certain circumstances, such as a ClusterSet split-brain scenario, these updates can make rejoin

operations impossible due to the creation of errant transactions.

As of this release, MySQL Router checks the value of a new Metadata schema option,

stats_updates_frequency, in the JSON field v2_cs_router_options.router_options, and

updates the check-in behavior based on the value of this option.

If the target Cluster is a member of a ClusterSet, MySQL Router does the following:

• MySQL Router always updates last_check_in when it starts.

• If the value of stats_updates_frequency is a positive integer N, MySQL Router continues

updating last_check_in every N seconds.

• If the value of stats_updates_frequency is zero or missing entirely, MySQL Router does not

update last_check_in.The same is true if the value of stats_updates_frequency is not a valid

positive integer.

If the target Cluster is not a member of a ClusterSet, MySQL Router's behavior is unchanged.

last_check_in is updated every tenth refresh cycle. This cycle is not configurable.

stats_updates_frequency can be updated using the MySQL Shell command,

clusterSet.setRoutingOption(). See MySQL Router Status for InnoDB ClusterSet. (WL #15230)

MySQL Router 8.0 Release Notes

Bugs Fixed

• Connections which were closed by the server were maintained in the connection pool, resulting in an

error if the connection was reused. (Bug #34536576)

• MySQL Router rejected compressed connections with the error error:5000, bad message.

MySQL Router does not currently support compressed connections. As of this release, if a client

requests a compressed connection, MySQL Router replies that it does not support them. The client can

then use an uncompressed connection. (Bug #34445287)

• Under certain circumstances, the unreachable destination quarantine mechanism,

introduced in MySQL Router 8.0.29, could block new, valid connections for the duration of

unreachable_destination_refresh_interval, while there is a quarantined, unavailable

destination. (Bug #34427559)

• Some configuration options were not correctly validated by the configuration checker. For example,

bootstrapping with --name resulted in an error although it is a valid configuration option. (Bug

#34258782)

• Multiple errors were logged if a client application did not send, or did not support, connection attributes.

(Bug #34196750)

• Processing SQL statements of 16MB or larger caused MySQL Router to become unresponsive. (Bug

#107982, Bug #34426322)

• MySQL Router stopped responding when calling a stored procedure with a prepared statement. (Bug

#107951, Bug #34420764)

Changes in MySQL Router 8.0.30 (2022-07-26, General Availability)

Bugs Fixed

• Router would block clients if the server backend was unreachable. (Bug #34218994)

• Added Enterprise Linux 9 (EL9) support. (Bug #34203755)

• Fixed potential deadlock issue with the metadata cache plugin's cache_stop() API function. (Bug

#34135189)

• Upgraded bundled duktape version from 2.6.0 to 2.7.0 (Bug #34089826)

• Added OpenSSL 3 support, which includes using the OpenSSL 3 API instead of the deprecated

OpenSSL 1.x API when compiled with OpenSSL 3. (Bug #34042982)

• Now Router actively cancels the client-side component of a connection if the associated server-side

connection was terminated. (Bug #34038187)

• On Solaris, Router would unexpectedly halt when connect_timeout expired after a successful

connection. (Bug #34021483)

• Router would emit an "option is not supported" error if ssl_* options were defined in the

[metadata_cache] section. (Bug #33996132)

• Updated the X protocol connection code to better handle file related errors, such as "too many open

files" and "no such file or directory" -- this error handling was already present for classic protocol

connections. (Bug #33962604)

MySQL Router 8.0 Release Notes

• On macOS, Router would not shut down (SIGKILL) if a connection to a non-responsive endpoint was

initiated until after the associated connect_timeout expired. The shutdown process is now more

immediate. (Bug #33944074)

• Optimized the ClusterSet metadata refresh mechanism by merging two queries into one. (Bug

#33819386)

Changes in MySQL Router 8.0.29 (2022-04-26, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Added a new unknown_config_option configuration option that defines Router behavior when

encountering an unknown configuration option, such as a typo. Behavior defaults to 'warning' if unset,

and bootstrapping sets it to 'error' in the generated configuration behavior. Previously, Router ignored

unknown configuration options. (Bug #32207191, WL #12771)

• Added connection pooling functionality to reuse server-side connections. This adds the new

max_idle_server_connections (defaults to 0 seconds; so is disabled) and idle_timeout

(defaults to 5 seconds) Router configuration options for the new [connection_pool] configuration

section. Set [rest_connection_pool] to enable its REST API functionality. (WL #12771)

• Changed the connect_timeout default value to 5 seconds. Previously it defaulted to 15 for the

[DEFAULT] section and 1 for the [routing] section. (WL #14978)

• Extended the quarantine mechanism to the first-available and next-available static destination routing

strategies, when previously it only applied to the static round-robin and dynamic metadata-cache

policies. Previously first-available would check for connections but now skips unreachable (quarantined)

destinations. The next-available strategy behavior did not change to preserve backwards compatibility.

This adds a new unreachable_destination_refresh_interval configuration option that

defaults to 1 (second). This determines how often each unreachable destination candidate is probed for

availability. (WL #14663)

Bugs Fixed

• Router would unnecessarily remove and recreate existing connections when new nodes were added to a

Cluster, and this would potentially block the GR notification thread. (Bug #33874978)

• Closing an SSL connection now cancels all events on the server-side socket instead of passively waiting

for it to close. (Bug #33830212)

• The metadata upgrade process (via MySQL Shell's dba.upgradeMetadata()) did not recognize when

Router was upgraded if the system still used the older metadata 1.x (metadata 2.0 was introduced

in v8.0.19); and this stalled the upgrade process. Now Router sets the Router version in metadata

during bootstrap for all metadata versions, and it continues to retry updating the version if it failed due to

missing privileges of the Router user when before it only tried once. (Bug #33825480)

• On Windows MSI builds, added the missing INFO_BIN and INFO_SRC files to the share/doc/

mysqlrouter directory. (Bug #33822549)

References: See also: Bug #33510726.

MySQL Router 8.0 Release Notes

• While bootstrapping, the default section name keys for the metadata_cache and routing sections

changed from the cluster name to "bootstrap" to help prevent potential invalid character clashes. (Bug

#33673803)

• Improved Doxygen support by removing [[maybe_used]] tags and ensuring all parameters are

documented. (Bug #33596116)

• A potential race condition occurred when the routing plugin shut down and cleaned up the sockets

container when the connector tried using this sockets container afterwards. Connections not yet moved

to the routing plugin container are now counted, and the routing plugin cannot shut down until these

connections are handled. (Bug #33593833)

• Split metadata_cache into metadata_cache (library) and metadata_cache_plugin (plugin). (Bug

#33574698)

• Refactored BasePluginConfig by adding transformation classes (StringOption, UintOption,

DoubleOption, and MilliSecondsOption) and converted plugin configurations to get_option(). (Bug

#33570004, Bug #33584470)

• Router now uses metadata to find a PRIMARY rather than rely upon the order of nodes returned by a

node list query. Before it would connect to the first node regardless, even if needing a primary and this

would waste time and yield unnecessary errors if the node was not a primary. (Bug #33551163)

Changes in MySQL Router 8.0.28 (2022-01-18, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Added the --conf-set-option command line option to set a value for any generated configuration

option during bootstrap. For example, setting --conf-set-option=logger.level=debug sets

[logger]level=debug in the generated mysqlrouter.conf. (WL #14706)

• On Windows, the following options now accept a custom service name parameter: --install-

service, --install-service-manual, and --remove-service. The previous and default value

for each of these is MySQLRouter. (WL #14739)

• Added the ability to alter configuration options at runtime via the command line. The

format is --section[:section_key].option_name=option_value; such as --

DEFAULT.plugin_folder=/home/dev/. This new feature does not modify the configuration file as it

only affects the runtime; and it overrides defaults and configured options. (WL #14684)

Bugs Fixed

• On Windows, removed the openssl/*.h includes to allow tls_context.h to include them in the

correct order. This allows Router to build on Windows with OpenSSL 1.0.x. (Bug #33579528, Bug

#105535)

• Two informative text files were added: INFO_BIN contains information about the build environment

used to produce the distribution, and INFO_SRC provides information about the product version and the

source repository from which the distribution was produced.

Update: these files were added to Windows MSI builds in 8.0.29. (Bug #33510726)

MySQL Router 8.0 Release Notes

• Fixed error reporting related to metadata-cache's role definition for its destination URL. Rather than

report "Invalid server role in metadata cache routing" it's now more specific and references the allowed

role values, which are PRIMARY, SECONDARY, and PRIMARY_AND_SECONDARY. (Bug #33444102)

• With logging_folder set, Router would always output "logging facility initialized, switching logging to

loggers specified in configuration" to the console; now this message is only displayed if previous console

output was detected. (Bug #33327741)

• Router could continue using a former Primary Cluster for periodic metadata updates despite it being an

invalidated target_cluster. (Bug #33300235)

• Router incorrectly accepted non-numeric values for numeric options. For example, 'a' was interpreted as

'0'. They are now rejected. (Bug #32248283)

Changes in MySQL Router 8.0.27 (2021-10-19, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Added a new max_total_connections option that defines the maximum number of connections

allowed by all Router destinations combined.

The existing max_connections option still functions and allows setting the maximum number of

connections per specific routing destination. (WL #14319)

• Added support for InnoDB ClusterSet topology and failover. This adds two new bootstrap command line

configuration options that define the target_cluster metadata option at bootstrap: --conf-target-

cluster (configure by cluster type) and --conf-target-cluster-by-name (configure using a

static cluster name).

The following ClusterSet values are added to Router's state file:

• clusterset-id: ID of the ClusterSet Router was bootstrapped against.

• metadata-servers: Set of all known ClusterSet metadata servers. Typically all nodes of all clusters

in the ClusterSet.

• view-id: ID of the last known view of the metadata.

InnoDB ClusterSet support requires the cluster_type option set to gr. (WL #12797)

Bugs Fixed

• Now accept Client::Greeting messages that announce PLUGIN_AUTH but don't send a plugin name; this

to be more flexible with the spec, like MySQL Server is. (Bug #33357723)

• Bootstrapping on systems with the older metadata version 1.0 now sets backend=file as metadata 1.0

does not support http_auth_backend. (Bug #33308536)

• Support for the following compilers was removed: Sun Studio, C++11, and C++14. (Bug #33307865, Bug

#33306219, Bug #33302907)

• Receiving an empty xproto packet would cause Router to unexpectedly halt. (Bug #33240637)

MySQL Router 8.0 Release Notes

• Updated error logs:

Max total active connections errors now reference the associated max_total_connections parameter

name.

A failed connection reported "generic:1, operation not permitted." instead of "connection refused". (Bug

#33051998, Bug #33059504)

• The Linux epoll IO service dropped events when multiple events fired at the same time. (Bug

#32998738)

• Improved HTTP authentication efficiency by caching credentials per connection. (Bug #32981242)

• Defining a Router configuration option using an unsupported value would emit the associated error three

times instead of once. (Bug #32949289)

• On Windows, the server_ssl_capath or server_ssl_crlpath Router configuration options did not function,

and defining them caused Router to not start. (Bug #32859961)

• Router would repeat error or warning messages every TTL when failing to refresh the metadata thus

filling up the logs. Now the log level is lowered (usually to level debug) if a given event had already been

reported. (Bug #32423845)

Changes in MySQL Router 8.0.26 (2021-07-20, General Availability)

• Deprecation and Removal Notes

• Bugs Fixed

Deprecation and Removal Notes

• The TLSv1.0 and TLSv1.1 connection protocols now are deprecated and support for them is subject to

removal in a future MySQL Router version. (WL #14582)

Bugs Fixed

• On Ubuntu with AppArmor enabled, AppArmor generated apparmor="DENIED" errors for paths /

usr/share/mysql-8.0/charsets/Index.xml and /etc/ssl/openssl.cnf. The bundled

AppArmor profile was updated to include the charset directory, and also changed openssl.conf to

openssl.cnf. (Bug #32939333)

• Reduced the CPU load consumed by HTTP Server processes by eliminating their excessive callbacks.

(Bug #32715238)

• Added a POD type and codec for client:Kill. (Bug #32672117)

• Recovering nodes that are not in the metadata (and only reported by Group Replication) are no longer

included in the quorum calculation (do not increase the required pool). This fixes a cloning scenario:

cloning causes the node to first appear in the Group Replication table, and adds it to metadata only after

the clone operation is complete. (Bug #32522398)

• Router unconditionally removed the pid_file on exit, even when the file already existed at startup and/or

was write protected. Now it is only removed if created by this invocation of Router. (Bug #32247493)

• Improved log messages for Router plugins, namely to debug plugin-related problems. (Bug #31584192)

MySQL Router 8.0 Release Notes

Changes in MySQL Router 8.0.25 (2021-05-11, General Availability)

This release contains no functional changes and is published to align the version number with the MySQL

Server 8.0.25 release.

Changes in MySQL Router 8.0.24 (2021-04-20, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Changed the default ports used by Router, and default behavior depends on the --conf-base-port

bootstrap option.

If --conf-base-port is not set, then the associated bind_port values begin at 6446; Classic (RW

6446, RO 6447) and X Protocol (RW 6448, RO 6449). Additionally, now setting --conf-base-port to

0 uses the old default ports of Classic (RW 6446, RO 6447) and X Protocol (RW 64460, RO 64470).

Reason: the previous default X Protocol ports (64460 and 64470) are defined as "Dynamic Ports" as per

RFC 6335. (WL #14327)

• Previously, Router bound the incoming socket at startup and kept it open even if no destinations were

available. Now Router only binds to the socket if destinations are available, and otherwise closes the

incoming sockets. This also means Load-Balancers know whether Router can handle traffic. (WL

#13327)

Bugs Fixed

• The mysqlrouter.conf file in Debian Router packages did not set the run directory to an absolute

path name, resulting in package installation errors. (Bug #32620788)

• Disabled code-cache when compiling on Solaris to avoid 'invalid bytecode' errors; previously it was only

disabled for sun-cc builds. (Bug #32567899)

• When using first-available policy and static routing, it was possible that the router wouldn't start and

emit an error similar to "plugin 'routing:test_default' start failed: routing:test_default: Failed setting up

TCP service"; fixed race condition on start-up between 'is running' and 'start socket acceptor'. (Bug

#32565479)

• Fixed assertion that a previous destination list contained primary destinations after connecting to a

primary node failed. This assertion was firing because the primary destinations were not properly

recognized during refresh. (Bug #32543464)

• Network transfers larger than the socket send buffer, such as large result sets or queries, could

terminate the connection. (Bug #32543049)

• Now return an std::errc::operation_would_block error code if write() blocks and no data is written; before

0 was returned. (Bug #32542170)

• Configuring a second Router instance on the same machine without the --name parameter would yield

unexpected errors related to file cleanup. (Bug #32517802)

• Router would report as READY before the sockets were open; so now reports it after the socket

acceptors are set up. (Bug #32429409)

MySQL Router 8.0 Release Notes

• Network loss before connect() was resulting in long failover times as it depended on the operating

system's network timeouts. The connect_timeout option was not honored, but is now applied before

connecting. (Bug #32428113)

• Router no longer relies upon the MySQL instance's availability logic for wait-primary-failover. Instead,

it now checks the metadata-cache's replicaset info for a new Primary. This is because GR membership

does not change is the network between Router and the Primary is lost. (Bug #32393421)

• After a network loss between Router and a group replication PRIMARY (but not network loss between

group replication members), the wait for the failover by Router did not timeout after 10 seconds, and

instead the connection remained locked. (Bug #32338771)

• Configuration options expecting numeric values would allow hex and octal values; but now only

completely numeric values are allowed. For example, --config-base-port=0xff now reports an

error. (Bug #32297657)

• Improved the DEBUG logging mechanism to include the following information: host:port, execution time,

OK/ERR information, and row count. In addition, now log one message instead of separate before/after

messages. (Bug #32293818)

• The REST endpoint timeout check changed from waiting for "timeout + request time" to waiting until the

timeout expires. (Bug #32252500)

• Connector/ODBC report ENUM columns as SQL_CHAR as the ODBC standard does not support

ENUM, and MS SQL Server expects CHAR data to always be the same fixed length as specified in the

column definition. This fixes errors related to new line and tab symbols present in the UNICODE version

of the driver. The workaround is to enable SSPS (default) by not setting NO_SSPS=1. (Bug #28783266,

Bug #92748)

References: See also: Bug #32537000.

Changes in MySQL Router 8.0.23 (2021-01-18, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Added configurable server<->router<->client TLS endpoint support, which allows additional configuration

for Router, Client, and Server interactions.

The default behavior changed from client_ssl_mode = PASSTHROUGH to client_ssl_mode =

PREFERRED where PASSTHROUGH forwards everything to the server and lets the client and server

decide TLS settings, whereas PREFERRED establishes TLS connections between the client and Router

if the client desires switching to TLS if the server supports TLS. This also matches the existing behavior

for client and server without the Router in-between.

Many new options were created, such as client_ssl_mode and server_ssl_mode that are

documented under TLS Configuration. (Bug #31141095, WL #12012)

Bugs Fixed

• On Linux, bootstrap would not function if the host had no external interfaces. (Bug #32200253)

• Host names resolving to IPv6 were wrapped in square brackets as it assumed the host name was an

IPv6 address. (Bug #32198746)

MySQL Router 8.0 Release Notes

• Refactored MySQLSession functionality to more consistently report syntax related errors. (Bug

#32151782)

• Large SQL statements that were larger than the send buffer would lead errors such as "write error:

Resource temporarily unavailable" and drop the connection. (Bug #32081158)

• Queries expected to return a single row were not being added to the debugging SQL log. (Bug

#32071807)

• Setting the --conf-use-gr-notifications bootstrap option increased the ttl value to a value

higher than the default auth_cache_refresh_interval value allowed thus not creating a valid

MySQL Router configuration file. Now, setting --conf-use-gr-notifications also adjusts the

auth_cache_refresh_interval value accordingly. (Bug #32062483)

Changes in MySQL Router 8.0.22 (2020-10-19, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Improved building mechanism by implementing CMake's GenerateExportHeader() functionality for the

MySQL Protocol library; which previously was hard coded. (Bug #31503429)

• The strict 1:1 thread-to-connection ratio was replaced by an event-driven + IO-threadpool design.

Instead of running blocking socket operations in a thread, non-blocking IO is now used and a thread may

be used when a socket is available. This raises the concurrent connection limit by a Router instance

from around 5,000 to around 50,000.

This also adds a new [io] configuration section with two new configuration options: backend that handles

async operations (accepts poll or linux_epoll) and threads as the number of IO threads to handles

connections (0 for all available, or 1-1024). (WL #10703)

• The bootstrap process now configures REST API functionality into the generated mysqlrouter.conf

configuration file. The new optional --https-port bootstrap argument defines port; which is defined

as 8443 by default.

To disable the REST API configuration from being generated, pass in the new --disable-rest

bootstrap option. (WL #13906)

• Added systemd notify support. If there is a NOTIFY_SOCKET environment variable set when the Router

starts, Router treats its value as unix-domain socket name; DGRAM on all unix-based operating systems

and as a named pipe path on Windows. (WL #13707)

Bugs Fixed

• When using the recently introduced _hidden instance feature, hiding secondary instances with

_disconnect_existing_sessions_when_hidden enabled would close all secondary instances rather than

only hidden instances. This issue only applied when using host names instead of IP addresses. (Bug

#31665764)

• Refactored acceptor-shutdown synchronization to avoid possible hangs. (Bug #31598112)

• Improved Router's metadata cache refresh mechanism to account for race conditions; such as a refresh

request made while the metadata is currently refreshing. (Bug #31597874)

MySQL Router 8.0 Release Notes

• Improved the round-robin routing strategy quarantine check mechanism. (Bug #31575084)

• Added support for the net_buffer_length routing option. Previously it was accepted but ignored in favor of

the default value. (Bug #31575027)

• Added link-local IPv6 address support. Previously values containing a '%' sign failed with an 'invalid

address' error. (Bug #31574975)

• Replaced all occurrences of 'master' in the context of the node role with 'primary'. (Bug #31508256)

• On Windows, added socket write support to emulate it by adding an AF_INET variant of socketpair().

(Bug #31414156)

• When Router loses the primary it waits for the failover with a 10 second timeout. Previously it did not

check for terminate requests, so could take up to 10 seconds if the new primary was not found until

Router honored the shutdown request. (Bug #31397127)

• Hostname detection resolved IP addresses of external network interfaces using code specific to Linux

that operated directly with c-style type cases. Improved portability using type safe network-address types

from net::ip::tcp::address and ::network thus making it portable for Windows, Solaris, FreebBSD, and

macOS. (Bug #31370876)

Changes in MySQL Router 8.0.21 (2020-07-13, General Availability)

• Packaging Notes

• Functionality Added or Changed

• Bugs Fixed

Packaging Notes

• For Windows, MSI installer packages for MySQL Router now include a check for the required Visual

Studio redistributable package, and produce a message asking the user to install it if it is missing. (Bug

#30541398)

Functionality Added or Changed

• Added new log functionality:

• [filelog]: this new section includes the optional filename option that defaults to [logger]'s

filename value. This file is written to the logging_folder directory; and the value must be a file

name and not include a path.

• [logger]: added an optional filename option to define Router's log file name, and it also sets

[filelog]'s default filename value. It is unset by default, while default filename behavior is Router's

mysqlrouter.log.

• [consolelog]: this new section includes the optional destination option that defaults to /dev/

stderr. Available values are /dev/stdout, /dev/stderr, or /dev/null on *nix; and CON or NUL

on Windows.

(Bug #29271072, Bug #94095, WL #13838)

• Added support for the InnoDB cluster metadata "tags" property; namely for the "_hidden" and

"_disconnect_existing_sessions_when_hidden" tags.

MySQL Router 8.0 Release Notes

• _hidden: A boolean that indicates if the node should be hidden. Setting "true" makes the node

hidden, while "false" or any other value considers it not hidden. Default: false.

• _disconnect_existing_sessions_when_hidden: A boolean that indicates if the existing

connections to the node should be dropped in case the node is hidden. A value of "false" means

the node is "dont_disconnect_existing", meaning existing connections to hidden nodes are not

disconnected. True or any other value means the opposite. Default: true.

This setting does not affect new client connections, which are never directed to hidden instances.

Hidden instances only affect user connections; the instance remains available to Router when

performing tasks such as fetching metadata and calculating the quorum. (WL #13787)

Bugs Fixed

• Updated mock_server MySQL Server type definitions; fixed NEWDECIMAL and added TIMESTAMP2

and JSON. (Bug #31283079, Bug #99416)

• For testing, the full protobuf dependency was replaced by protobuf-lite. (Bug #31245124)

• For Windows, added necessary internal functions to allow log rotation but it remains unsupported. This

functionality is only available on Unix-based systems. (Bug #31212570, Bug #33708504)

• The bootstrap process could not complete when MySQL Server had the optimizer switch derived_merge

set to off; because the v2_routers view became non-insertable. Now, derived_merge is set to on for

sessions that Router is handling metadata. (Bug #31170721)

• Improved the plugin loading mechanism to not implicitly load plugins; previously the same plugin could

be loaded twice. (Bug #31024867)

• Router assumed that each new GR change notified by X Protocol notifications has a new view id, but

that is not always the case; for example, for changes like switching the primary or change of the role.

The view id is no longer used for notification debouncing. (Bug #31017863, Bug #98863)

• Fixed MSVC 2019 16.6 builds by adding the missing headers. Thanks to Billy O'Neal for the patch. (Bug

#31008906, Bug #98880)

• Fixed Clang 9 warnings. (Bug #30920954)

• With use_gr_notifications=1, Router used the old X Protocol namespace name (xplugin) when sending

the PING message over the X Protocol connection that was sent to avoid the idle connection from being

closed. (Bug #30850734)

• With a high TTL and Group Replication (GR) notifications enabled, MySQL Shell operations such as

addInstance() and removeInstance() would go unnoticed until the TTL expired; which would trigger GR

notifications in the meantime. Now Router temporarily decreases TTL to 1s when it notices inconsistent

metadata until it becomes consistent again. (Bug #30739068)

• On Linux, Router now installs an example logrotate example script; it's located at /etc/logrotate.d/

mysqlrouter. (Bug #30611485)

• Updated HTTP server logic to function with changes made by libevent 2.1.9. (WL #10703)

Changes in MySQL Router 8.0.20 (2020-04-27, General Availability)

• Functionality Added or Changed

MySQL Router 8.0 Release Notes

• Bugs Fixed

Functionality Added or Changed

• Added additional functionality to configure the PID file location. This adds the --pid-file (command-

line) and pid_file (configuration file) options. Setting the ROUTER_PID environment variable remains

as the other option.

The PID file cannot be set while executing the --bootstrap option. (Bug #30510827, WL #13705)

• Added metadata_cache support for [http_auth_backend]; set backend=metadata_cache to use

it. Also added the optional auth_cache_refresh_interval and auth_cache_ttl options to

configure its use. (WL #12952)

• Added two new log levels: "system", which is higher than "error", and "note", which is between "info" and

"debug". (WL #11196)

Bugs Fixed

• Router's default data directory on Debian (/var/run/mysqlrouter) was not preserved between

system resets. Both the keyring and state.json files were stored here, so Router could not function

after a system reset. Now /var/lib/mysqlrouter is used instead. In addition, the installation

process now detects and moves an existing configuration file to the new location. (Bug #31029334, Bug

#98914)

• Routing failed for an InnoDB Cluster using metadata 2.0 (Shell 8.0.19+) when the primary was removed

using Shell/AdminAPI cluster.remove_instance(). Routing failed because Router flushed the routing table

as a precaution. (Bug #30733189)

• Added missing raise statement when queue is full. Thanks to Rastislav Masaryk for the patch. (Bug

#30643277, Bug #97938)

• Internal metadata queries were affected by global MySQL Server settings; but now Router explicitly

sets session parameters to make metadata queries and updates consistent. These settings are

group_replication_consistency, autocommit, sql_mode, character_set_client, character_set_results, and

character_set_connection. (Bug #30631442, Bug #97764)

• Router renamed its main thread from "mysqlrouter" to "main" to make debugging easier, but this meant

executing "killall mysqlrouter" would not find the process; and instead "killall main" did. The process is no

longer renamed. (Bug #30611421)

• Reviewed help text and error messages throughout MySQL Router's interface; and improved readability.

(Bug #30523166, Bug #30889974, Bug #29138501, Bug #29132761, Bug #30895659, Bug #29428293,

Bug #29132728, Bug #29361447)

• Group Replication notifications (use_gr_notifications) would log warnings about a missing

mysqlx_wait_timeout MySQL system variable when used against MySQL 5.7 as this variable was

added in MySQL 8.0. This warning is no longer present. (Bug #30478016, Bug #97414)

• With AppArmor active (Ubuntu/Debian), bootstrap failed as it could not write a temporary (state) file

as Router's AppArmor profile didn't allow writing to (var)/run/mysqlrouter. The AppArmor profile was

updated accordingly.

With AppArmor active (Ubuntu/Debian), Router ignored the global SSL configuration; the AppArmor

profile was updated to read /etc/ssl/openssl.conf. (Bug #30339399)

• The MySQL Router configuration file required a trailing newline. (Bug #28970487)

MySQL Router 8.0 Release Notes

• Improved error reporting when handling dissolved clusters. For example, the error text "The provided

server contains an unsupported InnoDB cluster metadata." was changed to "Expected the metadata

server to contain configuration for one cluster, found none." (Bug #28365867)

Changes in MySQL Router 8.0.19 (2020-01-13, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Router now utilizes metadata version 2.0 whereas all previous Router versions used metadata v1.0.1;

and Router is backwards compatible with metadata v1.0.1. The Router bootstrapping error log was

updated to reflect this requirement, in that MySQL Shell's dba.upgradeMetadata() exists to perform

a metadata upgrade. (Bug #30381549, WL #13188)

• Added Async ReplicaSet Cluster support.

Added a new cluster_type configuration option to the [metadata_cache] section. Accepted values

are "ar" (Async ReplicaSet) or "gr" (Group Replication). Bootstrapping checks the target instance type

and sets this value accordingly. (WL #13188)

• Added new --account and --account-create options to configure Router's bootstrap user. (WL

#13177)

• Metadata version checking functionality was added. Versions checked include 0.0.0 (a metadata

upgrade is in process), 1.x.x (old metadata version), and 2.x.x (current metadata version). The metadata

version is saved to Router's new routers.version field. In addition, the running router periodically updates

the routers.last_check_in metadata field with the current timestamp. (WL #13417)

Bugs Fixed

• Fixed gcc 5.5 compilation warnings. (Bug #30505196, Bug #97475)

• On Windows, when the Windows service created the Router log file (which happens when running router

as a service by bootstrap), the log file became unreadable (inaccessible) by anyone else; including the

local administrator. The workaround was to manually delete and recreate the log file after installation.

Related, the --install-service parameter attempted to grant r/w rights to an existing log file and

failed if it lacked rights to do so. Now it no longer attempts modifying privileges and instead reports an

error if LocalService lacks sufficient access. (Bug #30471498, Bug #30916395, Bug #97389)

• The Router's table was extended to include the username that accesses the metadata. (Bug #30435133)

• Improved GCC 5.5.0 support as it does not support constexpr. (Bug #30406328)

• An implicit move-assign generated an error when built with DevStudio 12.6; making it explicit eliminated

the error. (Bug #30396902)

• Fixed IPv6 metadata handling. (Bug #30354273)

• Building Router with AddressSanitizer (ASan) now uses ASAN's crash handler on all systems, when

before it would use a generic crash handler on POSIX systems. (Bug #30298740)

• The HTTP REST API bind_address configuration option only accepted IPv4 addresses. (Bug

#30287987)

MySQL Router 8.0 Release Notes

• The bootstrap process would improperly display text related to a successful setup before showing an

error for failing to generate a Router configuration file. (Bug #30055358)

• The bootstrap process did not properly store the configured access ports. (Bug #29969566)

• On shut down, Router now removes the pid-file it generated during start up. (Bug #29441087)

• The source tarball inside SRPM (Source RPM) is now identical to source tarball at the upstream

locations (dev.mysql.com/cdn.mysql.com); previously there were differences causing different checksum

values. (Bug #17760647, Bug #70847)

Changes in MySQL Router 8.0.18 (2019-10-14, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Added a timestamp_precision logger configuration option to configure logged timestamps. (WL

#11194)

• Added a new mysqlrouter_keyring utility to help view and manage the Router keyring. (WL #12974)

Bugs Fixed

• On Windows, ProcessLauncher-related error handling was improved. (Bug #30188010)

• Fixed the command line parser to better ensure that arguments are sent with proper quoting and

escaping. (Bug #30171528)

• Improved SQL quoting by the bootstrap process, which previously did not quote the username in

queries. (Bug #30123992)

• On MacOS, Router failed to start after a successful bootstrap because the loader could not locate the

SSL libraries. (Bug #30096843)

• Simplified and removed unnecessary SQL statements related to cluster metadata queries. (Bug

#30042526)

• Executing python2.7 setup.py install failed to create the mysqlx folder for commercial portable

packages. (Bug #29959309)

• SIGTRAP is now handled the same way as SIGINT in normal operations, and SIGTRAP allows

debugger (such as gdb) to jump in. (Bug #29843245)

• The internal REST API add path functionality did not always remove the current path first, which could

cause an unexpected halt. (Bug #29833031)

• Router could halt unexpectedly if unable to spawn another thread. (Bug #29759391)

• On Windows 10, Router built with -DINSTALL_LAYOUT=WIN would create a directory named

"ENV{APPDATA}" during bootstrap. (Bug #29160784)

Changes in MySQL Router 8.0.17 (2019-07-22, General Availability)

• Functionality Added or Changed

MySQL Router 8.0 Release Notes

• Bugs Fixed

Functionality Added or Changed

• Added the use_gr_notifications [metadata-cache] option to enable Group Replication notifications,

which is disabled by default. It supports group_replication/membership/quorum_loss, group_replication/

membership/view, group_replication/status/role_change, and group_replication/status/state_change.

Optionally use the new --conf-use-gr-notifications bootstrap command-line to enable this

option in the generated configuration file. (WL #10719)

• Added a REST API that follows the OpenAPI 2.0 specification and is implemented as a plugin; load

the plugin using [rest_api] in the configuration file. It also requires the http_server plugin. Use the

optional require_realm configuration option (string) to define the authentication realm.

The base-path for all REST endpoints is "api" followed by a numeric API version that is defined as the

release date, such as "/api/20190715/". The system follows camelCase naming rules and errors follow

RFC 7807. The system exposes a swagger.json file as /api/ {apiVersion}/swagger.json.

(WL #8965)

Bugs Fixed

• Bootstrapping could misclassify a hostname as IPv6 and surround it with square brackets in the state

(state.json) file; and this produced a "Configuration error: cluster-metadata-servers is incorrect" error.

A workaround was to disable ipv6 support on the system. (Bug #29876948, Bug #95531)

• Starting the http_server plugin against a port that was already bound would yield a confusing error, such

as "Error: bind('0.0.0.0:10100) failed: The operation completed successfully." (Bug #29823472)

• Improved the connection counter logic to prevent a potential unexpected halt before completing the

shutdown process. (Bug #29820725)

• Requesting the metadata-cache health immediately after start up could cause an expected exit by

get_destinations() if metadata_cache's cache-api was not yet initialized. (Bug #29820155)

• Bootstrapping would fail on hosts that defined multiple network interfaces. (Bug #29814629)

• Optimized logging mechanism; system generated log messages independent of the log level. Now log

messages are only prepared if configured to do so. (Bug #29798420)

• Fixed potential blocking during shutdown by adding proper libmysqlclient deinitialization where needed.

This bug only affected DEBUG builds. (Bug #29635378)

• harness/CMakeLists.txt was renamed to harness/src/CMakeLists.txt. (Bug #29629788)

• The loaded plugin message level was changed from level "info" to "debug". (Bug #29616101)

• The bootstrap "invalid URI" error message was improved. (Bug #29609170)

• HTTPS connections with ECDHE ciphers to Router's http_server component failed if built against

OpenSSL 1.0.1. (Bug #29609052)

• The file generated by mysqlrouter_passwd was world-readable, and is now user-readable (Bug

#29589127)

• For the REST API, unsupported query parameters now return the 400 HTTP status code; and remain

ignored. (Bug #29556935)

MySQL Router 8.0 Release Notes

• Log lines above 512 characters were truncated. (Bug #29540910)

• For the REST API, OPTION, TRACE, and CONNECT requests now return the application/problem+json

Content-Type and 405 HTTP status code. (Bug #29539557)

• The HTTP server component now supports .jpg/.jpeg image files, and file extension matches are now

case-insensitive. (Bug #29508595)

• Added Visual Studio 2019 support. (Bug #29454252)

• An unknown [http_auth_realm] backend yielded an unclear error. (Bug #29421759)

• An uncaught exception was generated if a client socket was shutdown the client peer address was

retrieved. (Bug #29382585)

• Misleading "Potential changes detected in cluster" warnings were added to Router's log file. Node order

differences no longer cause these errors. (Bug #29264764, Bug #94060)

• Router would start if bootstrap_server_addresses was empty or not set. Now Router fails to start

in this case if cluster-metadata-servers (a dynamic-config attribute) is also empty. (Bug #28352482)

• The .ini configuration file locations are now detected and displayed in --help output. (Bug #28261802)

• With Debian packages, the bootstrap process could fail when used with the --directory option. (Bug

#27034449)

Changes in MySQL Router 8.0.16 (2019-04-25, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• Bootstrapping now sets new routing_strategy values in the generated configuration file. Read-

Write (PRIMARY) sections set routing_strategy to first-available; and Read-Only (SECONDARY)

sections set it to round-robin-with-fallback. Previously, they were both set to round-robin.

The default behavior (for example, if routing_strategy is not defined in mysqlrouter.conf) did not

change and is still round-robin. (Bug #28636013, WL #12089)

• Before, bootstrapping would generate Read-Write (PRIMARY) and Read-Only (SECONDARY)

configuration routing sections for multi-master mode, but only Read-Write sections for single-master

mode. Now, both Read-Write and Read-Only sections are always generated. (WL #12089)

• Added ability to integrate external log-rotation applications by reopening the file-based logfile on

SIGHUP. On Linux, this allows integrating the system-wide logrotate utility. (WL #8988)

• On Windows, added the ability to report events to the Windows Application Events log. (WL #9552)

• Added a new sinks configuration file option to define one or more logger sinks. For example, all

level=debug messages can be sent to a file while only level=error are sent to an eventlog.

The supported sinks are: consolelog, filelog, eventlog on Windows, and syslog on Unix-based systems.

(WL #12733)

• An HTTP interface was added based on libevent's HTTP library. It's configured using a new [http_server]

configuration section that contains the following options:

MySQL Router 8.0 Release Notes

• port: The TCP port listening for HTTP requests; it defaults to 8011.

• bind_address: IPv4 address bound to the port; it defaults to 0.0.0.0.

• static_folder: Base directory for static file requests; it's empty by default. An empty value means

no static files are served.

• require_realm: Name of the [http_auth_realm] instance.

• ssl: The value 1 enables SSL, and 0 disables it. TLS clients supporting TLSv1.2 or later are required.

• ssl_cert: File name of the certificate and its chain certifications in PEM format; required if ssl=1.

• ssl_key: File name of the key in PEM format; required if ssl=1.

• ssl_cipher: The cipher-spec (see openssl's 'ciphers' list). Defaults to a comma-separated list of all

approved ciphers. Unknown ciphers are silently ignored. Fails if list of ciphers is empty and ssl=1.

• ssl_dh_param: Read the DH parameter from this file in PEM format. Uses the dh-param from RFC

5114 by default if ssl=1.

(WL #11891, WL #12503, WL #12524)

• A mysqlrouter_passwd tool was added to manage password's for the HTTP server component.

Two new HTTP configuration sections were added; [http_auth_backend] and

[http_auth_realm]. Both are optional, and multiple definitions are allowed. There options are:

[http_auth_backend]

• backend: Name of the backend implementation; it defaults to file.

• filename: Name of the backend storage file, relative to the data_folder directory.

[http_auth_realm]

• backend: Name of the [http_auth_backend] section.

• method: The HTTP authentication method; defaults to basic.

• require: Requires that the user validates with the authentication backend; defaults to valid-user,

which enables this check.

• name: Name of the realm presented to the authentication user.

(WL #12503)

• Colored text differentiation was added to MySQL Router's console output using the VT100 standard. (WL

#12598, WL #12604)

Bugs Fixed

• AppArmor is now given read/write access to /var/lib/mysqlrouter/ rather than specific files within

to allow additional dynamically generated files there. (Bug #29341853, Bug #94282)

• On Windows, building on a case-sensitive file system would not find the file named MSG000001.bin.

(Bug #29278749)

MySQL Router 8.0 Release Notes

• It was not possible to re-boostrap Router while it was running. Instead, stopping the service beforehand

was required. (Bug #29271620, Bug #94015)

• The cached metadata information (state.json) would cache an empty list if all MySQL servers were

shut down; and this caused restarting MySQL Router to fail. An empty list is no longer cached. (Bug

#29264755, Bug #94057)

• On Debian, apt-get purge and dpkg --purge now remove the /var/lib/mysqlrouter and /

run/mysqlrouter directories. (Bug #29171561)

• Installing from a .deb package would create an empty (and unused) log file named mysqlrouter.log

in the / directory. (Bug #29170728)

• Added Clang 7 support for Windows, and fixed Clang 8 warnings. (Bug #29003649, Bug #29015491)

• The dynamic configuration file created during the bootstrap process was assigned the same permissions

as the static configuration file, which is read-only. This meant that Router could not run as a service on

Windows. The Windows Local Service user can now write to the file. (Bug #28930180)

• When running on Windows as a service, Router now reports errors to the Windows Eventlog that are

encountered before the Router process opens the log file. Before they were sent to the non-existent

console, so the messages were lost. (Bug #28261178)

Changes in MySQL Router 8.0.15 (2019-02-01, General Availability)

This release contains no functional changes and is published to align version number with the MySQL

Server 8.0.15 release.

Changes in MySQL Router 8.0.14 (2019-01-21, General Availability)

• Deprecation and Removal Notes

• Functionality Added or Changed

• Bugs Fixed

Deprecation and Removal Notes

• The bootstrap_server_addresses configuration option is deprecated in favor of the new

dynamic_config option. (Bug #28082857, Bug #91029, WL #11318)

Functionality Added or Changed

• A new dynamic configuration bootstrap feature was added that tracks the current MySQL InnoDB Cluster

Metadata servers. This replaces the existing bootstrap_server_addresses option with the new

dynamic_config option in mysqlrouter.conf.

MySQL Router now tracks and stores active MySQL InnoDB Cluster Metadata server addresses and

loads them if Router is restarted. Previously, metadata server information was defined during Router's

initial bootstrap operation and stored statically as bootstrap_server_addresses in the configuration

file.

This new dynamic_config option is generated by --bootstrap and is defined under

mysqlrouter.conf's [DEFAULT] section. Its value points to a generated JSON file named

state.json that's initialized with InnoDB Cluster Metadata server addresses and the group replication

ID; and additional information is added and updated while Router is running.

MySQL Router 8.0 Release Notes

The bootstrap process no longer defines bootstrap_server_addresses because

dynamic_config replaces its functionality; and these two options cannot be set at the same time. For

backwards compatibility, if only bootstrap_server_addresses is set then it functions as it did in

previous Router versions and this new dynamic configuration functionality is not used. (Bug #28082857,

Bug #27015184, Bug #91029, WL #11318)

• MySQL Router now persistently tracks the metadata server addresses rather than only using the static

list defined in the configuration file using the destinations option. (WL #11318)

Bugs Fixed

• The standalone MySQL Router zip file did not include its own copy of the OpenSSL libraries, so the

Router binary would not start unless the MySQL Server zip file was also installed on the host. (Bug

#29132062)

• The copyright years in the README and LICENSE files were not synced. (Bug #29045945)

• The --version output was aligned with MySQL Server's layout. (Bug #28899194)

• Router would unexpectedly halt upon receiving an unexpected packet; now an exception is thrown. (Bug

#28793334)

• Solaris MySQL Router packages would not function with MySQL Server 8.0.13 due to an incorrect

CMake rpath value. (Bug #28730189)

• Linking Router against libmsyqlclient that was built with DBUG enabled led to slow Router shutdown

procedures. (Bug #28656618)

• Fixed a thread shutdown race condition. (Bug #28610484)

• Sending mysqlrouter a SIGTERM would take at least 100ms to shut down. Now a concurrent plugin

shutdown queue was added to speed up the shutdown process. (Bug #28570122)

• A metadata-cache API method was added to check the initialization status. Routing plugins use this

during initialization to safely register the callbacks after metadata-cache is initialized. (Bug #28569717)

• Installing MySQL Server with Router from source or building a tarball with "make package" would create

a top level "data/" directory as part of the "Router" component. Due to possible collisions with MySQL

Server, "data/" was changed to "var/lib/mysqlrouter". (Bug #28537733)

• The connection error counter that blocks clients after max_connect_errors connection errors did not

reset after a successful connection. (Bug #27995042, Bug #90809)

• The MySQL metadata server's connect_timeout default value changed from 30 to 15 seconds. (Bug

#27326466)

Changes in MySQL Router 8.0.13 (2018-10-22, General Availability)

• Functionality Added or Changed

• Bugs Fixed

Functionality Added or Changed

• To align package names with MySQL Server, the community package name prefix changed from "mysql-

router-" to "mysql-router-community-". This change also allows upgrading from MySQL Router 2.1 to 8.0.

MySQL Router 8.0 Release Notes

Additionally, a "mysql-router" meta package was added that redirects "mysql-router" to "mysql-router-

community". (WL #11127)

• MySQL Router is now included in MySQL Server's source and monolithic binary packages. The MySQL

Router standalone packages continue to exist, as before. (WL #10799)

Bugs Fixed

• For SLES 12, MySQL binary distributions are now built using GCC 7. The lowest supported GCC version

on this platform is now 5.3 (previously 4.8.5).

Installing MySQL Router 8.0.13 or higher RPM packages on SLES 12 platforms requires that the GCC

Devel repo is enabled, for example:

shell> cd /etc/zypp/repos.d/

shell> wget https://download.opensuse.org/repositories/devel:/gcc/SLE-12/devel:gcc.repo

...

shell> zypper install ./mysql-router-community-8.0.*rpm

(Bug #28685857)

References: See also: Bug #92147.

• The log level was changed from INFO to DEBUG for the InnoDB Cluster Metadata server and replicaset

connections. Because MySQL Router's ttl configuration option defaults to 0.1, these each generate 10

log entries per second. (Bug #28424243)

• Running MySQL Router against an invalid InnoDB Cluster would report internal SQL errors, such as

"Unknown database 'mysql_innodb_cluster_metadata'", rather than user-friendly information that the

cluster is not set up as a metadata server. The generated error now clarifies the reason and points to