Todos os produtos
Search
Central de documentação

PolarDB:Conexão a uma rede de banco de dados global

Última atualização: Jun 28, 2026

Uma rede de banco de dados global (GDN) consiste em vários clusters PolarDB implantados em diferentes regiões. Este tópico explica como visualizar os endpoints de cluster de uma GDN e conectar-se a ela.

Divisão de leitura/escrita e roteamento de solicitações

A configuração do proxy de banco de dados de cada cluster determina o roteamento de solicitações de leitura e escrita para os clusters (primário e secundários) em uma GDN. Não é necessário modifique o código da aplicação. Basta conectar-se ao endereço do respectivo cluster para que as solicitações de leitura e escrita sejam roteadas automaticamente conforme a seguinte lógica:

  • O proxy de banco de dados encaminha automaticamente as solicitações de escrita (como instruções INSERT, UPDATE e DELETE), outras sintaxes de broadcast (como instruções SET) e todas as solicitações dentro de transações para o nó primário do cluster primário.

  • Por padrão, o proxy de banco de dados direciona as solicitações de leitura para os nós somente leitura do cluster secundário local, permitindo acesso local. Se a consistência de sessão estiver ativada, algumas solicitações de leitura também poderão ser roteadas para o nó primário do cluster primário para garantir a consistência dos dados.

Nota

As mesmas regras de roteamento se aplicam quando uma aplicação se conecta ao endpoint de cluster de um cluster secundário. Após o cliente estabelecer conexão com o proxy de banco de dados, o proxy cria e mantém conexões de backend do cluster secundário para o nó primário do cluster primário. A configuração do proxy de banco de dados define se essas conexões são pré-estabelecidas. O link de um cluster secundário para o nó primário geralmente é uma conexão entre regiões. Para aplicações com conexões de curta duração, a criação frequente dessas conexões entre regiões pode degradar o desempenho devido a flutuações na rede. Nesse cenário, recomendamos ativar as On-demand Connections no proxy de banco de dados do cluster secundário. Para mais informações, consulte Configurar um proxy de banco de dados.

Além disso, a GDN fornece um nome de domínio global, que permite acesso geograficamente próximo e permanece inalterado após um failover do cluster primário.

Lógica detalhada de roteamento

Nó de destino

Solicitações encaminhadas

Encaminhadas apenas para o nó primário do cluster primário

  • Todas as operações DML, como INSERT, UPDATE, DELETE e SELECT FOR UPDATE.

  • Todas as operações DDL, como criação, exclusão ou alteração de tabelas ou bancos de dados, e gerenciamento de permissões.

  • Todas as solicitações dentro de transações.

  • Funções definidas pelo usuário.

  • Procedimentos armazenados.

  • Instruções EXECUTE.

  • Multi Statements.

  • Solicitações que utilizam tabelas temporárias.

  • SELECT last_insert_id().

  • Todas as consultas e modificações em variáveis de usuário.

  • SHOW PROCESSLIST.

  • KILL (a instrução SQL KILL, não o comando KILL).

Encaminhadas para nós somente leitura ou para o nó primário

Nota

As solicitações são enviadas ao nó primário somente se Primary Node Accepts Read Requests estiver definido como Yes na configuração do proxy de banco de dados.

  • Solicitações de leitura fora de transações.

  • Comandos COM_STMT_EXECUTE.

Sempre encaminhadas para todos os nós

  • Todas as modificações em variáveis de sistema.

  • Comandos USE.

  • Comandos COM_STMT_PREPARE.

  • Comandos como COM_CHANGE_USER, COM_QUIT e COM_SET_OPTION.

Nota

O nó primário de um cluster secundário destina-se apenas à replicação interna e não atende tráfego de leitura ou escrita. Portanto, nesta tabela, "nó primário" refere-se ao nó primário do cluster primário, e "nós somente leitura" referem-se aos nós somente leitura dos clusters secundários.

Nota
  • O serviço de divisão de leitura/escrita da GDN é suportado apenas para endpoints de cluster ou endpoints personalizados nos quais o Read-write mode está definido como Read/Write (Automatic Read/Write Splitting).

  • O Primary address e os endpoints personalizados com Read-write mode definido como Read-Only não suportam o serviço de divisão de leitura/escrita da GDN.

  • Para reduzir o possível impacto nos negócios causado pelo atraso de replicação entre os clusters primário e secundários, recomendamos defina Primary Node Accepts Read Requests como No e o Consistency Level como Eventual Consistency (Weak) ao configurar um endpoint de cluster personalizado em um cluster secundário.

  • Se sua aplicação não tolerar o atraso de replicação de um cluster secundário, conecte-se diretamente ao endpoint de cluster do cluster primário.

Visualizar endpoints de cluster

  1. Faça login no console do PolarDB. No painel de navegação à esquerda, clique em Global Database Network (GDN).

  2. Na página Global Database Network (GDN), localize a GDN desejada e clique em seu GDN ID/Name para abrir a página de detalhes da GDN.

  3. Na seção Clusters, localize o cluster secundário desejado e clique em Cluster Endpoint na coluna View para visualizar os detalhes do endpoint de cluster.

    Nota
    • É possível visualizar apenas as informações de endpoint do cluster padrão, incluindo os endpoints Private e Public.

    • Para obter informações mais detalhadas sobre o endpoint, clique em Visit the Overview page of the cluster. Você será redirecionado para a página de detalhes do cluster desejado, onde poderá visualizar mais endpoints na seção Database Connections.

Conectar-se a um cluster GDN

Aplicações em diferentes regiões conectam-se à GDN usando o endpoint de cluster mais próximo, habilitando a divisão automática de leitura/escrita. Este tópico apresenta exemplos de vários métodos comuns de conexão.

Usar o DMS para conectar-se ao cluster

O DMS é um serviço gráfico de gerenciamento de dados da Alibaba Cloud. Gerencie seu cluster PolarDB diretamente no DMS sem instale ferramentas adicionais.

  1. Acesse o console do PolarDB. Na Cluster List, clique no ID do cluster desejado para ir à página de detalhes do cluster. No canto superior direito da página, clique em Log on to Database.image

  2. Insira sua database account e database password do cluster PolarDB for MySQL e clique em Log on.image

  3. Após fazer login, localize o cluster PolarDB for MySQL na lista Logged-in Instances no painel de navegação à esquerda.image

Usar um cliente para conectar-se ao cluster

Use qualquer cliente compatível com MySQL para conectar-se a um cluster PolarDB. O exemplo a seguir utiliza o MySQL Workbench 8.0.29.

  1. Baixe e instale o MySQL Workbench.

  2. Abra o MySQL Workbench e escolha Database > Connect to Database.

  3. Insira as informações de conexão e clique em OK.

    Connection dialog

    Parâmetro

    Descrição

    Exemplo

    Hostname

    O endpoint do banco de dados.

    pc-2***.rwlb.rds.aliyuncs.com

    Port

    O número da porta do endpoint do banco de dados.

    Nota

    A porta padrão é 3306.

    3306

    Username

    A conta do banco de dados.

    polardb_mysql_user

    Password

    A senha da conta do banco de dados.

    Pass***233

Usar a linha de comando para conectar-se ao cluster

Se houver um cliente MySQL instalado no servidor, execute o seguinte comando para conectar-se ao cluster PolarDB for MySQL.

Sintaxe:

mysql -h<endpoint> -P<port> -u<database_username> -p<database_user_password>

Exemplo:

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

Parâmetro

Descrição

Exemplo

-h

O endpoint do banco de dados.

pc-2***.rwlb.rds.aliyuncs.com

-P

O número da porta do endpoint do banco de dados.

Nota
  • A porta padrão é 3306.

  • Se a porta for a padrão, omita este parâmetro.

3306

-u

A conta do banco de dados.

polardb_mysql_user

-p

A senha da conta do banco de dados.

Nota

Este parâmetro é obrigatório.

  • Se você omitir este parâmetro, o sistema solicitará a senha após Enter password.

  • Se incluir este parâmetro, não adicione espaço entre -p e a senha.

Pass***233

Usar uma aplicação para conectar-se ao cluster

A conexão a um cluster PolarDB for MySQL segue o mesmo processo de conexão a qualquer banco de dados MySQL. Substitua o endpoint, porta, conta e senha pelos valores do seu cluster PolarDB. Exemplos por linguagem:

Java

Use o driver JDBC do MySQL em um projeto Maven para conectar-se a um cluster PolarDB for MySQL.

  1. Adicione a dependência do driver JDBC do MySQL ao seu arquivo pom.xml:

    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.27</version>
    </dependency>
  2. Conecte-se ao cluster. Substitua <HOST>, <USER>, <PASSWORD>, <DATABASE>, <YOUR_TABLE_NAME> e <YOUR_TABLE_COLUMN_NAME> pelos seus valores reais.

    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.ResultSet;
    import java.sql.Statement;
    
    public class DatabaseConnection {
       public DatabaseConnection() {
       }
    
       public static void main(String[] args) {
          // The endpoint, port, and name of the database to connect to.
          String url = "jdbc:mysql://<HOST>:3306/<DATABASE>?useSSL=false&serverTimezone=UTC";
          // The database account.
          String user = "<USER>";
          // The password of the database account.
          String password = "<PASSWORD>";
    
          try {
             Class.forName("com.mysql.cj.jdbc.Driver");
             Connection conn = DriverManager.getConnection(url, user, password);
             Statement stmt = conn.createStatement();
             // The name of the data table to retrieve.
             ResultSet rs = stmt.executeQuery("SELECT * FROM `<YOUR_TABLE_NAME>`");
    
             while(rs.next()) {
                // The name of the column in the data table to retrieve.
                System.out.println(rs.getString("<YOUR_TABLE_COLUMN_NAME>"));
             }
    
             rs.close();
             stmt.close();
             conn.close();
          } catch (Exception var7) {
             var7.printStackTrace();
          }
    
       }
    }

Python

Use a biblioteca PyMySQL com Python 3 para conectar-se a um cluster PolarDB for MySQL.

  1. Instale a biblioteca PyMySQL:

    pip3 install PyMySQL
  2. Conecte-se ao cluster. Substitua <HOST>, <USER>, <PASSWORD>, <DATABASE> e <YOUR_TABLE_NAME> pelos seus valores reais.

    import pymysql
    
    # Database connection parameters
    host = '<HOST>'  # The endpoint of the PolarDB cluster
    port = 3306  # The default port is 3306
    user = '<USER>'  # The database account
    password = '<PASSWORD>'  # The password of the database account
    database = '<DATABASE>'  # The name of the database to connect to
    
    try:
        # Create a database connection
        connection = pymysql.connect(
            host=host,
            port=port,
            user=user,
            passwd=password,
            db=database
        )
    
        # Get the cursor
        with connection.cursor() as cursor:
            # Execute an SQL query
            sql = "SELECT * FROM `<YOUR_TABLE_NAME>`"  # The name of the data table to retrieve
            cursor.execute(sql)
    
            # Get the query results
            results = cursor.fetchall()
            for row in results:
                print(row)
    
    finally:
        # Close the database connection
        if 'connection' in locals() and connection.open:
            connection.close()
    

Go

Use o pacote database/sql e o driver go-sql-driver/mysql (Go 1.23.0) para conectar-se a um cluster PolarDB for MySQL.

  1. Instale o driver go-sql-driver/mysql:

    go get -u github.com/go-sql-driver/mysql
  2. Conecte-se ao cluster. Substitua <HOST>, <USER>, <PASSWORD>, <DATABASE> e <YOUR_TABLE_NAME> pelos seus valores reais.

    package main
    
    import (
        "database/sql"
        "fmt"
        "log"
        _ "github.com/go-sql-driver/mysql"
    )
    
    func main() {
        // Database connection parameters
        dbHost := "<HOST>"       // The endpoint of the PolarDB cluster
        dbPort := "3306"         // The default port is 3306
        dbUser := "<USER>"       // The database account
        dbPass := "<PASSWORD>"   // The password of the database account
        dbName := "<DATABASE>"   // The name of the database to connect to
    
        // Build the Data Source Name (DSN)
        dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", dbUser, dbPass, dbHost, dbPort, dbName)
    
        // Open a database connection
        db, err := sql.Open("mysql", dsn)
        if err != nil {
            log.Fatalf("Failed to connect to database: %v", err)
        }
        defer db.Close()
    
        // Test the connection
        err = db.Ping()
        if err != nil {
            log.Fatalf("Failed to ping database: %v", err)
        }
    
        // Create a cursor
        var result string
        err = db.QueryRow("SELECT VERSION()").Scan(&result)
        if err != nil {
            log.Fatalf("Failed to execute query: %v", err)
        }
    
        // Print the database version
        fmt.Printf("Connected to database, version: %s\n", result)
    
        // Execute an SQL query
        rows, err := db.Query("SELECT * FROM `<YOUR_TABLE_NAME>`") // The name of the data table to retrieve
        if err != nil {
            log.Fatalf("Failed to execute query: %v", err)
        }
        defer rows.Close()
    }

Documentação relacionada

Referência de API

API

Descrição

DescribeDBClusterEndpoints

Consulta as informações sobre os endpoints de cluster de um cluster PolarDB.

ModifyDBClusterEndpoint

Modifica os atributos de um endpoint de cluster PolarDB. Os atributos incluem modo de leitura/escrita, adição automática de novos nós, nível de consistência, divisão de transações, Primary Node Accepts Read Requests e pool de conexões.