Configure the read weight of a database proxy endpoint-ApsaraDB RDS(RDS)-阿里云帮助中心

When read and write traffic share a single connection path, write-heavy workloads can crowd out analytical queries, and you have no direct control over how read traffic is distributed across your read-only instances. The database proxy endpoint solves this by letting you assign a read/write attribute to each endpoint and set per-instance read weights, so you can route traffic precisely and scale read capacity independently.

Prerequisites

Before you begin, make sure that you have:

The database proxy feature enabled for your RDS instance. See Enable the database proxy feature
At least one read-only instance attached to your RDS instance, required for read/write splitting. See Create a read-only ApsaraDB RDS for PostgreSQL instance

Read/write attributes

A proxy endpoint operates in one of two modes:

Attribute	Typical use case	Traffic behavior
Read/Write	General application traffic with read/write splitting	All write requests go to the primary instance. Read requests are distributed across the read-only instances based on read weight. The endpoint must be connected to the primary instance and at least one read-only instance.
Read-only	Reporting, analytics, and other read-only workloads	The primary instance receives no traffic through this endpoint. New connections are distributed across the connected read-only instances in round-robin order. Each client connection lands on one read-only instance. The total connection capacity equals the sum of connections available across all connected read-only instances.

Note The IP address whitelist of the database proxy is automatically kept in sync with the IP address whitelist of the primary instance. Any update to the primary instance whitelist is immediately applied to the proxy.

Behavior by attribute and weight

The following table describes how traffic is handled under each combination of read/write attribute and weight settings.

Attribute	Weight method	Primary instance weight	Normal operation	After the last read-only instance is deleted	After all read-only instances are faulty
Read-only	Automatic or custom	Not configurable	Primary: no traffic. Proxy: read requests only.	Primary: no traffic. Proxy: connection error.	Primary: no traffic. Proxy: connection error.
Read/Write	Automatic	0 (see Default read weights)	Primary: write requests only. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.
	Custom	Weight > 0	Primary: read and write requests. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.
	Custom	Weight = 0	Primary: write requests only. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.	Primary: read and write requests. Proxy: read and write requests.

Notes on table terms:

No traffic to primary: The primary instance is excluded from read-only request forwarding.
Connection error: Occurs when a Read-only proxy endpoint has no available read-only instances to handle requests.
Read/Write mode with primary weight = 0: Read requests are not forwarded to the primary instance under normal conditions. If all read-only instances are faulty, a forceful hint is specified, or transaction splitting is enabled, the proxy forwards read requests to the primary instance as a fallback.

Configure read/write attributes and read weight

Go to the Instances page. In the top navigation bar, select the region where your RDS instance resides, then click the instance ID.
In the left-side navigation pane, click Database Proxy.
In the Connection Information section, find the endpoint to modify in the Proxy Endpoint (Terminal) ID column, then click Modify Configuration in the Actions column.
Set Read/Write Attributes to one of the following:
- Read/Write (Read/Write Splitting)
- Read-only (Primary Instance Not Connected to Receive Write Requests)
Set Read Weight Allocation to Automatic or Custom:
- Automatic: The system assigns a read weight to each instance based on its specifications. When you add a read-only instance, the system automatically includes it in read/write splitting with an appropriate weight — no manual update needed. For the weight values the system assigns, see Default read weights.
- Custom: Specify a read weight for each read-only instance. Valid values: 0–10000. When you create a new read-only instance, its initial weight is 0 — update the weight to include it in traffic distribution.
Note A higher weight means the instance receives proportionally more read requests. For example, if three read-only instances have weights 100, 200, and 200 and the primary instance weight is 0, the primary handles only writes and the read-only instances receive traffic in a 1:2:2 ratio.

Weight changes take effect immediately with no connection drops. Existing connections are unaffected; only new connections use the updated weights.

Note Read weights are automatically invalidated when a read-only instance is released, or when the primary instance fails or exceeds the replication latency threshold. Weights become valid again after the instance recovers.

Route requests with SQL hints

To override the proxy's routing decision for a specific query, add a routing hint to the SQL statement:

Force the query to the primary instance:

/*FORCE_MASTER*/ SELECT * FROM table_name;

Force the query to a read-only instance:

/*FORCE_SLAVE*/ SELECT * FROM table_name;

API reference

Operation	Description
DescribeDBProxy	Query the details of a database proxy
DescribeDBProxyEndpoint	Query the details of a database proxy endpoint
ModifyDBProxyEndpoint	Modify the read/write attribute and read weight of a database proxy endpoint