Enable and configure the database proxy feature - ApsaraDB RDS

The database proxy feature of ApsaraDB RDS for PostgreSQL provides advanced capabilities such as read/write splitting. This topic describes how to enable and configure the database proxy feature for an ApsaraDB RDS for PostgreSQL instance.

Prerequisites

Your RDS instance meets the following conditions:

The RDS instance runs PostgreSQL 10 or later.
The instance uses cloud disks.
The instance runs RDS High-availability Edition.
The instance is a primary RDS instance.

The database proxy feature of ApsaraDB RDS for PostgreSQL is rolled out in phases. The feature is available in the following regions and zones:

Region	Zone
China (Hangzhou)	Hangzhou Zone G, Hangzhou Zone H, Hangzhou Zone I, and Hangzhou Zone J
China (Shanghai)	Shanghai Zone B, Shanghai Zone E, Shanghai Zone F, Shanghai Zone G, and Shanghai Zone I
China (Beijing)	Beijing Zone F, Beijing Zone G, Beijing Zone H, and Beijing Zone I
China (Zhangjiakou)	Zhangjiakou Zone A, Zhangjiakou Zone B, and Zhangjiakou Zone C
China (Shenzhen)	Shenzhen Zone D, Shenzhen Zone E, and Shenzhen Zone F
China (Hong Kong)	Hong Kong Zone B
Singapore (Singapore)	Singapore Zone A, Singapore Zone B, and Singapore Zone C
Malaysia (Kuala Lumpur)	Kuala Lumpur Zone A and Kuala Lumpur Zone B
Indonesia (Jakarta)	Jakarta Zone A, Jakarta Zone B, and Jakarta Zone C
Germany (Frankfurt)	Frankfurt Zone A
US (Virginia)	Virginia Zone B

Billing rules

For more information, see Billing rules for the database proxy of an ApsaraDB RDS for PostgreSQL instance.

Usage notes

After the database proxy feature is enabled, we recommend that you do not migrate the primary RDS instance across zones. If you migrate the primary RDS instance across zones, the primary RDS instance and its proxy instances are in different zones. This increases access latency and slows down responses.
A read-only RDS instance is created for your RDS instance. If no read-only RDS instances are created for your RDS instance, you can enable the database proxy feature but cannot configure proxy terminals for the RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.

Procedure

Step 1: Enable the database proxy feature

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 ID of the instance.
In the left-side navigation pane, click Database Proxy.
Optional. Click Authorize to the right of SLR Authorization. In the dialog box that appears, click OK. If this is the first time you enable the database proxy feature, this step is required. Alibaba Cloud automatically creates a service-linked role named AliyunServiceRoleForRdsProxyOnEcs. The role is used to establish network connections by binding elastic network interfaces (ENIs) to the server on which your RDS instance resides.
Note
For more information about the service-linked role AliyunServiceRoleForRdsProxyOnEcs, see Service-linked roles.

On the page that appears, click Enable Proxy. In the dialog box that appears, configure the Proxy Instances parameter to specify the number of proxy instances and click Enable Now.

Note

We recommend that you calculate the number of proxy instances by using the following formula: (Number of CPU cores that are configured for your primary RDS instance + Number of CPU cores that are configured for all read-only RDS instances of the primary RDS instance)/8. If the result is not an integer, you must round up the result to the nearest integer. Up to 16 proxy instances are supported.
For example, if your primary RDS instance has 8 CPU cores and its read-only RDS instance has 4 CPU cores, the recommended number of proxy instances is 2 based on the following calculation: (8 + 4)/8 = 1.5. The result 1.5 is rounded up to 2.
The number of proxy instances is used to calculate the performance of the database proxy. The number does not represent the actual number of proxy instances. If you set the Proxy Instances parameter to a large value, the database proxy can process more requests of your RDS instance.
For example, if a single proxy instance is configured with 2 CPU cores and 4 GB of memory and you enable two proxy instances, the database proxy of your RDS instance can provide 4 CPU cores and 8 GB of memory.

After you enable the database proxy feature, you can view the basic information about the database proxy on the Proxy tab.

Table 1. Basic information about the database proxy
Section	Parameter	Description
Proxy Endpoint	Status	The status of the database proxy.
	Primary Instance ID	The ID of the RDS instance.
	Associated Proxy Instances	The number of proxy instances that are associated with the database proxy. You can increase the processing capability of the database proxy by enabling more proxy instances.
Endpoint	Proxy Terminal	The name of the proxy terminal. You can create multiple proxy endpoints for each proxy terminal. For more information, see Create a database proxy endpoint.
	Endpoint	The endpoint that is used to connect to the database proxy. The database proxy provides a default proxy endpoint to which the proxy terminal feature is bound. You can create, modify, or delete a proxy endpoint. For more information, see Manage the database proxy endpoints of an ApsaraDB RDS for PostgreSQL instance.
	VPC	The VPC and vSwitch to which the proxy terminal belongs.
	VSwitch	The VPC and vSwitch to which the proxy terminal belongs.
	Port	The port number that is bound to the proxy endpoint. Note To change a port number, find the proxy endpoint to which the port number is bound and click Change on the right. A valid port number ranges from 1000 to 5999.
	Network Type	The network type of a proxy endpoint. You cannot change the network type of a proxy endpoint.
Proxy Instance	Proxy Type	Only Dedicated Proxy is supported.
	Unit Proxy Specifications	The specifications of each proxy instance. Only the specifications of `2 CPU cores and 4 GB of memory` are supported.
	Zone	The zone of the proxy instance.
	Enabled Proxy Instances	The number of enabled proxy instances. You can modify this value.
	Current Proxy Specifications	The specifications of the current database proxy. The value is calculated based on the values of the Unit Proxy Specifications and Enabled Proxy Instances parameters. For example, if the value of the Enabled Proxy Instances parameter is 2, the specifications of the current database proxy are `4 CPU cores and 8 GB of memory`.

Step 2: Configure a proxy terminal

Before you can use the advanced capabilities that are provided by the database proxy feature, you must configure a proxy terminal for your RDS instance.

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 ID of the instance.
In the left-side navigation pane, click Database Proxy.
On the page that appears, click the Proxy Terminal tab. Then, click Configure Proxy Terminal.

Configure the following parameters and click OK.

Parameter	Description
Custom Proxy Terminal	The name of the proxy terminal. The name can be up to 30 characters in length.
Read/Write Attribute	The read and write attributes of the proxy terminal. For more information about the read and write attributes, see Read Weight Distribution. Read/Write (Read/Write Splitting): The proxy terminal connects to the primary RDS instance and the read-only RDS instances, and can receive write requests. If you select this option, your primary RDS instance can receive write requests, and you can specify a read weight for the primary RDS instance. If you select this option, make sure that the proxy terminal is associated with at least one primary RDS instance and one read-only RDS instance. All write requests are routed to the primary RDS instance. Read-only: The proxy terminal connects only to the read-only RDS instances and cannot receive write requests. You cannot specify a read weight for your primary RDS instance. If you select this option, make sure that the proxy terminal is associated with at least one read-only RDS instance. The proxy terminal does not route requests to the primary RDS instance. If you select Read-only for a proxy terminal, the proxy terminal assigns connections to the associated read-only RDS instances based on the round-robin algorithm. Each database client is assigned only one connection to one read-only RDS instance. The proxy terminal does not assign the connection to the primary RDS instance. The total number of available connections is the sum of connections that are established to all the read-only RDS instances.
Latency Threshold	The maximum latency that is allowed for data replication from the primary RDS instance to the read-only RDS instances. If the latency of data replication to a read-only RDS instance exceeds the value of this parameter, the system no longer forwards read requests to the read-only RDS instance regardless of the read weight of the read-only RDS instance. Valid values: 0 to 3600. Unit: seconds. The read-only RDS instances may replicate data from the primary RDS instance at a specific latency. The latency varies based on the status of the SQL statements that are executed. We recommend that you set this parameter to a value that is greater than or equal to 30. Note This parameter appears only when you set the Read/Write Attribute parameter to Read/Write (Read/Write Splitting).
Read Weight Distribution	The method that is used to assign read weights. A higher read weight indicates more read requests that need to be processed. For example, three read-only RDS instances are attached to the primary RDS instance, the read weight of the primary RDS instance is 0, and the read weights of the three read-only RDS instances are 100, 200, and 200. In this case, the primary RDS instance processes only write requests, and the three read-only RDS instances process all read requests based on the 1:2:2 ratio. Automatic: The system assigns a read weight to each RDS instance in your database system based on the specifications of the RDS instance. After you create a read-only RDS instance, ApsaraDB RDS automatically assigns a read weight to the read-only RDS instance and adds the read-only RDS instance to the read/write splitting link. For more information, see Default read weights. Custom: You must manually specify a read weight for each RDS instance in your database system based on your business requirements. Valid values: 0 to 10000. By default, the read weight of a read-only RDS is 0. After you create a read-only RDS instance, you must manually specify a read weight for the read-only RDS instance based on your business requirements. Note You cannot specify weights for read-only RDS instances that have the data replication latency specified. After you reconfigure this parameter, the new read weights immediately take effect and no transient connections occur. In addition, the existing connections remain valid. Only the requests that are sent over new connections are forwarded based on the new weights. After the RDS instances are released, the read weights automatically become invalid. If your RDS instance fails or the data replication latency exceeds the specified threshold, the read weights automatically become invalid. After your RDS instance runs as normal, the read weights become valid again.

After you configure a proxy terminal, you must add the specified endpoint of the proxy terminal to your application. Then, ApsaraDB RDS can forward write requests to the primary RDS instance and read requests to the read-only RDS instances based on the read weights of these instances.

Processing logic based on the read and write attributes

Read and write attributes	Method to specify read weights	Weight of a primary RDS instance	Normal case	After the last read-only RDS instance is deleted	After all read-only RDS instances are faulty
Read-only	Automatic or Custom	You cannot specify a read weight for your primary RDS instance.	Primary RDS instance: does not process read or write requests. In this case, no request forwarding is performed. Proxy terminal: processes only read requests.	Primary RDS instance: does not process read or write requests. In this case, no request forwarding is performed. Proxy terminal: does not process read or write requests. In this case, a connection error occurs.	Primary RDS instance: does not process read or write requests. In this case, no request forwarding is performed. Proxy terminal: does not process read or write requests. In this case, a connection error occurs.
Read and write	Automatic	A weight equal to 0 For more information, see Rules of weight allocation by the system.	Primary RDS instance: processes only write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.
	Custom	A weight greater than 0	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.
	Custom	A weight equal to 0	Primary RDS instance: processes only write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.	Primary RDS instance: processes read and write requests. Proxy terminal: processes read and write requests.

Note

No request forwarding: indicates that the primary RDS instance is not involved in read-only request forwarding.
Connection error: indicates that a connection error is reported when the proxy terminal does not process read or write requests.
In read/write mode, when the weight of the primary RDS instance is set to 0, read requests are not forwarded to the primary RDS instance by default. However, if read-only RDS instances of the primary RDS instance are faulty, a forceful hint is specified, or transaction splitting is enabled, the read requests are forwarded to the primary RDS instance.

Related operations

Operation	Description
ModifyDBProxy	Enables or disables the database proxy feature for an instance.
DescribeDBProxy	Queries the details of a database proxy.
ModifyDBProxyEndpoint	Configures a database proxy terminal.