This document explains how to connect to your PolarDB for PostgreSQL (PolarFlex) cluster. After your cluster is running, you can connect to its built-in proxy to automatically handle read/write splitting.
Proxy
Proxy is a component for your PolarDB cluster that intelligently routes database requests. By connecting to different proxy addresses, you can automatically separate read and write operations, improving performance and availability.
High availability
Proxyautomatically detects the roles of the nodes in your cluster (primary and read-only) and requires no manual intervention.You can deploy
Proxyon multiple machines. If one proxy becomes unavailable, your application can connect through another one to maintain access to the database. To achieve high availability for your application, you can configure multiple proxy addresses in your JDBC connection string.
Read/write splitting
Proxy provides two different addresses to support different routing strategies:
Primary endpoint: Routes all requests (reads and writes) to the primary node. If the primary node fails,
Proxyautomatically detects the failure and switches to a new primary node. The default port is 12369.Read/write splitting endpoint: Routes write requests to the primary node and distributes read requests across all active read-only nodes. This balances the load and improves read performance.
Request forwarding for the primary endpoint | Request forwarding for the read/write splitting endpoint |
 |  |
Consistency levels
PolarDB for PostgreSQL (PolarFlex) provides two consistency levels for different scenarios:
Strong consistency: All requests are routed to the primary node of the cluster.
Session consistency: Read requests can be routed to read-only nodes. Within a single connection, the system ensures consistency based on the replication offset. However, consistency is not guaranteed across different connections. This level lets you fully utilize the resources of read-only nodes for read-only operations.
The two consistency levels correspond to two separate endpoints. Strong consistency applies to the primary endpoint on the default port 12369. Session consistency applies to the read/write splitting endpoint on the default port 12370.
Access the cluster
Built-in client
After the cluster starts, you can connect to the cluster using the built-in psql client from the PolarDB for PostgreSQL (PolarFlex) kernel binary package.
When you create a cluster, the following resources are created by default:
A user named
adminwith the passwordpostgres.A database named
admin_db.
Examples
Connect to the primary endpoint
PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h <primary_endpoint> -p12369 -U admin -d admin_dbConnect to the read/write splitting endpoint
PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h <read_write_splitting_endpoint> -p12370 -U admin -d admin_dbConnect to a target node
The default port for direct connections to a cluster node is 1523. To connect locally, you can use localhost for the -h parameter.
PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h <target_node_ip_address> -p1523 -U admin -d admin_dbJDBC
When you use Java Database Connectivity (JDBC) to connect to the database, configure the host addresses of multiple Proxy instances in the connection string. This ensures that client access is not affected if a single Proxy instance fails.
jdbc:postgresql://proxy1_host:proxy1_port,proxy2_host:proxy2_port,proxy3_host:proxy3_port/databaseDrivers
Select the appropriate driver based on your cluster's compatibility mode:
PostgreSQL-compatible mode: Use the standard, native PostgreSQL driver.
Oracle-compatible mode: Use the dedicated PolarDB driver.