Queries information about all PolarDB clusters or specified PolarDB clusters that you can access.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeDBClusters

The operation that you want to perform. Set the value to DescribeDBClusters.

RegionId String Yes cn-hangzhou

The region ID of the cluster.

Note You can call the DescribeRegions operation to query information about regions.
DBClusterIds String No pc-****************

The IDs of the clusters. Separate cluster IDs with commas (,).

DBClusterDescription String No pc-****************

The description of clusters. You can specify keywords to implement fuzzy match.

DBClusterStatus String No Running

The state of the clusters that you want to query. For information about valid values, see Cluster status.

DBType String No MySQL

The database engine that databases in the clusters run. Valid values:

  • MySQL
  • PostgreSQL
  • Oracle
PageSize Integer No 30

The number of entries to return on each page. Valid values: 30, 50, or 100.

Default value: 30.

PageNumber Integer No 10

The number of the page to return. The value of this parameter must be an integer that is greater than 0. Default value: 1.

ResourceGroupId String No rg-**********

The ID of the resource group.

PayType String No Postpaid

The billing method. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
DBNodeIds String No pi-***************

The ID of the node. You can specify multiple node IDs. Separate multiple node IDs with commas (,).

Tag.N.Key String No MySQL

The keys of the tags. You can use tags to filter clusters. You can specify up to 20 tags. N specifies the serial number of each tag. The values that you specify for N must be unique and be consecutive integers that start from 1. The values of the Tag.N.Key parameter and the values of the Tag.N.Value parameter must be from the same key-value pairs.

Note The value of this parameter can be up to 64 characters in length and cannot start with aliyun, acs:, http://, or https://.
Tag.N.Value String No 5.6

The values of the tags.

Note The value of this parameter can be up to 64 characters in length and cannot start with aliyun, acs:, http://, or https://.

Response parameters

Parameter Type Example Description
TotalRecordCount Integer 16

The total number of entries.

PageRecordCount Integer 5

The number of clusters returned per page.

RequestId String 9B7BFB11-C077-4FE3-B051-F69CEB******

The ID of the request.

PageNumber Integer 12

The number of returned pages.

Items Array of DBCluster

Details about the returned clusters.

DBCluster
VpcId String vpc-****************

The ID of the virtual private cloud (VPC).

ExpireTime String 2020-11-14T16:00:00Z

The time when the cluster expires.

Note Expiration time is returned only for clusters that use the subscription billing method. An empty string is returned for clusters that use the pay-as-you-go billing method.
Expired String false

Indicates whether the cluster has expired. Valid values:

Note This parameter is returned only for clusters that use the subscription billing method.
DBNodeNumber Integer 2

The number of nodes.

CreateTime String 2020-08-14T05:58:42Z

The time when the cluster was created.

PayType String Prepaid

The billing method. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: the subscription billing method
DBNodeClass String polar.mysql.x4.large

The instance type of the node.

Tags Array of Tag

Details about the returned tags.

Tag
Key String MySQL

The key of the tag.

Value String 5.6

The value of the tag.

DBType String MySQL

The database engine that databases in the clusters run.

LockMode String Unlock

The state of the cluster lock. Valid values:

  • Unlock: The instance is not locked.
  • ManualLock: The cluster is manually locked.
  • LockByExpiration: The cluster is automatically locked because the cluster has expired.
DBNodes Array of DBNode

Details about nodes.

DBNode
DBNodeClass String polar.mysql.x4.large

The instance type of the node.

ZoneId String cn-hangzhou-i

The ID of the zone.

DBNodeRole String Reader

The role of the node. Valid values:

  • Writer: The node is the primary node.
  • Reader: The node is a read-only node.
DBNodeId String pi-****************

The ID of the node.

RegionId String cn-hangzhou

The region ID of the cluster.

RegionId String cn-hangzhou

The region ID of the cluster.

DeletionLock Integer 0

The protection state of the cluster. Valid values:

  • 0: The cluster is not locked.
  • 1: The cluster is locked.
    Note You cannot delete the cluster if the cluster is locked.
DBVersion String 5.6

The version of the database engine that databases in the clusters run.

DBClusterId String pc-****************

The IDs of the clusters.

DBClusterStatus String Running

The status of the cluster.

ResourceGroupId String rg-************

The ID of the resource group.

StorageUsed Long 3009413120

The storage space used by the cluster.

DBClusterNetworkType String VPC

The network type of the cluster.

DBClusterDescription String GDN-1

The description of the cluster.

ZoneId String cn-hangzhou-i

The ID of the zone.

Engine String POLARDB

The database engine that databases in the cluster run.

Category String Normal

The edition of the cluster. Valid values:

  • Normal: Cluster Edition
  • Basic: Single Node
  • Archive: Archive Database

Examples

Sample requests

http(s)://polardb.aliyuncs.com/?Action=DescribeDBClusters
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDBClustersResponse>
    <TotalRecordCount>16</TotalRecordCount>
    <PageRecordCount>5</PageRecordCount>
    <RequestId>9B7BFB11-C077-4FE3-B051-F69CEB******</RequestId>
    <PageNumber>12</PageNumber>
    <Items>
        <VpcId>vpc-****************</VpcId>
        <ExpireTime>2020-11-14T16:00:00Z</ExpireTime>
        <Expired>false</Expired>
        <DBNodeNumber>2</DBNodeNumber>
        <CreateTime>2020-08-14T05:58:42Z</CreateTime>
        <PayType>Prepaid</PayType>
        <DBNodeClass>polar.mysql.x4.large</DBNodeClass>
        <Tags>
            <Key>MySQL</Key>
            <Value>5.6</Value>
        </Tags>
        <DBType>MySQL</DBType>
        <LockMode>Unlock</LockMode>
        <DBNodes>
            <DBNodeClass>polar.mysql.x4.large</DBNodeClass>
            <ZoneId>cn-hangzhou-i</ZoneId>
            <DBNodeRole>Reader</DBNodeRole>
            <DBNodeId>pi-****************</DBNodeId>
            <RegionId>cn-hangzhou</RegionId>
        </DBNodes>
        <RegionId>cn-hangzhou</RegionId>
        <DeletionLock>0</DeletionLock>
        <DBVersion>5.6</DBVersion>
        <DBClusterId>pc-****************</DBClusterId>
        <DBClusterStatus>Running</DBClusterStatus>
        <ResourceGroupId>rg-************</ResourceGroupId>
        <StorageUsed>3009413120</StorageUsed>
        <DBClusterNetworkType>VPC</DBClusterNetworkType>
        <DBClusterDescription>GDN-1</DBClusterDescription>
        <ZoneId>cn-hangzhou-i</ZoneId>
        <Engine>POLARDB</Engine>
        <Category>Normal</Category>
    </Items>
</DescribeDBClustersResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalRecordCount" : 16,
  "PageRecordCount" : 5,
  "RequestId" : "9B7BFB11-C077-4FE3-B051-F69CEB******",
  "PageNumber" : 12,
  "Items" : [ {
    "VpcId" : "vpc-****************",
    "ExpireTime" : "2020-11-14T16:00:00Z",
    "Expired" : "false",
    "DBNodeNumber" : 2,
    "CreateTime" : "2020-08-14T05:58:42Z",
    "PayType" : "Prepaid",
    "DBNodeClass" : "polar.mysql.x4.large",
    "Tags" : [ {
      "Key" : "MySQL",
      "Value" : "5.6"
    } ],
    "DBType" : "MySQL",
    "LockMode" : "Unlock",
    "DBNodes" : [ {
      "DBNodeClass" : "polar.mysql.x4.large",
      "ZoneId" : "cn-hangzhou-i",
      "DBNodeRole" : "Reader",
      "DBNodeId" : "pi-****************",
      "RegionId" : "cn-hangzhou"
    } ],
    "RegionId" : "cn-hangzhou",
    "DeletionLock" : 0,
    "DBVersion" : "5.6",
    "DBClusterId" : "pc-****************",
    "DBClusterStatus" : "Running",
    "ResourceGroupId" : "rg-************",
    "StorageUsed" : 3009413120,
    "DBClusterNetworkType" : "VPC",
    "DBClusterDescription" : "GDN-1",
    "ZoneId" : "cn-hangzhou-i",
    "Engine" : "POLARDB",
    "Category" : "Normal"
  } ]
}

Error codes

HttpCode Error codes Error message Description
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an internal error has occurred.
503 ServiceUnavailable The request has failed due to a temporary failure of the server. The error message returned because a temporary server failure has occured.

For a list of error codes, visit the API Error Center.