4.5 Reloading TLS

As of MySQL Router 26.10, TLS material can be reloaded without restarting MySQL Router. Reloading is asynchronous and does not disconnect or otherwise modify existing connections.

MySQL Router rescans the configured certificate, private key, Certificate Authority (CA), CA directory, certificate revocation list (CRL), and CRL directory paths, as applicable. These are the paths accepted when MySQL Router started. Reloading does not rescan mysqlrouter.conf and cannot change TLS modes, cipher suites, TLS versions, listener addresses, ports, plugin loading, or configured file paths. It also cannot enable TLS for a component that was configured without TLS.

The following components support TLS-material reload:

• routing, client-to-Router TLS: Reloads the Router server certificate, private key, and configured trust material for new client TLS handshakes.

• routing, Router-to-destination TLS: Reloads the configured client certificate, private key, CA, and CRL material for new destination connections.

• http_server: Reloads the HTTPS certificate, private key, and configured trust material for new HTTPS handshakes. |

• metadata_cache: Reloads the configured client certificate, private key, and trust material for newly created metadata connections.

A component does not need to have every type of TLS material configured. An unconfigured material type is not an error. TLS passthrough connections are not affected because Router does not terminate their TLS sessions.

Each component independently loads and validates its replacement TLS state before publishing it. This validation includes certificate and private-key compatibility and all configured trust material. If loading or validation fails, the component logs the error and continues to use its previous TLS state. A failure in one component does not prevent the other components from attempting their reloads.

A successful reload applies only to new TLS handshakes and new outbound connections. Connections and handshakes already in progress continue to use the TLS state they previously acquired. Reused outbound connections can continue using their previous TLS state until they are closed and replaced

Requesting Reload

On POSIX platforms, use one of the following commands:

mysqlrouter --reload-tls --pid=PID
mysqlrouter --reload-tls --pid-file=/run/mysqlrouter/mysqlrouter.pid

The command sends SIGHUP to the target Router process. On POSIX platforms, SIGHUP requests both TLS-material reload and log-file reopening.

For a packaged systemd service, use:

systemctl reload mysqlrouter.service

The packaged SysV init script similarly implements its reload and force-reload actions without stopping and restarting Router.

On Windows, MySQL Router must be running as a Windows service. To target the default MySQLRouter service, use:

mysqlrouter --reload-tls

To target a service installed under another name, use:

mysqlrouter --reload-tls --service-name=NAME

The command returns after the reload request is delivered. It does not wait for TLS files to be read or validated and does not report the result of the asynchronous reload. Review the Router log for successful completion and for errors reported by individual components. Multiple requests waiting before a reload begins can be combined into one reload. A request received while a reload is active causes another reload after the active reload completes.

Certificate-Replacement Example

Router is configured with stable paths below a current symbolic link, for example:

    [routing:example]
    client_ssl_cert=/etc/mysqlrouter/tls/current/router-cert.pem
    client_ssl_key=/etc/mysqlrouter/tls/current/router-key.pem

The current link points to the active date-versioned directory, for example:

/etc/mysqlrouter/tls/current -> /etc/mysqlrouter/tls/2026-07-20

To renew the certificate, create a new dated directory with the replacement files, change current to point to that directory, and request a reload:

> mysqlrouter --reload-tls --pid-file=/run/mysqlrouter/mysqlrouter.pid

The Router service account must be able to read the replacement files. If the replacement certificate and private key are invalid or do not match, the affected routing component logs the failure and continues to use its previously loaded TLS state.