Help Center/ TaurusDB_TaurusDB for PostgreSQL/ User Guide/ Database Proxy (Read/Write Splitting)/ Introduction to Database Proxy
Updated on 2026-01-16 GMT+08:00
View PDF
Share

Introduction to Database Proxy

Database Proxy is a network proxy service that sits between TaurusDB for PostgreSQL and applications. It is used to handle all requests from the applications to access TaurusDB for PostgreSQL instances.

Read/Write splitting enables read and write requests to be automatically routed through a proxy address. After creating a TaurusDB for PostgreSQL instance, you can create a proxy instance. With the proxy address, write requests are automatically forwarded to the primary node, and read requests are forwarded to each node based on the routing policy of the proxy instance, offloading the read load from the primary node.

Proxy instances are free.

Basic Concepts

Proxy Address

After buying a proxy instance, you can view the proxy address on the Database Proxy page. The proxy instance sends write requests to the primary node and read requests to read replicas through this address.

Proxy Mode

There are read/write and read-only proxy modes. The read/write attribute processing logic varies depending on the proxy mode. For details, see Table 1.

  • Read/Write: Write requests are only forwarded to the primary node. Read requests are forwarded to the selected nodes with fewer active connections.
  • Read-only: All read requests are forwarded to the selected read replicas with fewer active connections.
Table 1 Read/Write attribute processing logic

Proxy Mode

Routing Policy

Normal Case

All Read Replicas Are Faulty

Read/Write

Load balancing

Primary node: readable and writable

Proxy address: readable and writable

Primary node: readable and writable

Proxy address: readable and writable

Read-only

Load balancing

The primary node does not process read-only requests.

Proxy address: readable but not writable

The primary node does not process read-only requests.

Proxy address: connection error

Connection Pool

Proxy instances provide transaction-level connection pooling. It helps reduce high load caused by frequently setting up connections. A transaction-level connection pool is suitable for short transactions. After a transaction is committed or rolled back, the system automatically resets the connection's session status (clearing user variables, temporary tables, and session-level configurations) and puts the connection back to the proxy instance's connection pool.

When a client starts a new transaction, it reuses an available connection from the pool to reduce the connection setup overhead and resource usage. If no connections are available, a new one is created as usual.

When any of the following operations is performed, the connection is locked until the client disconnects. Once locked, all subsequent SQL statements from users are routed to the same service node until the connection ends.
  • Running the PREPARE statement
  • Creating a temporary table
  • Modifying user variables. If users do not want to lock the connection when running the SET statement, they can set general.set_lock_session to false.

Routing Policy

Proxy instances support the load balancing routing policy.

Read requests are routed to the node with the fewest active connections.

How Read/Write Splitting Works

You can create one or more proxy instances for your TaurusDB for PostgreSQL instance to enable read/write splitting.

If your TaurusDB for PostgreSQL instance has only one proxy instance, applications connect to the proxy instance through the proxy address. Write requests are forwarded to the primary node and read requests to the primary node or read replicas based on the routing policy you specify.

Figure 1 Read/Write splitting with only one proxy instance

To isolate workloads from one another, you can create up to four proxy instances for a TaurusDB for PostgreSQL instance. Different applications can connect to different proxy instances as required. The associated read replicas of the proxy instances process read requests from different applications for workload isolation.

Figure 2 Read/Write splitting with multiple proxy instances

Read/Write Splitting Advantages

  • Read/Write splitting enables read and write requests to be automatically routed. You can easily scale out a proxy instance as required at low maintenance costs.
  • Read requests are distributed to read replicas to balance database traffic and improve resource utilization.
  • A proxy instance routes read requests of an application only to its associated read replicas to isolate workloads.

Request Routing Rules

Write Requests Sent Only to the Primary Node

  • INSERT, UPDATE, DELETE, SELECT FOR UPDATE, and SELECT INTO
  • All DDL operations (such as table/database creation, table/database deletion, table structure change, and permission change)
  • All requests in a transaction (except declared read-only transactions)
  • User-defined functions
  • Stored procedures
  • PREPARE/EXECUTE statements
  • Requests that use temporary tables
  • All changes to user variables

Read Requests Sent to the Primary Node

  • If a query statement is placed in a transaction, all requests in that transaction are routed to the primary node—unless it is a declared read-only transaction.
  • When running SQL statements:
    • Read operations with locks (for example, SELECT FOR UPDATE) will be routed to the primary node.
    • If you add /*FORCE_MASTER*/ at the beginning of a SQL statement, requests will be routed to the primary node.
    • TABLE statements (for example, TABLE pg_class) will be routed to the primary node.
  • All queries of user variables (for example, SHOW user.var;)
  • Function invocation requests sent over the FASTPATH protocol (The client directly sends a binary request by specifying the function OID and parameters.)
  • Query statements that invoke user-defined functions
  • Statements that use the TABLE syntax (for example, TABLE pg_class;)

Requests Sent Either to the Primary Node or a Read Replica

  • SELECT statements (excluding SELECT INTO and SELECT FOR UPDATE)
  • Multi-statements in simple query form
  • Multi-statements sent using P, B, D, and E packets.

Precautions

Table 2 Precautions for proxy instances

Category

Precaution

Unsupported functions

You cannot control access by editing the database's pg_hba file, and blocking proxy IP addresses there will prevent the proxy instances from connecting to the database.

Usage constraints
  • Read/Write splitting can be enabled only when at least one read replica is created.
  • After read/write splitting is enabled, the database port and private IP address of your TaurusDB for PostgreSQL instance cannot be changed.
  • If multiple proxy instances are deployed or users directly log in to the database, operations such as creating users, changing passwords, and changing permissions may not be applied immediately. The SQL statements of these operations will apply within the delay specified by the cache_refresh parameter, which defaults to 5 minutes.
    NOTE:

    cache_refresh specifies the interval (in seconds) for reading user and database metadata from the database and refreshing the cache. The default value is 300 seconds (5 minutes). You can manually change the value.

  • The lastval() and currval() functions may fail to obtain related values and can only be used in transactions.
  • rdsAdmin is the built-in account of the database proxy system. You are advised not to create an account with the same name or modify this account, or read/write splitting may not work properly.
  • The statements for modifying database parameters (including ALTER SYSTEM SET and SELECT pg_reload_conf()) are only applied on the primary node.
  • If a transaction is started, the entire transaction is executed on the primary node. (If a transaction is explicitly declared as read-only, the entire transaction is executed on a read replica.)
  • SQL statements that invoke stored procedures or use common table expressions are routed to the primary node.
  • When a proxy instance is used, database names and all database object names (including database names, table names, schemas, index names, and usernames) only support printable ASCII characters.
  • You cannot log in to the database as user rdsAdmin, rdsBackup, rdsMetric, or rdsRepl through a proxy instance.
  • You cannot log in to database template0 or template1 through a proxy instance.
Parent Topic: Database Proxy (Read/Write Splitting)