The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a read-only query fails, then the router can retry the query on a different server.

Configuring Retries for Failed Reads

1. Configure retries for failed reads by configuring the retry_failed_reads parameter for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If the primary server fails, then the router can automatically reconnect existing client connections to the new primary server.

Configuring Automatic Primary Server Re-connection

1. Configure automatic primary server re-connection by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. If a replica server fails, then the router may need to create new connections to a different replica server for any existing client connections. The router takes certain steps to ensure that those new replica server connections have the same state as the old replica server connections.

Session Command History

The Read/Write Split Router (readwritesplit) maintains connection state on replica servers by keeping a session command history. If the router has to create a new connection, then it replays these session commands from the previous connection on the new connection.

Minimizing Memory Usage of Session Command History

The session command history can require a lot of memory if connections are long-lived. In these cases, there are two options to limit memory usage:

• Configure a maximum size for the session command history

• Disable the session command history. This option is not recommended, because you would lose out on the benefits of the session command history.

Configuring a Maximum Size of the Session Command History

1. Set the maximum size of the session command history by configuring some parameters for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

Disabling the Session Command History

1. Disable the session command history by configuring the disable_sescmd_history parameter for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a server fails, then the router may need to retry failed queries on a different server. The retry may need to be delayed in some cases, such as when automatic failover is in progress.

Configuring Delayed Retries for Failed Queries

1. Configure delayed retries for failed queries by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The load balances read-only queries between one or more replica servers. If the replica servers are using asynchronous , then the data on the replica servers can sometimes lag behind the primary server. When this occurs, read-only queries that are executed on the replica servers can return stale results if they are not executed in a causally consistent manner. Causal consistency is the act of ensuring that interdependent operations maintain consistency by performing them in the same order on all servers.

To prevent this, the Read/Write Split Router can be configured to enable "causal reads", which ensures causal consistency for read-only queries. When causal reads is enabled, the Read/Write Split Router ensures that load balanced read-only queries are only executed on the replica server after all write statements previously executed on the primary server are fully replicated and applied on that specific replica server.

performs query-based load balancing. For each client connected to MaxScale, it opens up connections to multiple back-end database servers. When the client sends a write query to MaxScale, it routes the query to the connection opened with the primary server. When the client sends a read query to MaxScale, it routes the query to a connection opened with one of the replicas.

This page contains topics that need to be considered when designing applications that use the Read/Write Split Router.

• How does the

The routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a server fails, then the router may need to replay in-progress transactions on a different server.

Session Command History

The maintains connection state on replica servers by keeping a session command history. If the router has to create a new connection, then it replays these session commands from the previous connection on the new connection.

The load balances read-only queries between one or more replica servers. It selects a replica server to execute a query using criteria configured by the slave_selection_criteria parameter.

MaxScale's performs query-based load balancing. For each client connected to MaxScale, it opens up connections to multiple back-end database servers. When the client sends a write query to MaxScale, it routes the query to the connection opened with the primary server. When the client sends a read query to MaxScale, it routes the query to a connection opened with one of the replicas.

What Does the Read/Write Split Router Support?

The supports:

The Read/Write Split Router (readwritesplit) uses well-defined rules to determine whether a statement can be routed to a replica server, or whether it needs to be routed to the primary server. Application designers must understand these rules to ensure that the router can properly load balance queries.

Statements Routed to the Primary Server

The following statements are routed to the primary server:

• Queries that write to the database. For example, this includes, but is not limited to, the following statements:
• Queries that modify the database (DDL) For example, this includes, but is not limited to, the following statements:

• Queries within open transactions If the application uses explicit transactions, then all queries within the transaction will be routed to the primary server. Explicit transactions are used in the following cases:

  • When is set to OFF.

  • When is executed.

For example, all queries will be routed to the primary server in this case:

And all queries will also be routed to the primary server in this case:

• Queries using stored procedures

• Queries using stored functions

• Queries using user-defined functions (UDF)

Statements Routed to a Replica Server

The following statements are routed to a replica server:

• Queries that are read-only For example, this includes, but is not limited to, the following statements:

• Queries that read system or user-defined variables For example, this includes, but is not limited to, the following statements:

For example, the following queries would be routed to a replica:

• Queries using built-in functions

Statements Routed to All Servers

The following statements are routed to all servers:

• statements, including those embedded in read-only statements

• statements

• statements that create prepared statements

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}