All Products
Search

This Product

    PolarDB:CreateDBCluster

    Document Center

    PolarDB:CreateDBCluster

    Last Updated:Jul 01, 2026

    Creates a PolarDB 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

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID.

    Note

    You can call the DescribeRegions operation to query available regions.

    cn-hangzhou
    ZoneId

    string

    No

    The zone ID.

    Note

    You can call the DescribeRegions operation to query available zones.

    cn-hangzhou-j
    Architecture

    string

    No

    The CPU architecture. Valid values:

    • X86

    • ARM

    X86
    DBType

    string

    Yes

    The database engine type. Valid values:

    • MySQL

    • PostgreSQL

    • Oracle

    MySQL
    DBVersion

    string

    Yes

    The database engine version.

    • 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, only version 14 is supported.

    * Valid values for Oracle: * **11** * **14**

    5.6
    DBNodeClass

    string

    No

    The node specification. For more information, see the following topics:

    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.

    • To create a serverless cluster for PolarDB for PostgreSQL Cluster Edition, set this parameter to polar.pg.sl.small.

    • To create a serverless cluster for PolarDB for PostgreSQL Standard Edition, set this parameter to polar.pg.sl.small.c.

    • To create a serverless cluster for PolarDB for PostgreSQL (Compatible with Oracle), set this parameter to polar.o.sl.small.

    polar.mysql.x4.medium
    ClusterNetworkType

    string

    No

    The network type of the cluster. Only Virtual Private Cloud (VPC) is supported. Set the value to VPC.

    VPC
    DBClusterDescription

    string

    No

    The name of the cluster. The name 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: Auto-renewal is enabled.

    • false: Auto-renewal is disabled.

    Default value: false.

    Note

    This parameter takes effect only when PayType is set to Prepaid.

    true
    Period

    string

    No

    This parameter is required when PayType is set to Prepaid. Pass this parameter to specify whether the upfront cluster uses a yearly or monthly billing cycle.

    • Year: The subscription period is measured in years.

    • Month: The subscription period is measured in months.

    Month
    UsedTime

    string

    No

    This parameter is required when PayType is set to Prepaid.

    • When Period is set to Month, the valid values of UsedTime are integers in the range of [1-9].

    • When Period is set to Year, the valid values of UsedTime are integers in the range of [1-3].

    1
    VPCId

    string

    No

    The VPC ID.

    vpc-**********
    VSwitchId

    string

    No

    The vSwitch ID.

    Note

    If you specify VPCId, you must also specify VSwitchId.

    vsw-**********
    CreationOption

    string

    No

    The method used to create the cluster. Valid values:

    Default value: Normal.

    Note

    When DBType is set to MySQL and DBVersion is set to 8.0, you can set this parameter to CreateGdnStandby.

    Normal
    SourceResourceId

    string

    No

    Instance ID of the source ApsaraDB RDS instance or the source 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, set this parameter to instance ID of the source ApsaraDB RDS instance. The source ApsaraDB RDS instance must run RDS MySQL 5.6, 5.7, or 8.0 on RDS High-availability Edition.

    • If CreationOption is set to CloneFromPolarDB, set this parameter to instance ID of the source PolarDB cluster. The cloned cluster and the source cluster have the same DBType by default. For example, if the source cluster runs MySQL 8.0, set DBType to MySQL and DBVersion to 8.0 for the cloned cluster.

    • If CreationOption is set to RecoverFromRecyclebin, set this parameter to instance ID of the released source PolarDB cluster. The recovered cluster and the source cluster must have the same DBType. For example, if the source cluster runs MySQL 8.0, set DBType to MySQL and DBVersion to 8.0 for the recovered cluster.

    rm-*************
    CloneDataPoint

    string

    No

    The point in time at which data is cloned. Valid values:

    • LATEST: The latest point in time.

    • BackupID: A historical backup set ID. Specify the actual backup set ID.

    • Timestamp: A historical point in time. Specify the actual time in the YYYY-MM-DDThh:mm:ssZ format (UTC).

    Default value: LATEST.

    Note

    If CreationOption is set to CloneFromRDS, this parameter can only be set to LATEST.

    LATEST
    ClientToken

    string

    No

    The client token that is used to ensure the idempotence of the request. The value is generated by the client and must be unique among different requests. It is case-sensitive and cannot exceed 64 ASCII characters in length.

    6000170000591aed949d0f5********************
    ResourceGroupId

    string

    No

    The resource group ID.

    rg-************
    SecurityIPList

    string

    No

    The IP addresses in the whitelist of the PolarDB cluster.

    Note

    You can specify multiple IP addresses. Separate multiple IP addresses with commas (,).

    10.***.***.***
    TDEStatus

    boolean

    No

    Specifies whether to enable Transparent Data Encryption (TDE). Valid values:

    • true: TDE is enabled.

    • false: TDE is disabled. This is the default value.

    Note

    • This parameter takes effect only when DBType is set to PostgreSQL or Oracle.

    • You can call the ModifyDBClusterTDE operation to enable TDE for a PolarDB for MySQL cluster.

    • TDE cannot be disabled after it is enabled.

    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. This is the default value.

    • Basic: Single Node Edition.

    • ArchiveNormal: X-Engine Edition.

    • NormalMultimaster: Multi-master Cluster Edition.

    • SENormal: Standard Edition.

    Note

    • MySQL 5.6, 5.7, 8.0, PostgreSQL 14, and Oracle syntax-compatible 2.0 support Basic.

    • MySQL 8.0 supports ArchiveNormal and NormalMultimaster.

    • MySQL 5.6, 5.7, 8.0, and PostgreSQL 14 support SENormal.

    For more information about editions, see Product editions.

    Normal
    DefaultTimeZone

    string

    No

    The default time zone of the cluster (UTC). The value can be any time frame within the range of -12:00 to +13:00, such as 00:00. Default value: SYSTEM, which indicates that the default time zone is the same as the time zone of the region.

    Note

    This parameter takes effect only when DBType is set to MySQL.

    SYSTEM
    LowerCaseTableNames

    string

    No

    Specifies whether table names are case-sensitive. Valid values:

    • 1: Table names are case-insensitive.

    • 0: Table names are case-sensitive.

    Default value: 1.

    Note

    This parameter takes effect only when DBType is set to MySQL.

    1
    BackupRetentionPolicyOnClusterDeletion

    string

    No

    The data retention policy applied when the cluster is deleted. Valid values:

    • ALL: All backups are retained for long-term retention (LTR).

    • LATEST: The last backup is retained for long-term retention (LTR). An automatic backup is performed before deletion.

    • NONE: No backups are retained when the cluster is deleted.

    Default value: NONE, which means no backups are retained when the cluster is deleted.

    Note

    • This parameter takes effect only when DBType is set to MySQL.

    • Serverless clusters do not support this parameter.

    NONE
    StorageSpace

    integer

    No

    The storage space for subscription billing (pay-by-space). Unit: GB.

    Note

    • Valid values for PolarDB for MySQL Enterprise Edition: 10 to 50000.

    • Valid values for PolarDB for MySQL Standard Edition: 20 to 64000.

    • When the Standard Edition storage type is ESSDAUTOPL, valid values are 40 to 64000 with a minimum step of 10. Only values such as 40, 50, 60, and so on are accepted.

    50
    DBMinorVersion

    string

    No

    The minor engine version. Valid values:

    • 8.0.2

    • 8.0.1

    Note

    This parameter takes effect 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 template list in the specified region, including the parameter template ID.

    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 tag pairs at a time. Tag.N.Key corresponds to 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 tag pairs at a time. Tag.N.Value corresponds to Tag.N.Key.

    test
    ServerlessType

    string

    No

    The serverless type. Set the value to AgileServerless (agile).

    Note

    Only serverless clusters support this parameter.

    AgileServerless
    ScaleMin

    string

    No

    The minimum scaling limit for a single node. Valid values: 1 PCU to 31 PCU.

    Note

    Only serverless clusters support this parameter.

    1
    ScaleMax

    string

    No

    The maximum scaling limit for a single node. Valid values: 1 PCU to 32 PCU.

    Note

    Only serverless clusters support this parameter.

    3
    AllowShutDown

    string

    No

    Specifies whether to enable No-activity Suspension. Valid values:

    • true: Enabled.

    • false: Disabled. This is the default value.

    Note

    Only serverless clusters support this parameter.

    true
    ScaleRoNumMin

    string

    No

    The minimum number of read-only nodes for scaling. Valid values: 0 to 15.

    Note

    Only serverless clusters support this parameter.

    2
    ScaleRoNumMax

    string

    No

    The maximum number of read-only nodes for scaling. Valid values: 0 to 15.

    Note

    Only serverless clusters support this parameter.

    4
    StorageType

    string

    No

    Valid values for Enterprise Edition storage type:

    • PSL5

    • PSL4

    Valid values for Standard Edition storage type:

    • ESSDPL0

    • ESSDPL1

    • ESSDPL2

    • ESSDPL3

    • ESSDAUTOPL

    PSL4
    DBNodeNum

    integer

    No

    The number of nodes for Standard Edition and Enterprise Edition. Valid values:

    • Standard Edition: 1 to 8 (supports 1 read/write node and 7 read-only nodes).

    • Enterprise Edition: 1 to 16 (supports 1 read/write node and 15 read-only nodes).

    Note

    • Enterprise Edition has 2 nodes by default. Standard Edition has 1 node by default.

    • Only PolarDB for MySQL supports this parameter.

    • Changing the number of nodes for Multi-master Cluster Edition clusters is not supported.

    1
    HotStandbyCluster

    string

    No

    Specifies whether to enable the hot standby cluster. Valid values:

    • ON (default): Enables the hot standby storage cluster.

    • OFF: Disables the hot standby cluster.

    • STANDBY: Enables the hot standby cluster.

    • EQUAL: Enables both the hot standby storage cluster and the hot standby compute cluster.

    • 3AZ: Enables multi-zone strong data consistency.

    Note

    STANDBY takes effect only for PolarDB for PostgreSQL.

    ON
    StrictConsistency

    string

    No

    Specifies whether multi-zone strong data consistency is enabled for the cluster. Valid values:

    • ON: Multi-zone strong data consistency is enabled. This value applies to the Standard Edition 3AZ scenario.

    • OFF: Multi-zone strong data consistency is disabled.

    ON
    StandbyAZ

    string

    No

    The zone of the hot standby cluster.

    Note

    This parameter takes effect only when the hot standby cluster or multi-zone strong data consistency 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 match the type that corresponds to the node specifications of the cluster:

    • If the node specifications are General-purpose, set the proxy type to Standard Enterprise Edition.

    • If the node specifications are Dedicated, set the proxy type to Dedicated Enterprise Edition.

    Exclusive
    ProxyClass

    string

    No

    The specification of the database proxy for Standard Edition. 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 the binary logging feature. Valid values:

    • ON: Binary logging is enabled for the cluster.

    • OFF: Binary logging is disabled for the cluster.

    Note

    This parameter takes effect only when DBType is set to MySQL.

    ON
    LooseXEngine

    string

    No

    Specifies whether to enable the X-Engine storage engine. Valid values:

    • ON: The X-Engine engine is enabled for the cluster.

    • OFF: The X-Engine engine is disabled for the cluster.

    Note

    This parameter takes effect only when CreationOption is not set to CreateGdnStandby, DBType is set to MySQL, and DBVersion is set to 8.0. The memory specification of nodes with X-Engine enabled must be 8 GB or more.

    ON
    LooseXEngineUseMemoryPct

    string

    No

    The percentage of memory allocated to the X-Engine storage engine. Valid values: integers from 10 to 90.

    Note

    This parameter takes effect only when LooseXEngine is set to ON.

    50
    StoragePayType

    string

    No

    The billing type 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 Standard Edition clusters. Valid values:

    • Enable: Automatic storage scaling is enabled.

    • Disable: Automatic storage scaling is shutdown.

    Enable
    StorageUpperBound

    integer

    No

    Sets the upper limit for automatic storage scaling of Standard Edition clusters. Unit: GB.

    Note

    The maximum value is 32000.

    800
    ProvisionedIops

    integer

    No

    1000
    BurstingEnabled

    string

    No

    Specifies whether to enable I/O performance burst for the ESSD AutoPL cloud disk. Valid values:

    • true: Enabled.

    • false: Disabled. This is the default value.

    Note

    This parameter is supported only when StorageType is set to ESSDAUTOPL.

    false
    TargetMinorVersion

    string

    No

    The target minor engine version.

    8.0.1.1.54
    StorageEncryption

    boolean

    No

    Specifies whether to enable cloud disk encryption. Valid values:

    • true: Cloud disk encryption is enabled.

    • false: Cloud disk encryption is disabled. This is the default value.

    Note

    This parameter takes effect only when DBType is set to MySQL.

    Note

    This parameter takes effect only when StorageType is set to a Standard Edition storage type.

    StorageEncryptionKey

    string

    No

    The ID of the custom encryption key for cloud disk encryption in the same region as the instance. Specifying this parameter automatically enables cloud disk encryption, which cannot be disabled after it is enabled. Leave this parameter empty to use the default service key for cloud disk encryption.

    You can view the key ID in the Key Management Service (KMS) console or create a new key.

    Note

    This parameter takes effect only when DBType is set to MySQL.

    Note

    This parameter takes effect only when StorageType is set to a Standard Edition storage type.

    1022xxxxxxxx
    SourceUid

    integer

    No

    The UID of the account that owns the source backup set in cross-account backup restoration scenarios.

    1022xxxxxxxx
    CloudProvider

    string

    No

    The cloud service provider of the instance.

    ENS
    EnsRegionId

    string

    No

    The ENS node ID required when creating an ENS database.

    vn-hanoi-3
    AutoUseCoupon

    boolean

    No

    Specifies whether to automatically use coupons. Valid values:

    • true (default): Coupons are used.

    • false: Coupons are not used.

    true
    PromotionCode

    string

    No

    The coupon code. If not specified, the default coupon is used.

    727xxxxxx934

    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-***************
    AgenticDbClusterId

    string

    AgenticDbClusterDescription

    string

    Examples

    Success response

    JSON format

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

    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.