Querying DB Instances
Function
This API is used to query DB instances according to search criteria.
- Before calling an API, you need to understand the API in Authentication.
URI
- URI format
GET /v3/{project_id}/instances?id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}&tags={key}={value}
- Parameter description
Table 1 Parameter description Name
Type
Mandatory
Description
project_id
String
Yes
Explanation:
Project ID of a tenant in a region.
For details about how to obtain the project ID, see Obtaining a Project ID.
Constraints:
N/A
Value range:
N/A
Default value:
N/A
id
String
No
Explanation:
Instance ID.
The asterisk (*) is reserved for the system. If the instance ID starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance ID. The value cannot contain only asterisks (*).
Constraints:
N/A
Value range:
N/A
Default value:
N/A
name
String
No
Explanation:
Instance name.
The asterisk (*) is reserved for the system. If the instance name starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance name. The value cannot contain only asterisks (*).
Constraints:
N/A
Value range:
N/A
Default value:
N/A
type
String
No
Explanation:
Instance type.
Constraints:
N/A
Value range:
- Single: single-node instance
- Ha: primary/standby instance
- Replica: read replica
- Enterprise: distributed instance (Enterprise Edition)
Default value:
N/A
datastore_type
String
No
Explanation:
DB engine.
Constraints:
The value is case-sensitive.
Value range:
- MySQL
- PostgreSQL
- SQLServer
Default value:
N/A
vpc_id
String
No
Explanation:
VPC ID. To obtain this parameter value, use either of the following methods:
- Method 1: Log in to VPC console and view the VPC ID in the VPC details.
- Method 2: See the "Querying VPCs" section in the Virtual Private Cloud API Reference.
Constraints:
N/A
Value range:
N/A
Default value:
N/A
subnet_id
String
No
Explanation:
Subnet ID. To obtain this parameter value, use either of the following methods:
- Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.
- Method 2: See the "Querying Subnets" section in the Virtual Private Cloud API Reference.
Constraints:
N/A
Value range:
N/A
Default value:
N/A
offset
Integer
No
Explanation:
Index offset. The query starts from the next piece of data indexed by this parameter.
Constraints:
The value must be a non-negative number.
Value range:
An integer greater than or equal to 0
Default value:
0
limit
Integer
No
Explanation:
Number of records to be queried.
Constraints:
N/A
Value range:
The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100.
Default value:
100
tags
Array of objects
No
Explanation:
Tag key-value pairs of the instance.
- {key} indicates the tag key. It must be unique and cannot be empty.
- {value} indicates the tag value, which can be left empty.
To query instances with multiple tag keys and values, separate key-value pairs with commas (,). A maximum of 10 key-value pairs are supported.
For details, see Table 2.
Constraints:
N/A
Value range:
N/A
Default value:
N/A
Table 2 tags field data structure description Name
Type
Mandatory
Description
key
String
Yes
Explanation:
Tag key.
Constraints:
N/A
Value range:
It must consist of 1 to 128 Unicode characters.
It can contain letters, digits, spaces, and special characters _.:=+-@. However, it cannot start or end with a space, or start with _sys_.
Default value:
N/A
value
String
No
Explanation:
Tag value.
Constraints:
N/A
Value range:
It can be left blank or contain a maximum of 255 Unicode characters.
It can contain letters, digits, spaces, and special characters _.:=+-@.
Default value:
N/A
Request
- URI example
- Querying all DB instances
GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances
- Querying DB instances based on search criteria
GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10&tags=rds001=001,rds002=002
- Querying all DB instances
Response
- Normal response
Table 3 Parameter description Name
Type
Description
instances
Array of objects
Explanation:
Indicates the DB instance information.
For details, see Table 4.
total_count
Integer
Explanation:
Indicates the total number of records.
Value range:
N/A
Table 4 instances field data structure description Name
Type
Description
id
String
Explanation:
Indicates the DB instance ID.
Value range:
N/A
name
String
Explanation:
Indicates the created DB instance name.
Value range:
N/A
status
String
Explanation:
Indicates the DB instance status.
Value range:
- BUILD: The instance is being created.
- CREATE FAIL: The instance failed to be created.
- ACTIVE: The instance is running properly.
- FAILED: The instance is abnormal.
- FROZEN: The instance is frozen.
- MODIFYING: The instance is being scaled out.
- REBOOTING: The instance is being rebooted.
- RESTORING: The instance is being restored.
- MODIFYING INSTANCE TYPE: The instance is changing from single to primary/standby.
- SWITCHOVER: The instance is performing a primary/standby switchover.
- MIGRATING: The instance is being migrated.
- BACKING UP: The instance is being backed up.
- MODIFYING DATABASE PORT: The database port is being changed.
- STORAGE FULL: The instance storage space is full.
alias
String
Explanation:
Indicates the DB instance alias.
Value range:
N/A
private_ips
List<String>
Explanation:
Indicates the private IP address list. It is a blank string until an ECS is created.
Value range:
N/A
private_dns_names
List<String>
Explanation:
Indicates the private domain name list of the DB instance. After a DB instance is created, you need to manually apply for a private domain name, or the private domain name is left blank.
Value range:
N/A
public_dns_names
List<String>
Explanation:
Indicates the public domain name list of the DB instance. Currently, only RDS for SQL Server supports public domain names. After a DB instance is created, you need to manually apply for a public domain name, or the public domain name is left blank.
Value range:
N/A
public_ips
List<String>
Explanation:
Indicates the public IP address list.
Value range:
N/A
port
Integer
Explanation:
Indicates the database port number.
Value range:
- RDS for MySQL instances can use database ports 1024 to 65535, excluding 12017 and 33071, which are reserved for RDS system use.
- RDS for PostgreSQL instances can use database ports 2100 to 9500.
- For RDS for SQL Server 2022 Enterprise Edition, 2022 Standard Edition, 2022 Web Edition, 2019 Enterprise Edition, 2019 Standard Edition, 2019 Web Edition, 2017 Enterprise Edition, 2017 Standard Edition, and 2017 Web Edition, the port number can be set to 1433 or 2100 to 9500 (excluding 5050, 5353, 5355, 5985, and 5986).
For other editions, the port number can be set to 1433 or 2100 to 9500 (excluding 5355, 5985, and 5986).
If this parameter is not set, the default value is as follows:
- RDS for MySQL: 3306
- RDS for PostgreSQL: 5432
- RDS for SQL Server: 1433
enable_ssl
Boolean
Explanation:
Indicates whether SSL is enabled for the instance.
Value range:
- true: SSL is enabled for the instance.
- false: SSL is disabled for the instance.
type
String
Explanation:
Instance type.
Value range:
- Single: single-node instance
- Ha: primary/standby instance
- Replica: read replica
- Enterprise: distributed instance (Enterprise Edition)
ha
Object
Explanation:
Indicates the primary/standby DB instance information. Returned only when you obtain a primary/standby DB instance list.
For details, see Table 5.
region
String
Explanation:
Indicates the region where the DB instance is deployed.
Value range:
N/A
datastore
Object
Explanation:
Indicates the database information.
For details, see Table 6.
created
String
Explanation:
Indicates the creation time.
Value range:
The value is in the "yyyy-mm-ddThh:mm:ssZ" format.
T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.
The value is empty when the instance is being created. After the instance is created, the value is not empty.
updated
String
Explanation:
Indicates the update time.
Value range:
The format is the same as that of the created field.
The value is empty when the instance is being created. After the instance is created, the value is not empty.
db_user_name
String
Explanation:
Indicates the default username.
Value range:
N/A
vpc_id
String
Explanation:
Indicates the VPC ID.
Value range:
N/A
subnet_id
String
Explanation:
Indicates the network ID of the subnet.
Value range:
N/A
security_group_id
String
Explanation:
Indicates the security group ID.
Value range:
N/A
flavor_ref
String
Explanation:
Indicates the specification code.
Value range:
N/A
cpu
String
Explanation:
Indicates the number of vCPUs. For example, the value 1 indicates 1 vCPU.
Value range:
N/A
mem
String
Explanation:
Indicates the memory size in GB.
Value range:
N/A
volume
Object
Explanation:
Indicates instance storage.
For details, see Table 7.
switch_strategy
String
Explanation:
Indicates the database failover priority.
Value range:
- reliability: Reliability is given priority during the failover.
- availability: Availability is given priority during the failover.
read_only_by_user
Boolean
Explanation:
Indicates the read-only status of the DB instance. This parameter is available only to RDS for MySQL.
Value range:
- true: indicates that the DB instance is set to read-only.
- false: indicates that the DB instance is set to read/write.
backup_strategy
Object
Explanation:
Indicates the backup policy.
For details, see Table 8.
maintenance_window
String
Explanation:
Indicates the start time of the maintenance time window in the UTC format.
Value range:
N/A
nodes
Array of objects
Explanation:
Indicates the primary/standby DB instance information.
For details, see Table 9.
related_instance
Array of objects
Explanation:
Indicates all associated DB instances.
For details, see Table 10.
disk_encryption_id
String
Explanation:
Indicates the disk encryption key ID.
Value range:
N/A
enterprise_project_id
String
Explanation:
Indicates the enterprise project ID.
Value range:
N/A
time_zone
String
Explanation:
Indicates the time zone.
Value range:
N/A
charge_info
Object
Explanation:
Indicates the billing information, which is yearly/monthly or pay-per-use. By default, pay-per-use is used.
For details, see Table 11.
tags
Array of objects
Explanation:
Indicates the tag list. If there is no tag in the list, an empty array is returned.
For details, see Table 13.
backup_used_space
Double
Explanation:
Indicates the backup space usage in GB.
This field is returned only when you query information about a specified RDS for PostgreSQL or RDS for SQL Server DB instance.
Value range:
N/A
storage_used_space
Double
Explanation:
Indicates the storage space usage in GB.
This field is returned only when you query information about a specified RDS for PostgreSQL or RDS for SQL Server DB instance.
Value range:
N/A
order_id
String
Explanation:
Indicates the order ID. This field is returned only when the DB instance is billed on a yearly/monthly basis.
Value range:
N/A
associated_with_ddm
Boolean
Explanation:
Indicates whether a DDM instance has been associated.
Value range:
N/A
max_iops
Long
Explanation:
Indicates the maximum disk IOPS of the instance.
This field is returned only for RDS for SQL Server instances.
Value range:
N/A
expiration_time
String
Explanation:
Indicates the time when an instance expires. The format is yyyy-mm-ddThh:mm:ssZ.
This field is returned only for yearly/monthly instances.
Value range:
N/A
serverless_info
Object
Explanation:
Indicates the compute power range of a serverless instance, in RCU.
For details, see Table 12.
Table 5 ha field data structure description Name
Type
Description
replication_mode
String
Explanation:
Indicates the replication mode for the standby instance.
Value range:
- For RDS for MySQL, the value is async or semisync.
- For RDS for PostgreSQL, the value is async or sync.
- For RDS for SQL Server, the value is sync.
NOTE:- async indicates the asynchronous replication mode.
- semisync indicates the semi-synchronous replication mode.
- sync indicates the synchronous replication mode.
Table 6 datastore field data structure description Name
Type
Description
type
String
Explanation:
Indicates the DB engine. Its value can be any of the following and is case-insensitive:
Value range:
- MySQL
- PostgreSQL
- SQLServer
version
String
Explanation:
Indicates the database version.
Value range:
N/A
complete_version
String
Explanation:
Indicates the complete version number. This parameter is returned only when the DB engine is MySQL or PostgreSQL.
Value range:
N/A
Table 7 volume field data structure description Name
Type
Description
type
String
Explanation:
Storage type. The value is case-sensitive.
Value range:- COMMON: SATA storage.
- HIGH: SAS storage.
- ULTRAHIGH: ultra-high I/O storage.
- ULTRAHIGHPRO: ultra-high I/O (advanced) storage. This storage type is supported only with ultra-high performance (advanced) instances.
- CLOUDSSD: cloud SSD storage. This storage type is supported only with general-purpose and dedicated instances.
- LOCALSSD: local SSD storage.
- ESSD: extreme SSD storage. This storage type is supported only with dedicated instances.
size
Integer
Explanation:
Storage space in GB.
Value range:
N/A
Table 8 backup_strategy field data structure description Name
Type
Description
start_time
String
Explanation:
Indicates the backup time window. Automated backups will be triggered during the backup time window.
The time is in the UTC format.
Value range:
N/A
keep_days
Integer
Explanation:
Indicates the number of days to retain the generated backup files.
Value range:
0–732 If the value is 0, the automated backup policy is not configured or has been disabled. To extend the retention period, contact customer service. Automated backups can be retained for up to 2,562 days.
Table 9 nodes field data structure description Name
Type
Description
id
String
Explanation:
Indicates the node ID.
Value range:
N/A
name
String
Explanation:
Indicates the node name.
Value range:
N/A
role
String
Explanation:
Indicates the node type.
Value range:
- master: primary node
- slave: standby node
- readreplica: read replica node
status
String
Explanation:
Indicates the node status.
availability_zone
String
Explanation:
Indicates the AZ.
Value range:
N/A
Table 10 related_instance field data structure description Name
Type
Description
id
String
Explanation:
ID of the associated DB instance.
Value range:
N/A
type
String
Explanation:
Type of the associated DB instance.
Value range:
- replica_of: indicates a primary DB instance.
- replica: indicates a read replica.
Table 11 chargeInfo field data structure description Name
Mandatory
Type
Description
charge_mode
Yes
String
Explanation:
Indicates the billing mode.
Value range:
- prePaid: indicates the yearly/monthly billing mode.
- postPaid: indicates the pay-per-use billing mode.
Table 12 Data structure of the serverless_info field Parameter
Mandatory
Type
Description
min_compute_unit
Yes
String
Explanation:
Minimum compute power of a serverless instance, in RCU.
Value range:
0.5–8, in RCU
max_compute_unit
Yes
String
Explanation:
Maximum compute power of a serverless instance, in RCU.
Value range:
0.5–8, in RCU
Table 13 tags field data structure description Name
Type
Description
key
String
Explanation:
Indicates the tag key.
Value range:
N/A
value
String
Explanation:
Indicates the tag value.
Value range:
N/A
The values of region and availability_zone are used as examples.
- Example normal response
Query DB instances based on search criteria.
{ "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }], "total_count": 1 }
- Query all DB instances.
{ "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "enable_ssl": false, "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }, { "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02", "status": "ACTIVE", "name": "mysql-0820-022709-02", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }], "total_count": 2 } - Query serverless DB instances.
{ "instances": [ { "id": "06f4bde8fec442d7bb122f742c9e51dein01", "status": "ACTIVE", "name": "rds-4961", "port": 3306, "type": "Ha", "ha": { "replication_mode": "semisync" }, "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2023-10-24T03:10:28+0000", "updated": "2023-10-24T03:10:28+0000", "volume": { "type": "CLOUDSSD", "size": 40 }, "nodes": [ { "id": "0c4844b1323e4f30a7a49b021a047e36no01", "name": "rds-4961_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }, { "id": "62bb9a79e2c34c369845ede701a4cf34no01", "name": "rds-4961_node1", "role": "slave", "status": "ACTIVE", "availability_zone": "bbb" } ], "tags": [], "bpDomainId": "", "bpType": "Default", "alias": "", "private_ips": [], "private_dns_names": [ "0aabbcc.mysql.rds.myhuaweicloud.com" ], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "a70b5818-a306-426d-a53e-11b6b57c31af", "subnet_id": "7cac9cc5-7b87-414e-9913-cbbc5051347e", "security_group_id": "89f258c5-4b81-4ef0-be30-34f2ee07dd1c", "flavor_ref": "rds.mysql.serverless.ha", "switch_strategy": "reliability", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "18:00-22:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "UTC+08:00", "order_id": "", "associated_with_ddm": false, "serverless_info": { "max_compute_unit": "0.5", "min_compute_unit": "8" } } ], "total_count": 1 } - Abnormal response
For details, see Abnormal Request Results.
Status Code
- Normal
- Abnormal
For details, see Status Codes.
Error Code
For details, see Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot
