Readable secondary instance

How it works

To make the secondary instance readable on an SQL Server Cluster Edition instance, you must enable either a dedicated read-only endpoint for the secondary instance or read/write splitting (unified read-only endpoint). The read/write capabilities of the primary and secondary instances vary based on the option you choose:

• If neither a dedicated read-only endpoint nor read/write splitting is enabled: Only the primary instance is readable and writable. You cannot read from or write to the secondary instance.

• If a dedicated read-only endpoint for the secondary instance is enabled: The primary instance is readable and writable, and the secondary instance is read-only. This endpoint routes connections only to the secondary instance, not to the primary instance or any other read-only instances.

• If read/write splitting (unified read-only endpoint) is enabled: The primary instance is readable and writable, and the secondary instance is read-only. The primary instance, secondary instance, and all read-only instances can participate in read weight distribution.

Prerequisites

The primary instance must meet the following requirements. You can view this information on the Basic Information page of the instance.

• Instance version: 2017 Enterprise Cluster Edition, 2019 Enterprise Cluster Edition, 2022 Enterprise Cluster Edition, or 2025 Enterprise Cluster Edition

• Instance series: Cluster Edition

• Storage type: ESSD or ultra disk

• Billing method: subscription or pay-as-you-go. Serverless instances are not supported.

Method 1: Configure read/write splitting

1. Log on to the ApsaraDB RDS console and go to the Instances page. In the top navigation bar, select the region in which the RDS instance resides. Then, find the RDS instance and click the instance ID.

2. In the navigation pane on the left, click Cluster Management.

3. If read/write splitting is not enabled, click Enable Read-only Endpoint. In the dialog box that appears, set Endpoint Type and Weight Distribution.

   If read/write splitting is already enabled, click Configure Readonly Splitting Address . In the dialog box that appears, set Weight Distribution.

   The weight value must be an integer multiple of 100. For example, to make the secondary instance readable, you can assign it a weight greater than 0 (e.g., 800), while setting the primary instance's weight to 0 to offload all read requests from it.

   The higher the read weight of an instance, the more read requests it processes. For example, if three instances in the read pool have weights of 100, 200, and 200, they process read requests at a 1:2:2 ratio.

   • Automatic Distribution: The system automatically allocates the read weight for each instance based on its specifications. New read-only instances that are subsequently added to the primary instance are also automatically added to the read/write splitting link based on the system-allocated weights. No manual configuration is required.

   • Customized Distribution: Manually set the read weight for each instance. The value must be an integer from 0 to 10,000. New read-only instances receive a default weight of 0 and require manual configuration.

   Note

   When you delete a read-only instance, the system automatically removes its weight. The weights of the remaining instances do not change.

4. Click OK.

Method 2: Enable dedicated read-only endpoint

The dedicated read-only endpoint provides read-only access exclusively to the secondary instance. You cannot use this endpoint to access the primary instance or other read-only instances.

1. Go to the RDS Instances page, select a region in the top navigation bar, and then click the ID of the target instance.

2. In the navigation pane on the left, click Cluster Management.

3. In the Secondary Instance Network Information section, click Enable Secondary Instance Endpoint, and then set the Endpoint Type.

4. Click OK.

API reference

You can call the AllocateReadWriteSplittingConnection operation to allocate a read-only endpoint.