Data Management Service (DMS) lets you query, manage schemas, and control access for all your Alibaba Cloud database instances from a single console. This guide shows you how to register an ApsaraDB instance in DMS so you can start managing it immediately.
Prerequisites
Before you begin, ensure that you have:
-
A DBA or administrator system role. To check your role, see View my system role
-
A private network endpoint for the instance—DMS does not support registration via public endpoints
Before you register
Database account
Create a dedicated database account for DMS rather than reusing an existing one. Grant permissions based on what you need to manage:
| Goal | Required permissions |
|---|---|
| Manage all databases on an instance | Permissions on all databases |
| Manage specific databases only | Permissions on those databases |
| Run DML operations and modify table schemas | Sufficient DML permissions |
| Work with views, stored procedures, triggers, and functions | Corresponding object permissions |
Whitelist configuration
When you register an ApsaraDB instance, DMS typically prompts you to configure a whitelist automatically. If the prompt does not appear and you cannot access the database in DMS, add the DMS IP address ranges to the database security settings manually.
Input formatting
Do not add leading or trailing spaces to any field values—this causes connection failures.
Register an instance
The following steps use an ApsaraDB RDS for MySQL database as an example.
-
Log on to the DMS console V5.0.
-
In the Database Instances area on the left, click the Add Instance icon
.NoteYou can also choose from the menu bar and click Add Instance.
Alternatively, choose Data Assets > Instance Management from the menu bar, then click Add Instance.
-
On the Add Instance page, fill in the instance details. See Parameter reference below.
-
Click Test Connection in the lower-left corner.
If the test fails, review the error message and correct the instance information.
-
After Connection successful appears, click Submit.
The instance is now registered. It appears in the instance list on the left side of the DMS console.
Parameter reference
Core parameters
These parameters are required for every registration.
| Parameter | Description |
|---|---|
| Data source | The database type to register. Defaults to Alibaba Cloud-MySQL. Selecting a different type refreshes the parameters on the page. |
| Instance region | The region where the database instance resides. |
| Entry method | How to identify the instance: by Instance ID or Connection String Address. |
| Instance ID or Connection String Address | The identifier for the instance. A connection string uses the format private-network-address:port—for example, rm-XXXXXXX.mysql.rds.aliyuncs.com:3306 for ApsaraDB RDS for MySQL. |
| Access mode | How DMS authenticates to the database. See Choose an access mode below. |
| Instance DBA | The DBA responsible for subsequent operations such as permission requests. |
Advanced parameters
Configure these as needed after the initial registration.
| Parameter | Description |
|---|---|
| Other primary accounts | Appears only for Cross-Alibaba Cloud account instances. Select the Alibaba Cloud account that owns the instance. If the account is not listed, click Add User to add it. For details, see Add a user. |
| Value-added feature package | Optional feature packages: Security Collaboration (includes all Stable Change features plus DevOps workflows and custom approval flows) or Stable Change (lock-free schema evolution and SQL review). If you select neither, the instance runs in Flexible Management mode. Sensitive Data Protection is available independently and lets you manage and mask sensitive data. For details, see Enable sensitive data protection. |
| Security rules | Appears when you select Security Collaboration. Choose the default security rule or a custom security rule for fine-grained database control. |
| Classification and grading template | Appears when you enable Sensitive Data Protection. Attach a classification and grading template to automatically detect and tag sensitive fields. |
| Environment type | The type of database environment (for example, production or development). |
| Instance name | Clear Sync instance name to set a custom display name in DMS. DMS syncs the name from ApsaraDB on first registration only; use Edit Instance to update it afterward. |
| Lock-free Schema Change | MySQL only. Choose how to execute schema changes: Execute with DMS lock-free change or Prioritize native lock-free, switch to DMS on failure. For details, see Enable the Lock-free Schema Change feature. |
| Enable SSL | MySQL and Redis only. DMS disables SSL by default. To use SSL, enable it here and make sure SSL is also enabled on the database. SSL encrypts the connection at the transport layer, improving security at the cost of slightly higher connection latency. |
| Query timeout (s) | The maximum time a query can run in an SQL window before DMS interrupts it. |
| Export timeout (s) | The maximum time an export operation can run in an SQL window before DMS interrupts it. |
|
Category |
Parameter |
Description |
|
Data source |
- |
By default, Alibaba Cloud-MySQL is selected. You can select a different database type. |
|
Basic information |
Database type |
Select the type of the database instance. Note
After you select a database type, DMS automatically refreshes the parameters on the Basic information page. |
|
Instance region |
Select the region where the database instance resides. |
|
|
Other primary accounts |
This parameter appears if you select Cross-Alibaba Cloud account instances. Select the Alibaba Cloud account to which the database instance belongs. Note
If the Alibaba Cloud account is not in the list, click Add User to add the Alibaba Cloud account of the instance purchaser. For more information, see Add a user. |
|
|
Entry method |
Select the method to add the database instance. You can add an instance by its Instance ID or Connection String Address. |
|
|
Instance ID or Connection String Address |
Enter the Instance ID or Connection String Address. Note
A connection string is in the format of `Private network address:Port number`. For example, for an ApsaraDB RDS for MySQL instance: rm-XXXXXXX.mysql.rds.aliyuncs.com:3306. |
|
|
Access mode |
Select whether to enable security hosting for the instance and the method to log on to the database. When security hosting is enabled, users do not need to directly handle credentials. This allows for fine-grained permission control.
|
|
|
Value-added feature package |
Select a feature package as needed.
|
|
|
Security rules |
This parameter appears if you select Security Collaboration for the feature package. You can select the default security rule or a custom security rule to implement fine-grained control over the database. |
|
|
Classification and grading template |
The Classification and grading template parameter appears only when you enable Sensitive Data Protection. You can attach a classification and grading template to an instance. This helps detect if fields in the instance's databases and tables match the template's detection rules. If a field matches a rule, it is tagged with a classification and a sensitivity level to protect highly sensitive fields. |
|
|
Advanced information |
Environment type |
Select the type of database environment. |
|
Instance name |
Clear the Sync instance name checkbox to customize the display name of the instance in DMS. Note
When you add an ApsaraDB instance for the first time, DMS syncs the instance name from the ApsaraDB side. The name is not synced afterward. You can maintain the instance name using the Edit Instance feature. |
|
|
Lock-free Schema Change |
Select whether to enable the lock-free schema evolution feature. You can choose one of two methods for executing changes: Execute with DMS lock-free change and Prioritize native lock-free, switch to DMS on failure. Note
This parameter appears only when the database is MySQL. |
|
|
Enable SSL |
Note
This parameter appears only when the database is MySQL or Redis. By default, DMS disables SSL connections. To connect to the database using SSL, manually enable SSL connections in DMS and ensure that SSL is enabled for the database. Secure Sockets Layer (SSL) encrypts network connections at the transport layer. This improves the security and integrity of communication data, but it increases the network connection response time. |
|
|
Instance DBA |
Select a DBA role for subsequent processes such as permission requests. |
|
|
Query timeout (s) |
Set a security policy. When the specified time is reached, a query statement executing in an SQL window is interrupted to protect the database. |
|
|
Export timeout (s) |
Set a security policy. When the specified time is reached, an export statement executing in an SQL window is interrupted to protect the database. |
Choose an access mode
The access mode controls how DMS handles database credentials. Security hosting centralizes credential management so users do not interact with credentials directly, enabling fine-grained permission control.
| Access mode | How it works | When to use it |
|---|---|---|
| Security Hosting - Automatic (Recommended) | DMS enables security hosting and creates a dedicated database account automatically. The auto-created account does not have permissions to create databases or database accounts (except on ApsaraDB RDS for PostgreSQL). | ApsaraDB RDS instances where you want minimal credential management. Do not modify or delete the auto-created account. |
| Security Hosting - Manual | DMS enables security hosting. Enter an existing database account and password. | Instances where you have an existing account and want to keep using it under security hosting. |
| Security Hosting - KMS | DMS enables security hosting. Select an RDS credential stored in Key Management Service (KMS). | ApsaraDB RDS instances in environments that already manage credentials with KMS. |
| Disable Security Hosting (Not Recommended) | Security hosting is off. Users log on with a database account and password each time. | Legacy setups or cases where security hosting is not feasible. This mode limits fine-grained access control. |
Security Hosting - Automatic and Security Hosting - KMS are available for ApsaraDB RDS instances only.
If you switch from Security Hosting - Automatic to another mode and then back, DMS resets the password of the originally auto-generated account.
What's next
After registering the instance, you can:
-
Get started with SQL Console to create databases and tables, and query and modify data.
-
Use lock-free data change to modify large tables without locking them.
-
Export table data for analysis or backup.
-
Use the AddInstance API to register instances programmatically.
-
Access resources in another account or register your resources in another account's DMS using cross-account operations.
FAQ
Whitelist prompt during registration
Click Set Whitelist. DMS attempts to add its server endpoint to the database whitelist automatically. If that fails, add the ranges manually—see Add DMS IP address ranges.
Flexible Management mode availability
Yes. If you do not select Stable Change or Security Collaboration during registration, the instance defaults to Flexible Management mode.
SSL connection error after enabling TLS/SSL for Redis
Edit the instance to enable SSL in DMS:
-
Log on to the DMS console V5.0.
-
In the Database Instances pane, find the Redis instance under Not Logged On Instances. Right-click it and select Edit Instance.
-
In the Advanced Information section, enable SSL.
-
Click Test Connection, then click Save after the test succeeds.
Missing table information after registering a MaxCompute instance
Starting March 1, 2024, new MaxCompute projects no longer include the Information Schema package by default. As a project owner or a RAM user with the Super_Administrator role, install the package by running the following command in the MaxCompute client:
install package Information_Schema.systables;
For more information, see Project-level Information Schema.
For other login issues, see Log on to a database.