PolarDB-X is MySQL-protocol compatible, so you can connect to it using Data Management (DMS), the MySQL CLI, any MySQL-compatible GUI client, or application code written in Java, Python, or Go.
Choose a connection method
Use the table below to identify the right method for your environment:
| Environment | Recommended method |
|---|---|
| Alibaba Cloud console, no local client needed | DMS |
| Local GUI tool preferred | MySQL Workbench or another GUI client |
| Command line preferred | MySQL CLI |
| Connecting from application code | Java, Python, or Go driver |
Prerequisites
Before you begin, make sure you have:
The database endpoint and port for your instance — go to the PolarDB for Distributed console, click the instance ID in the Instances list, and find both values under Basic Information > Connection Information
Internal endpoints cannot be used from a virtual host or Simple Application Server.
Choose the right endpoint type:
Endpoint type When to use Internal endpoint Your Elastic Compute Service (ECS) instance and PolarDB-X instance are in the same Virtual Private Cloud (VPC). Provides the best performance. Public endpoint Connecting from an on-premises machine or an ECS instance in a different VPC. Click Apply for Public Endpoint to get one. Internet access works but does not provide optimal performance. 
A database account — create one if you have not done so
An IP whitelist configured for the instance — go to Configuration Management > Security Management and add the IP address or CIDR block of your client. For full instructions, see Configure whitelists If your network uses a proxy, the IP returned above may not be your actual public IP. In that case, add
0.0.0.0/0to the whitelist temporarily, connect to the instance, runSHOW PROCESSLIST;to find your real IP, add it to the whitelist, then remove0.0.0.0/0.WarningThe
0.0.0.0/0CIDR block allows access from all IP addresses. Remove it from the whitelist as soon as you have identified your actual IP.Finding your public IP address:
OS Command Linux / macOS curl ifconfig.meWindows curl ip.me

Connect using DMS
Data Management (DMS) is a browser-based management tool provided by Alibaba Cloud. It covers data management, schema management, user authorization, security audit, data trends, data tracking, BI charts, performance optimization, and server management — no additional client software needed.
In the PolarDB for Distributed console, click the instance ID, then click Log On To Database in the upper-right corner.

Enter your Database Account and Database Password, then click Logon.
Click Test Connection before logging on to verify your credentials. If the test fails, check the account and password you entered. DMS automatically adds its server IP addresses to the ApsaraDB whitelist. If the addresses are not added automatically, add them manually. By default, the control mode is Flexible Management when you first log on to DMS. To change it after logging on, see Modify instance information and Control modes.

After you log on, the instance appears in Instances Connected in the left navigation pane.

Connect using a GUI client
PolarDB-X works with any MySQL-compatible GUI client. Recommended options:
MySQL Workbench (recommended)
SQLyog
Sequel Pro
Navicat for MySQL
GUI clients support standard CRUD and DDL operations. Advanced client-specific features may not be supported by PolarDB-X.
The following steps use MySQL Workbench 8.0.29. Other clients follow a similar pattern.
Download and install MySQL Workbench.
Open MySQL Workbench and choose Database > Connect to Database.
Enter your connection details and click OK.
Parameter Description Example Hostname The database endpoint pxc-xxx.polarx.rds.aliyuncs.comPort The port number (default: 3306) 3306Username Your database account polardb_x_userPassword The account password Pass***233
Connect using the MySQL CLI
If MySQL is installed on your machine, connect with a single command:
mysql -h<endpoint> -P<port> -u<username> -p<password> -D<database>Example:
mysql -hpxc-xxx.polarx.rds.aliyuncs.com -P3306 -upolardb_mysql_user -pPass***233 -Dtest_db| Flag | Description | Example |
|---|---|---|
-h | Database endpoint | pxc-xxx.polarx.rds.aliyuncs.com |
-P | Port number. Omit if using the default port (3306). | 3306 |
-u | Database account | polardb_x_user |
-p | Password. Required. Do not add a space between -p and the password. Omit the value to be prompted interactively. | Pass***233 |
-D | Database name. Optional. | test_db |
Connect from application code
PolarDB-X accepts standard MySQL connections. Replace the endpoint, port, account, and password in any MySQL driver or library you already use.
Java
This example uses Maven with the MySQL JDBC driver.
Add the driver dependency to your
pom.xml:<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.27</version> </dependency>Connect to the instance. Replace
<HOST>,<USER>,<PASSWORD>, and<DATABASE>with your values.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) { // Connection string: endpoint, port, and database name String url = "jdbc:mysql://<HOST>:3306/<DATABASE>?useSSL=false&serverTimezone=UTC"; String user = "<USER>"; String password = "<PASSWORD>"; try { Class.forName("com.mysql.cj.jdbc.Driver"); Connection conn = DriverManager.getConnection(url, user, password); Statement stmt = conn.createStatement(); ResultSet rs = stmt.executeQuery("SELECT * FROM `<YOUR_TABLE_NAME>`"); while (rs.next()) { System.out.println(rs.getString("<YOUR_TABLE_COLUMN_NAME>")); } rs.close(); stmt.close(); conn.close(); } catch (Exception e) { e.printStackTrace(); } } }
Python
This example uses Python 3 with PyMySQL.
Install PyMySQL:
pip3 install PyMySQLConnect to the instance. Replace
<HOST>,<USER>,<PASSWORD>, and<DATABASE>with your values.import pymysql host = '<HOST>' # Database endpoint port = 3306 # Default port user = '<USER>' # Database account password = '<PASSWORD>' # Account password database = '<DATABASE>' # Target database try: connection = pymysql.connect( host=host, port=port, user=user, passwd=password, db=database ) with connection.cursor() as cursor: cursor.execute("SELECT * FROM `<YOUR_TABLE_NAME>`") results = cursor.fetchall() for row in results: print(row) finally: if 'connection' in locals() and connection.open: connection.close()
Go
This example uses Go 1.23.0 with the database/sql package and the go-sql-driver/mysql driver.
Install the driver:
go get -u github.com/go-sql-driver/mysqlConnect to the instance. Replace
<HOST>,<USER>,<PASSWORD>, and<DATABASE>with your values.package main import ( "database/sql" "fmt" "log" _ "github.com/go-sql-driver/mysql" ) func main() { dbHost := "<HOST>" // Database endpoint dbPort := "3306" // Default port dbUser := "<USER>" // Database account dbPass := "<PASSWORD>" // Account password dbName := "<DATABASE>" // Target database // 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) 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 database version to confirm a successful connection var version string if err = db.QueryRow("SELECT VERSION()").Scan(&version); err != nil { log.Fatalf("Query failed: %v", err) } fmt.Printf("Connected. Database version: %s\n", version) // Query a table rows, err := db.Query("SELECT * FROM `<YOUR_TABLE_NAME>`") if err != nil { log.Fatalf("Query failed: %v", err) } defer rows.Close() for rows.Next() { var id int var name string if err := rows.Scan(&id, &name); err != nil { log.Fatalf("Scan failed: %v", err) } fmt.Printf("ID: %d, Name: %s\n", id, name) } if err = rows.Err(); err != nil { log.Fatalf("Row iteration error: %v", err) } }
Best practices for timeout settings
Troubleshooting
The following errors are the most common connection issues. Use Ctrl+F to search for your exact error message.
| Error message | Likely cause |
|---|---|
Access denied for user 'xxx'@'xxx' (using password: YES) | Incorrect account or password |
Unknown MySQL server host 'xxx' | Incorrect endpoint |
Can't connect to MySQL server on 'xxx' / Connection timed out | IP not whitelisted, or invalid IP or CIDR block |