PolarDB:Connect to a Global Database Network

How routing works

Request routing in a GDN is controlled by the database proxy configuration of each cluster. Connect to the nearest cluster endpoint, and the proxy routes each request automatically:

• Writes (all DML, DDL, requests inside transactions) go to the primary node of the primary cluster.

• Reads outside transactions go to read-only nodes of the local secondary cluster by default, providing the lowest latency.

• If session consistency is enabled, some reads are redirected to the primary cluster to guarantee data freshness.

The primary node of a secondary cluster handles asynchronous data replication from the primary cluster only — it does not serve read or write requests. In the routing table below, "primary node" refers to the primary node of the primary cluster, and "read-only nodes" refers to the read-only nodes of the secondary clusters.

Detailed routing rules

Reads are sent to the primary node only when Primary Node Accepts Read Requests is set to Yes in the database proxy configuration.

Choose an endpoint

Select your endpoint based on your workload:

The Primary Endpoint and custom endpoints with Read/Write Mode set to Read-only do not support GDN read/write splitting.

Global domain name

The GDN global domain name routes requests to the nearest cluster and preserves the same connection string after a primary cluster switchover. Use it to avoid updating application configuration after failover.

Prerequisites

Before you begin, ensure that you have:

• A GDN with at least one secondary cluster

• A database account and password for the target cluster

• (For application connections) Network access from your application host to the cluster endpoint in the target region

View cluster endpoints

1. Log on to the PolarDB console and click Global Database Network (GDN) in the navigation pane.

2. On the Global Database Network (GDN) page, find the target GDN and click its Global Database Network ID.

3. In the Clusters section, find the target secondary cluster and click View in the Cluster Endpoint column. The dialog box shows the Private and Public endpoints of the default cluster endpoint.

   

To see all endpoints for a cluster, click Visit the Overview page of the cluster. The Database Connections section on the cluster's details page lists every available endpoint.

Connect to a GDN cluster

The following sections cover four connection methods. Use whichever fits your workflow.

mysql -h <Endpoint> -P <Port> -u <Account> -p<Password>

mysql -h pc-2***.rwlb.rds.aliyuncs.com -P3306 -upolardb_mysql_user -pPass***233

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.27</version>
</dependency>

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class DatabaseConnection {
    public static void main(String[] args) {
        // Endpoint, port, and database name of the PolarDB cluster
        String url = "jdbc:mysql://<HOST>:3306/<DATABASE>?useSSL=false&serverTimezone=UTC";
        // Database account
        String user = "<USER>";
        // Database account password
        String password = "<PASSWORD>";

        try {
            Class.forName("com.mysql.cj.jdbc.Driver");
            Connection conn = DriverManager.getConnection(url, user, password);
            Statement stmt = conn.createStatement();
            // Table to query
            ResultSet rs = stmt.executeQuery("SELECT * FROM `<YOUR_TABLE_NAME>`");

            while (rs.next()) {
                // Column to print
                System.out.println(rs.getString("<YOUR_TABLE_COLUMN_NAME>"));
            }

            rs.close();
            stmt.close();
            conn.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

pip3 install PyMySQL

import pymysql

host = '<HOST>'         # Cluster endpoint
port = 3306             # Default port
user = '<USER>'         # Database account
password = '<PASSWORD>' # Database account password
database = '<DATABASE>' # Database name

try:
    connection = pymysql.connect(
        host=host,
        port=port,
        user=user,
        passwd=password,
        db=database
    )

    with connection.cursor() as cursor:
        sql = "SELECT * FROM '<YOUR_TABLE_NAME>'"
        cursor.execute(sql)
        results = cursor.fetchall()
        for row in results:
            print(row)

finally:
    if 'connection' in locals() and connection.open:
        connection.close()

go get -u github.com/go-sql-driver/mysql

package main

import (
    "database/sql"
    "fmt"
    "log"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    dbHost := "<HOST>"     // Cluster endpoint
    dbPort := "3306"       // Default port
    dbUser := "<USER>"     // Database account
    dbPass := "<PASSWORD>" // Database account password
    dbName := "<DATABASE>" // Database name

    // Build the DSN (Data Source Name)
    dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
        dbUser, dbPass, dbHost, dbPort, dbName)

    db, err := sql.Open("mysql", dsn)
    if err != nil {
        log.Fatalf("Failed to open connection: %v", err)
    }
    defer db.Close()

    // Verify the connection
    if err = db.Ping(); err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }

    // Print the server version
    var version string
    if err = db.QueryRow("SELECT VERSION()").Scan(&version); err != nil {
        log.Fatalf("Failed to query version: %v", err)
    }
    fmt.Printf("Connected. Server version: %s\n", version)

    // Run a query
    rows, err := db.Query("SELECT * FROM '<YOUR_TABLE_NAME>'")
    if err != nil {
        log.Fatalf("Failed to execute query: %v", err)
    }
    defer rows.Close()
}

What's next

• Global Database Network (GDN) — GDN architecture and common use cases.

• Create a global domain name — Set up a stable connection address that survives primary cluster switchovers.

API reference