CreateDBCluster - - Alibaba Cloud Documentation Center

This operation creates a DB cluster.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

polardb:CreateDBCluster

create

*All Resource

*

polardb:EncryptionRequired

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. Note To check available zones, call the DescribeRegions operation.	cn-hangzhou
ZoneId	string	No	The zone ID. Note To check available zones, call the DescribeRegions operation.	cn-hangzhou-j
Architecture	string	No	The CPU architecture. Valid values: X86 ARM	X86
DBType	string	Yes	The database engine. Valid values: MySQL PostgreSQL Oracle	MySQL
DBVersion	string	Yes	The version of the database engine. Valid values for MySQL: 5.6 5.7 8.0 Valid values for PostgreSQL: 11 14 15 Note To create a serverless cluster for PolarDB for PostgreSQL, set the version to 14. Valid values for Oracle: 11 14	5.6
DBNodeClass	string	No	The specifications of the node. See more below: PolarDB for MySQL: Compute node specifications. PolarDB for PostgreSQL (Oracle Compatible): Compute node specifications. PolarDB for PostgreSQL: Compute node specifications. Note To create a serverless cluster for PolarDB for MySQL Cluster Edition, set this parameter to polar.mysql.sl.small. To create a serverless cluster for PolarDB for MySQL Standard Edition, set this parameter to polar.mysql.sl.small.c.	polar.mysql.x4.medium
ClusterNetworkType	string	No	The network type of the cluster. Only VPC is supported.	VPC
DBClusterDescription	string	No	The description of the cluster. The description must meet the following requirements: It cannot start with `http://` or `https://`. It must be 2 to 256 characters in length.	test
PayType	string	Yes	The billing method. Valid values: Postpaid: pay-as-you-go. Prepaid: subscription.	Postpaid
AutoRenew	boolean	No	Specifies whether to enable auto-renewal. Valid values: true: enables auto-renewal. false: disables auto-renewal. Default value: false. Note This parameter is valid only when the PayType parameter is set to Prepaid.	true
Period	string	No	Required when the PayType parameter is set to Prepaid. Specifies the subscription type of the subscription cluster. Year: The subscription duration is measured in years. Month: The subscription duration is measured in months.	Month
UsedTime	string	No	Required when the PayType parameter is set to Prepaid. If Period is set to Month, the value of UsedTime can be an integer from 1 to `9`. If Period is set to Year, the value of UsedTime can be an integer from 1 to `3`.	1
VPCId	string	No	The ID of the virtual private cloud (VPC).	vpc-**********
VSwitchId	string	No	The ID of the vSwitch. Note If you specify a VPCId, you must also specify a VSwitchId.	vsw-**********
CreationOption	string	No	The method to create the cluster. Valid values: Normal: Creates a new PolarDB cluster. For more information, see the following documents: Create a PolarDB for MySQL cluster Create a PolarDB for PostgreSQL cluster Create a PolarDB for PostgreSQL (Oracle Compatible) cluster CloneFromPolarDB: Clones data from an existing PolarDB cluster to a new PolarDB cluster. See more below: Clone a PolarDB for MySQL cluster Clone a PolarDB for PostgreSQL cluster Clone a PolarDB for PostgreSQL (Oracle Compatible) cluster RecoverFromRecyclebin: Restores data from a released PolarDB cluster to a new PolarDB cluster. See more below: Restore a released PolarDB for MySQL cluster Restore a released PolarDB for PostgreSQL cluster Restore a released PolarDB for PostgreSQL (Oracle Compatible) cluster CloneFromRDS: Clones data from an existing ApsaraDB RDS instance to a new PolarDB cluster. For more information, see Clone an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster. MigrationFromRDS: Migrates data from an existing ApsaraDB RDS instance to a new PolarDB cluster. The created PolarDB cluster is in read-only mode and has binary logging enabled by default. See Upgrade an ApsaraDB RDS for MySQL instance to a PolarDB for MySQL cluster. CreateGdnStandby: Creates a secondary cluster. See Add a secondary cluster. UpgradeFromPolarDB: Upgrades and migrates a PolarDB cluster. See Major version upgrade. Default value: Normal. Note If DBType is set to MySQL and DBVersion is set to 8.0, this parameter can be set to CreateGdnStandby.	Normal
SourceResourceId	string	No	The ID of the source ApsaraDB RDS instance or PolarDB cluster. This parameter is required only when CreationOption is set to MigrationFromRDS, CloneFromRDS, CloneFromPolarDB, or RecoverFromRecyclebin. If CreationOption is set to MigrationFromRDS or CloneFromRDS, you must specify the ID of the source ApsaraDB RDS instance. The source ApsaraDB RDS instance must be of ApsaraDB RDS for MySQL 5.6, 5.7, or 8.0 High-availability Edition. If CreationOption is set to CloneFromPolarDB, you must specify the ID of the source PolarDB cluster. The DBType of the clone cluster is the same as the DBType of the source cluster by default. For example, if the source cluster is a MySQL 8.0 cluster, you must set DBType to MySQL and DBVersion to 8.0 for the clone cluster. If CreationOption is set to RecoverFromRecyclebin, you must specify the ID of the released source PolarDB cluster. The DBType of the cluster restored from the recycle bin must be the same as the DBType of the source cluster. For example, if the source cluster is a MySQL 8.0 cluster, you must set DBType to MySQL and DBVersion to 8.0 for the restored cluster.	rm-*************
CloneDataPoint	string	No	The point in time to which you want to clone data. Valid values: LATEST: the latest point in time. BackupID: the ID of a historical backup set. You must specify a specific backup set ID. Timestamp: a specific point in time. Specify the time in the `YYYY-MM-DDThh:mm:ssZ` format. The time must be in UTC. Default value: LATEST. Note If CreationOption is set to CloneFromRDS, this parameter can only be set to LATEST.	LATEST
ClientToken	string	No	A client token to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests. The token is case-sensitive and cannot exceed 64 ASCII characters.	6000170000591aed949d0f5********************
ResourceGroupId	string	No	The ID of the resource group.	rg-************
SecurityIPList	string	No	The IP whitelist of the PolarDB cluster. Note You can configure multiple IP addresses in the whitelist. Separate the IP addresses with commas (,).	10.*..**
TDEStatus	boolean	No	Specifies whether to enable transparent data encryption (TDE). Valid values: true: enables TDE. false: disables TDE (default). Note This parameter is valid only when DBType is set to PostgreSQL or Oracle. You can call the ModifyDBClusterTDE operation to enable TDE for a PolarDB for MySQL cluster. After TDE is enabled, it cannot be disabled.	true
GDNId	string	No	The ID of the Global Database Network (GDN). Note This parameter is required when CreationOption is set to CreateGdnStandby.	gdn-***********
CreationCategory	string	No	The edition of the cluster. Valid values: Normal: Cluster Edition (default) Basic: Single-node Edition ArchiveNormal: X-Engine Edition NormalMultimaster: Multi-master Cluster Edition SENormal: Standard Edition Note Basic is supported for PolarDB for MySQL 5.6, 5.7, and 8.0, PolarDB for PostgreSQL 14, and PolarDB for PostgreSQL (Oracle Compatible) 2.0. ArchiveNormal and NormalMultimaster are supported for PolarDB for MySQL 8.0. SENormal is supported for PolarDB for MySQL 5.6, 5.7, and 8.0 and PolarDB for PostgreSQL 14. For more information about the editions, see Editions.	Normal
DefaultTimeZone	string	No	The time zone of the cluster. The time zone must be in UTC. You can set the parameter to a value that is on the hour from -12:00 to +13:00, such as 00:00. The default value is SYSTEM, which means that the cluster uses the same time zone as the region. Note This parameter is valid only when DBType is set to MySQL.	SYSTEM
LowerCaseTableNames	string	No	Specifies whether table names are case-sensitive. Valid values: 1: case-insensitive 0: case-sensitive Default value: 1. Note This parameter is valid only when DBType is set to MySQL.	1
BackupRetentionPolicyOnClusterDeletion	string	No	The backup retention policy for the cluster when it is released. Valid values: ALL: All backups are permanently retained. LATEST: The last backup is permanently retained. An automatic backup is performed before the cluster is released. NONE: No backup sets are retained when the cluster is released. When you create a cluster, the default value is NONE, which means that no backup sets are retained when the cluster is released. Note This parameter is valid only when DBType is set to MySQL. This parameter is not supported for serverless clusters.	NONE
StorageSpace	integer	No	The storage space of the subscription cluster. This parameter is required for the subscription storage billing method. Unit: GB. Note The storage space of a PolarDB for MySQL Enterprise Edition cluster ranges from 10 GB to 50,000 GB. The storage space of a PolarDB for MySQL Standard Edition cluster ranges from 20 GB to 64,000 GB. If the storage class of the Standard Edition cluster is ESSDAUTOPL, the storage space ranges from 40 GB to 64,000 GB. The minimum step size is 10 GB. You can only enter values such as 40, 50, and 60.	50
DBMinorVersion	string	No	The minor version of the database engine. Valid values: 8.0.2 8.0.1 Note This parameter is valid only when DBType is set to MySQL and DBVersion is set to 8.0.	8.0.1
ParameterGroupId	string	No	The ID of the parameter template. Note You can call the DescribeParameterGroups operation to query the parameter templates of a specific region, including the ID of the parameter template.	pcpg-**************
Tag	array<object>	No	The list of tags.
	object	No
Key	string	No	The tag key. To add multiple tags to the cluster at a time, click Add to add tag keys. Note You can add up to 20 tags at a time. The value of `Tag.N.Key` corresponds to the value of `Tag.N.Value`.	type
Value	string	No	The tag value. To add multiple tags to the cluster at a time, click Add to add tag values. Note You can add up to 20 tags at a time. The value of `Tag.N.Value` corresponds to the value of `Tag.N.Key`.	test
ServerlessType	string	No	The type of the serverless cluster. The value is fixed as AgileServerless. Note This parameter is supported only for serverless clusters.	AgileServerless
ScaleMin	string	No	The minimum number of PolarDB Capacity Units (PCUs) for a single node. Valid values: 1 to 31. Note This parameter is supported only for serverless clusters.	1
ScaleMax	string	No	The maximum number of PCUs for a single node. Valid values: 1 to 32. Note This parameter is supported only for serverless clusters.	3
AllowShutDown	string	No	Specifies whether to enable No-activity Suspension. Valid values: true: Enable false: Disable (default) Note This parameter is supported only for serverless clusters.	true
ScaleRoNumMin	string	No	The minimum number of read-only nodes for scaling. Valid values: 0 to 15. Note This parameter is supported only for serverless clusters.	2
ScaleRoNumMax	string	No	The maximum number of read-only nodes for scaling. Valid values: 0 to 15. Note This parameter is supported only for serverless clusters.	4
StorageType	string	No	The storage class of the Enterprise Edition cluster. Valid values: PSL5 PSL4 The storage class of the Standard Edition cluster. Valid values: ESSDPL0 ESSDPL1 ESSDPL2 ESSDPL3 ESSDAUTOPL	PSL4
DBNodeNum	integer	No	The number of nodes in a Standard Edition or Enterprise Edition cluster. Valid values: Standard Edition: 1 to 8. The cluster can have one read/write node and seven read-only nodes. Enterprise Edition: 1 to 16. The cluster can have one read/write node and 15 read-only nodes. Note By default, an Enterprise Edition cluster has two nodes, and a Standard Edition cluster has one node. This parameter is supported only for PolarDB for MySQL. You cannot change the number of nodes in a Multi-master Cluster.	1
HotStandbyCluster	string	No	Specifies whether to enable the hot standby feature. Valid values: ON (default): Enables a hot standby storage cluster. OFF: Disables the hot standby cluster. STANDBY: Enables a hot standby cluster. EQUAL: Enables hot standby for both storage and computing. 3AZ: Enables strong consistency for data across multiple zones. Note STANDBY is valid only for PolarDB for PostgreSQL.	ON
StrictConsistency	string	No	Specifies whether to enable strong consistency for data across multiple zones. Valid values: ON: Enables strong consistency for data across multiple zones. This applies to Standard Edition clusters that are deployed across three zones. OFF: Disables strong consistency for data across multiple zones.	ON
StandbyAZ	string	No	The zone of the hot standby cluster. Note This parameter is valid only when the hot standby feature or strong consistency for data across multiple zones is enabled	cn-hangzhou-g
ProxyType	string	No	The type of the database proxy. Valid values: EXCLUSIVE: Dedicated Enterprise Edition GENERAL: Standard Enterprise Edition Note The proxy type must be consistent with the type of the node specifications of the cluster. Details: If the node specifications are General-purpose, the proxy type must be Standard Enterprise Edition. If the node specifications are Dedicated, the proxy type must be Dedicated Enterprise Edition.	Exclusive
ProxyClass	string	No	The specifications of the database proxy for a Standard Edition cluster. Valid values: polar.maxscale.g2.medium.c: 2 cores. polar.maxscale.g2.large.c: 4 cores. polar.maxscale.g2.xlarge.c: 8 cores. polar.maxscale.g2.2xlarge.c: 16 cores. polar.maxscale.g2.3xlarge.c: 24 cores. polar.maxscale.g2.4xlarge.c: 32 cores. polar.maxscale.g2.8xlarge.c: 64 cores.	polar.maxscale.g2.medium.c
LoosePolarLogBin	string	No	Specifies whether to enable binary logging. Valid values: ON: The cluster has binary logging enabled. OFF: The cluster has binary logging disabled. Note This parameter is valid only when DBType is set to MySQL.	ON
LooseXEngine	string	No	Specifies whether to enable the X-Engine storage engine. Valid values: ON: The cluster has the X-Engine engine enabled. OFF: The cluster has the X-Engine engine disabled. Note This parameter is valid only when CreationOption is not set to CreateGdnStandby, DBType is set to MySQL, and DBVersion is set to 8.0. The memory of a node with X-Engine enabled must be 8 GB or larger.	ON
LooseXEngineUseMemoryPct	string	No	The percentage of memory that is allocated to the X-Engine storage engine. Valid values: integers from 10 to 90. Note This parameter is valid only when LooseXEngine is set to ON.	50
StoragePayType	string	No	The billing method for storage. Valid values: Postpaid: pay-by-capacity (pay-as-you-go). Prepaid: pay-by-space (subscription).	Prepaid
StorageAutoScale	string	No	Specifies whether to enable automatic storage scaling for a Standard Edition cluster. Valid values: Enable: Enables automatic storage scaling. Disable: Disables automatic storage scaling.	Enable
StorageUpperBound	integer	No	The upper limit for automatic storage scaling of a Standard Edition cluster. Unit: GB. Note The maximum value is 32000.	800
ProvisionedIops	integer	No		1000
BurstingEnabled	string	No	Specifies whether to enable performance burst for the ESSD AutoPL disk. Valid values: true: enables performance burst. false: disables performance burst (default). Note This parameter is supported only when StorageType is set to ESSDAUTOPL.	false
TargetMinorVersion	string	No
StorageEncryption	boolean	No	Specifies whether to enable disk encryption. Valid values: true: enables disk encryption. false: disables disk encryption (default). Note This parameter is valid only when DBType is set to MySQL. Note This parameter is valid only when StorageType is a storage class of Standard Edition.
StorageEncryptionKey	string	No	The ID of a custom key for disk encryption in the same region as the instance. If you specify this parameter, disk encryption is automatically enabled and cannot be disabled. If you want to use the default service key for disk encryption, leave this parameter empty. You can view the key ID in the Key Management Service (KMS) console. You can also create a new key. Note This parameter is valid only when DBType is set to MySQL. Note This parameter is valid only when StorageType is a storage class of Standard Edition.
SourceUid	integer	No		1022xxxxxxxx

Response elements

Element	Type	Description	Example
	object
DBClusterId	string	The cluster ID.	pc-bp1s826a1up******
OrderId	string	The order ID.	211454967******
RequestId	string	The request ID.	E56531A4-E552-40BA-9C58-137B80******
ResourceGroupId	string	The resource group ID.	rg-***************

Examples

Success response

JSON format

{ "DBClusterId": "pc-bp1s826a1up******", "OrderId": "211454967******", "RequestId": "E56531A4-E552-40BA-9C58-137B80******", "ResourceGroupId": "rg-***************" }

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidBackupRetentionPolicyOnClusterDeletion.Malformed	The specified BackupRetentionPolicyOnClusterDeletion is invalid.	The specified BackupRetentionPolicyOnClusterDeletion parameter is invalid.
400	InvalidLowerCaseTableNames.Malformed	The specified LowerCaseTableNames is invalid.	The specified LowerCaseTableNames parameter is invalid.
400	InvalidDefaultTimeZone.Malformed	The specified DefaultTimeZone is invalid.	The specified DefaultTimeZone parameter is invalid.
400	Location.FailedGetSubDomain	The specified regionId does not match the zoneId or the zoneId does not exist.	The specified region ID or zone ID is invalid or the specified zone ID does not exist.
400	MissParameter.GDNId	The GDNId parameter is required.	The GDNId parameter is required.
400	EntityNotExist.ResourceGroup	The resource group does not exist..	The resource group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.