Quick start
This topic describes how to get started with PolarDB for MySQL, including how to create a cluster, configure an allowlist, create a database account, and connect to a database.
Tutorial
If you have questions about any of the following steps, click the step to view detailed instructions.
1. Create a cluster
Go to PolarDB and open the Quick Purchase page to quickly create a PolarDB for MySQL cluster with minimal configuration. Configure the parameters in the following table and use the default values for all other settings. For detailed instructions about how to create a cluster, see Create a cluster with custom configurations.
Parameter | Description |
Billing Method | Select the Billing type of the cluster. For more information, see Billing methods.
|
Region | Select the region where the cluster is deployed. Note Make sure that the PolarDB and the ECS instance that you want to connect to are in the same region. Otherwise, they cannot communicate directly over the internal network. |
Database Engine | Select the Database engine of the cluster.
Note Quick Purchase supports only the MySQL 8.0 version. To purchase another MySQL version, click the Purchase tab in the upper-left corner. |
Service Edition | Select the Edition of the cluster.
Note Enterprise Edition and Standard Edition provide different features. For more information, see Differences between Enterprise Edition and Standard Edition. |
Network Type | Configure the VPC and vSwitch for the cluster. Note
|
Deployment Mode (Optional) | Select the number of nodes and the high-availability mode for the cluster. For more information, see High-availability mode (hot standby cluster).
Note Only when the Billing type is Subscription or Pay-as-you-go do you need to select the high-availability mode of the cluster. |
Node Specifications | Select the compute node specifications for the cluster based on your requirements. To purchase other specifications, click the Purchase tab in the upper-left corner. |
Storage Capacity (Optional) | Configure the storage capacity of the cluster. Note Only when the Edition is Standard Edition do you need to configure the storage capacity of the cluster. |
2. Configure an allowlist
Go to the PolarDB console. In the Clusters list, click the ID of the target cluster to go to the cluster details page. Choose Configuration and Management > Cluster Whitelists to add an IP allowlist or a security group. For more information, see Configure whitelists for a cluster and Configure a security group.
If you use an ECS instance to access PolarDB, and the ECS instance and PolarDB are in the same VPC, you can add the CIDR block of the VPC where the ECS instance resides to the default group.
If you use an ECS instance to access PolarDB, but the ECS instance and PolarDB are not in the same VPC, you can add the public IP address of the ECS instance to a new IP allowlist group, or add the security group of the ECS instance to the cluster allowlist.
If you access PolarDB from your on-premises environment, add the public IP address of the on-premises environment to a new IP allowlist group.
To get the public IP address of your on-premises environment, use one of the following methods:
For the Linux operating system, open a terminal, enter the
curl ifconfig.mecommand, and press Enter.For the Windows operating system, open Command Prompt, enter the
curl ip.mecommand, and press Enter.For the macOS operating system, open a terminal, enter the
curl ifconfig.mecommand, and press Enter.
If your on-premises network uses a proxy or a similar setup, the IP address obtained by the preceding methods may not be your actual public IP address. You can add the
0.0.0.0/0CIDR block to the PolarDB cluster allowlist. After you connect to the cluster, run theSHOW PROCESSLIST;command to get your actual public IP address and add it to the cluster allowlist. Then, remove the0.0.0.0/0CIDR block from the allowlist.xxx | aurora | 100.104.xxx.xxx:59236 | information_schema | Sleep | 47 | | NULL 268459868 | polardb_mysql_account | 47.94.74.xxx:39160 | NULL | Query | 0 | starting | SHOW PROCESSLISTThe
0.0.0.0/0CIDR block allows all sources to access the cluster. Adding it to the cluster allowlist poses an extremely high risk. Do not add it to the allowlist unless necessary.
3. Create a database account
Go to the PolarDB console. In the Clusters list, click the ID of the target cluster to go to the cluster details page. Choose Configuration and Management > Accounts to create a database account. For more information, see Create and manage database accounts.
Database accounts can be Privileged Account or Standard Account, and the two account types have different privileges. Create a privileged account or a standard account based on your business needs. For more information, see Account privileges.
4. Get the cluster endpoint
Go to the PolarDB console. In the Clusters list, click the ID of the target cluster to go to its details page. Choose Database Connections to get the database endpoint. For more information, see Manage endpoints. On the Database Connection page, find the Cluster Endpoint (Recommended) section and click Copy next to the private endpoint to get the connection endpoint.
(Recommended) Use the Cluster Endpoint. The default port is 3306.
Select the Internal Network or the Internet endpoint based on your access environment.
If you use an ECS instance to access PolarDB, and the ECS instance and PolarDB are in the same VPC, select the Internal Network endpoint.
If you access PolarDB from your on-premises environment, select the Internet endpoint. For the public endpoint, click Application on the right.
Internet refers to the internet. Access through the Internet endpoint cannot deliver optimal performance for a PolarDB cluster.
Virtual hosts and simple application servers cannot use the Internal Network endpoint to connect to a PolarDB cluster.
5. Connect to the database
Choose a connection method that suits your needs:
Use DMS to connect to the cluster
DMS is a graphical data management service from Alibaba Cloud. You can manage your PolarDB cluster directly in DMS without installing additional tools.
Go to the PolarDB console. In the Cluster List, click the ID of the target cluster to go to the cluster details page. In the upper-right corner of the page, click Log on to Database.

Enter your database account and database password for the PolarDB for MySQL cluster, then click Log on.

After you log on, find the PolarDB for MySQL cluster in the Logged-in Instances list in the left navigation pane.

Use a client to connect to the cluster
You can use any MySQL-compatible client to connect to a PolarDB cluster. The following example uses MySQL Workbench 8.0.29.
Download and install MySQL Workbench.
Open MySQL Workbench and choose Database > Connect to Database.
Enter the connection information and click OK.

Parameter
Description
Example
Hostname
The database endpoint.
pc-2***.rwlb.rds.aliyuncs.com
Port
The port number of the database endpoint.
NoteThe default port is 3306.
3306
Username
The database account.
polardb_mysql_user
Password
The password of the database account.
Pass***233
Use the command line to connect to the cluster
If a MySQL client is installed on your server, run the following command to connect to the PolarDB for MySQL cluster.
Syntax:
mysql -h<endpoint> -P<port> -u<database_username> -p<database_user_password>Example:
mysql -h pc-2***.rwlb.rds.aliyuncs.com -P3306 -upolardb_mysql_user -pPass***233Parameter | Description | Example |
-h | The database endpoint. | pc-2***.rwlb.rds.aliyuncs.com |
-P | The port number of the database endpoint. Note
| 3306 |
-u | The database account. | polardb_mysql_user |
-p | The password of the database account. Note This parameter is required.
| Pass***233 |
Use an application to connect to the cluster
Connecting to a PolarDB for MySQL cluster is the same as connecting to any MySQL database. Replace the endpoint, port, account, and password with your PolarDB cluster values. Examples by language:
Java
Use the MySQL JDBC driver in a Maven project to connect to a PolarDB for MySQL cluster.
Add the MySQL JDBC driver dependency to your pom.xml file:
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.27</version> </dependency>Connect to the cluster. Replace
<HOST>,<USER>,<PASSWORD>,<DATABASE>,<YOUR_TABLE_NAME>, and<YOUR_TABLE_COLUMN_NAME>with your actual values.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 the PyMySQL library with Python 3 to connect to a PolarDB for MySQL cluster.
Install the PyMySQL library:
pip3 install PyMySQLConnect to the cluster. Replace
<HOST>,<USER>,<PASSWORD>,<DATABASE>, and<YOUR_TABLE_NAME>with your actual values.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 the database/sql package and go-sql-driver/mysql driver (Go 1.23.0) to connect to a PolarDB for MySQL cluster.
Install the
go-sql-driver/mysqldriver:go get -u github.com/go-sql-driver/mysqlConnect to the cluster. Replace
<HOST>,<USER>,<PASSWORD>,<DATABASE>, and<YOUR_TABLE_NAME>with your actual values.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() }
Cluster management
Node management | Change cluster configurations | High availability | Backup and restore |
Database proxy | Monitoring and optimization | Version management | Binary log management |
FAQ
ECS connection to the PolarDB cluster fails
Troubleshoot as follows:
Check whether the PolarDB cluster is in the running state.
Verify that the database endpoint, port, account, and password are correct. Obtain the database endpoint and port.
Test network connectivity from the ECS instance using
ping <database endpoint>ortelnet <database endpoint> <port>.If you are using a private network endpoint:
Check whether the ECS instance and the PolarDB cluster are in the same VPC. If they are not in the same VPC, you cannot use the private network endpoint. Use one of the following solutions to place the ECS instance and the PolarDB cluster in the same VPC:
Switch the VPC of the ECS instance.
If your cluster is a Cluster Edition cluster, you can switch the VPC of the cluster.
Use Cloud Enterprise Network (CEN) to enable communication between VPCs in the same region.
Check whether the private IP address, IP address range, or security group of the ECS instance is added to the cluster whitelist.
If you are using a public network endpoint, check whether the public IP address or security group of the ECS instance is added to the cluster whitelist.
Virtual hosts and simple application servers cannot connect to PolarDB through a private network endpoint.
On-premises connection to the PolarDB cluster fails
Troubleshoot as follows:
Check whether the PolarDB cluster is in the running state.
Verify that the database endpoint, port, account, and password are correct. Obtain the database endpoint and port.
NoteThe database endpoint must be a public network endpoint. If you are using an ECS instance that is in the same VPC as the PolarDB cluster, you can use a private network endpoint.
Test network connectivity from your on-premises environment using
ping <database endpoint>ortelnet <database endpoint> <port>.Check whether the public IP address or IP address range of your on-premises environment is added to the cluster whitelist.
Obtain your public IP address:
Linux operating system: Open the terminal and run the
curl ifconfig.mecommand.Windows operating system: Open the command prompt and run the
curl ip.mecommand.macOS operating system: Open the terminal and run the
curl ifconfig.mecommand.
If your on-premises network environment uses a proxy server or has other similar configurations, the IP address obtained using the preceding methods may not be your real public IP address. You can add the IP address range
0.0.0.0/0to the PolarDB cluster whitelist. After you successfully connect to the cluster, run theSHOW PROCESSLIST;command to obtain the real public IP address and add it to the cluster whitelist. Then, remove the IP address range0.0.0.0/0from the whitelist.
Cannot connect to a PolarDB cluster with the error "Access denied for user 'xxx'@'xxx' (using password: YES)"
The database account or password is incorrect. Go to the PolarDB console and verify or reset credentials on the Configurations and Management > Account Management page.
Cannot connect to a PolarDB cluster with the error "Unknown MySQL server host 'xxx'"
The database endpoint is incorrect. The correct format is pc-xxxxxx.rwlb.rds.aliyuncs.com. Go to the PolarDB console and verify the endpoint in the Basic Information > Database Connection section.
Cannot connect to a PolarDB cluster with the error "Can't connect to MySQL server on 'xxx'" or "Connection timed out"
The public IP address or IP address range of your environment is likely not in the PolarDB cluster whitelist, or the IP address you entered is incorrect.
Obtain your public IP address:
Linux operating system: Open the terminal and run the
curl ifconfig.mecommand.Windows operating system: Open the command prompt and run the
curl ip.mecommand.macOS operating system: Open the terminal and run the
curl ifconfig.mecommand.
If your on-premises network environment uses a proxy server or has other similar configurations, the IP address obtained using the preceding methods may not be your real public IP address. You can add the IP address range 0.0.0.0/0 to the PolarDB cluster whitelist. After you successfully connect to the cluster, run the SHOW PROCESSLIST; command to obtain the real public IP address and add it to the cluster whitelist. Then, remove the IP address range 0.0.0.0/0 from the whitelist.
