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 major engine version of the instance is PostgreSQL 10, PostgreSQL 11, PostgreSQL 12, PostgreSQL 13, or PostgreSQL 14.
  • The instance uses standard SSDs or enhanced SSDs (ESSDs).
  • 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:
    • China (Hong Kong): Hongkong Zone B.
    • China (Hangzhou): Hangzhou Zone G, Hangzhou Zone H, Hangzhou Zone I, and Hangzhou Zone J.
    • 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 (Shanghai): Shanghai Zone B, Shanghai Zone E, Shanghai Zone F, and Shanghai Zone G.
    • China (Shenzhen): Shenzhen Zone D and Shenzhen Zone E.
    • Indonesia (Jakarta): Jakarta Zone A.
    • Singapore (Singapore): Singapore Zone A, Singapore Zone B, and Singapore Zone C.

Billing

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

Precautions

  • 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 exist, you can enable the database proxy feature but cannot configure proxy terminals for your RDS instance. For more information, see Create a read-only ApsaraDB RDS for PostgreSQL instance.

Procedure

Step 1: Enable the database proxy feature

  1. Access RDS Instances, select a region at the top, and then click the ID of the target RDS instance.
  2. In the left-side navigation pane, click Database Proxy.
  3. Optional. The first time you enable the database proxy feature, click Authorize to the right of SLR Authorization. In the dialog box that appears, click OK. Alibaba Cloud automatically creates a service-linked role named AliyunServiceRoleForRdsProxyOnEcs. Then, the database proxy feature can use this role to bind elastic network interfaces (ENIs) to users and establish network connections.
    Note For more information about the service-linked role AliyunServiceRoleForRdsProxyOnEcs, see Service-linked roles.
  4. On the page that appears, click Enable Proxy. In the dialog box that appears, configure the Proxies parameter to specify the number of proxy instances and click Enable.
    Note
    • We recommend that you set the Proxies parameter to one-eighth of the total number of cores that are configured for your primary RDS instance and its read-only RDS instances. If the result is not an integer, you must round up the result to the nearest integer. Up to 60 proxy instances are supported.

      For example, if your primary RDS instance has eight cores and its read-only RDS instance has four cores, we recommend that you specify the Proxies parameter 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 Proxies 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 cores and 4 GB of memory and you enable two proxy instances, the database proxy of your RDS instance can provide 4 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. Database proxy details
    Table 1. Basic information
    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.
    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 the 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 cores and 4 GB of memory are supported.
    Enabled Proxy Instances The number of enabled proxy instances.
    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 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.

  1. Access RDS Instances, select a region at the top, and then click the ID of the target RDS instance.
  2. In the left-side navigation pane, click Database Proxy.
  3. On the page that appears, click the Proxy Terminal tab. Then, click Configure Proxy Terminal.
  4. In the dialog box that appears, configure the following parameters and click OK. Configure Proxy Terminal
    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 Processing logic based on the read and write attributes.
    • 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. This is the default attribute. 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 the read-only RDS instances to replicate data from the primary RDS instance. If the latency at which a read-only RDS instance replicates data from the primary RDS instance exceeds the value of this parameter, ApsaraDB RDS no longer routes 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 must 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: ApsaraDB RDS automatically assigns a read weight to each RDS instance in your database system based on the specifications of each 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 open. Only the requests that are sent over new connections are routed 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 route 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.
  • Proxy terminal: processes only read 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.
Read and write Automatic A weight greater than 0

For more information, see Default read weights.

  • 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 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.
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.

Related operations

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