ApsaraDB RDS:Set read/write splitting attributes and read weights

Choose a mode

Read/Write mode requires at least one primary instance and one read-only instance in the proxy access policy. It supports transaction splitting and connection pools.

Read-only mode requires at least one read-only instance. The primary instance is not involved in routing, and transaction splitting is not supported. Each client connection maps to a single connection on one read-only instance. The total connection capacity equals the sum of connections across all configured read-only instances.

For Cluster Edition instances, Read/Write mode sends writes only to the primary node, while Read-only mode routes reads to secondary nodes in round-robin. The IP whitelist for the database proxy stays in sync with the primary instance's whitelist automatically.

Routing behavior in edge cases

The table below shows what happens in Read/Write mode when read-only instances are unavailable, and in Read-only mode under all weight scenarios.

In Read-only mode, "no forwarding" means the primary instance does not accept read requests. If the proxy has no readable instances, clients receive a connection error.

In Read/Write mode with the primary weight set to 0, reads are not sent to the primary instance by default. Reads are sent to the primary instance only if a read-only node is unhealthy, a hint forces routing to it, or transaction splitting is enabled.

Load balancing based on active requests (recommended)

Routes each request to the node with the lowest (Active Requests / Node Weight) ratio. This adapts in real time to uneven load and is less affected by slow nodes.

Example with primary weight 100, read-only node 1 weight 200, and read-only node 2 weight 200:

Weight-based load balancing

Distributes read requests strictly by weight ratio using a round-robin algorithm. Each scheduling round selects the node with the highest current_weight value, then adjusts weights as follows:

1. Selection: The node with the highest current_weight is selected. Ties are broken by position in the configuration list.

2. Accumulation: After each round, every node's current_weight increases by its own weight.

3. Reset: The selected node's current_weight is reduced by the sum of all node weights.

Example with primary weight 100, read-only node 1 weight 200, and read-only node 2 weight 200:

Take a read-only instance offline without service interruption

To remove a read-only instance (for example, instance C in a cluster with primary A and read-only instances B and C) without disrupting traffic:

1. Go to the RDS Instances page, select the region, and click the ID of primary instance A.

2. In the left navigation pane, click Database Proxy. In the Connection Topology Management section, click Modify Configuration.

3. In the Modify Proxy Endpoint (Terminal) Configuration dialog, set the read weight for read-only node C to 0.

4. Go to the Monitoring and Alerts page for read-only instance C. In the Session Connection section, monitor the active_session metric and wait for it to drop to 0.

   If active_session does not reach 0 after a reasonable wait, kill the remaining sessions manually.

5. On the Database Proxy tab for primary instance A, remove read-only instance C from the proxy endpoint.

Route specific SQL statements with hints

Use SQL hints to force a statement to run on a specific node — useful for writes inside a SELECT or queries that must always use a read-only instance.

High-availability Edition instances:

• /*FORCE_MASTER*/ — routes the statement to the primary instance, even if its read weight is 0

• /*FORCE_SLAVE*/ — routes the statement to a read-only instance

Cluster Edition instances:

• /*FORCE_MASTER*/ — routes the statement to the primary node, even if its read weight is 0

• /*FORCE_SLAVE*/ — routes the statement to a secondary node

Add the hint at the beginning of the statement:

/*FORCE_MASTER*/ SELECT * FROM table_name;

Reduce cross-zone latency

To avoid a single point of failure, create at least two read-only instances for a primary instance and deploy them across different zones. Enable the nearest access feature to minimize network latency from cross-zone traffic. The nearest access feature controls how your application connects to the proxy; read weights control how the proxy routes requests to backend databases. Configure both together for optimal performance.

Is the primary instance still readable after I add read-only instances?

After read-only instances are added, the primary instance remains readable and writable at all times. Adding read-only instances does not affect the readability or writability of the primary instance.

The primary instance has its own direct connection endpoint. This endpoint connects directly to the primary instance without going through the database proxy, so the primary instance is always readable and writable through this endpoint regardless of read weight configuration.

The database proxy endpoint is used for read/write splitting. When connected through the proxy endpoint, read and write requests are routed based on the configured read weights. When the primary instance read weight is set to 0, the proxy does not forward read requests to the primary instance by default. However, the primary instance itself remains readable and writable through its direct connection endpoint. When all read-only instances experience latency exceeding the threshold or become unavailable, read requests are automatically routed back to the primary instance to ensure business continuity.

To control read/write routing through the proxy endpoint, adjust the read weights in the Database Proxy configuration.