All Products
Search

This Product

    PolarDB:CreateDBCluster

    Document Center

    PolarDB:CreateDBCluster

    Last Updated:Sep 24, 2026

    Creates a PolarDB cluster.

    Operation description

    A DBLink can connect two PolarDB for PostgreSQL (Compatible with Oracle) clusters, or connect a PolarDB for PostgreSQL (Compatible with Oracle) cluster to a self-managed PostgreSQL database on an ECS instance. You can use DBLink to query data across clusters.

    Note

    • You can create up to 10 DBLinks for a cluster.

    • A DBLink occupies one DBLink quota on both the source cluster and the destination cluster.

    • The source cluster and the destination cluster or destination ECS instance must be in the same region.

    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

    *DBCluster

    acs:polardb:{#regionId}:{#accountId}:dbcluster/{#DbClusterId}
    • polardb:EncryptionRequired
    		 None

    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

    Valid values:

    • X86 :

      X86 architecture.

    • ARM :

      ARM architecture.

    X86
    DBType

    string

    Yes

    The type of the database engine. Valid values:

    • MySQL

    • PostgreSQL

    • Oracle

    MySQL
    DBVersion

    string

    Yes

    The database DPI engine version number.

    • Valid values for MySQL version number:

      • 5.6

      • 5.7

      • 8.0

    • Valid values for PostgreSQL version number:

      • 11

      • 14

      • 15

    Note

    To create a serverless cluster for PolarDB for PostgreSQL, only version 14 is supported.

    * Valid values for Oracle version number: * **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 clouds (VPCs) are 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: enables auto-renewal.

    • false: disables auto-renewal.

    Default value: false.

    Note

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

    true
    Period

    string

    No

    This is a required parameter to pass when PayType is set to Prepaid. Specifies the subscription type of the subscription cluster.

    • Year: annual subscription.

    • Month: monthly subscription.

    Month
    UsedTime

    string

    No

    This parameter is required when PayType is set to Prepaid.

    • If Period is set to Month, UsedTime is an integer that ranges from [1-9].

    • If Period is set to Year, UsedTime is an integer that ranges from [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 ApsaraDB RDS for MySQL 5.6, 5.7, or 8.0 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 use 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 restored cluster and the source cluster must use the same DBType. For example, if the source cluster runs MySQL 8.0, set DBType to MySQL and DBVersion to 8.0 for the restored 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. Set this parameter to the specific backup set ID.

    • Timestamp: a historical point in time. Specify the 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 token is generated by the client and must be unique among different requests. The token is case-sensitive and cannot exceed 64 ASCII characters in length.

    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 multiple 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 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.

    • 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: PolarDB 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: long-term retention (LTR) of all backups.

    • LATEST: long-term retention (LTR) of the last backup (an automatic backup is performed before deletion).

    • NONE: does not retain backups upon cluster deletion.

    When a cluster is created, the default value is NONE, which means backups are not retained upon cluster deletion.

    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 (pay-by-space) billing. 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 storage type of Standard Edition is ESSDAUTOPL, valid values are 40 to 64000 with a minimum step of 10, meaning only values such as 40, 50, 60, and so on are accepted.

    50
    DBMinorVersion

    string

    No

    The minor version of the database engine. 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 list of parameter templates in the target region, including parameter template IDs.

    pcpg-**************
    Tag

    array<object>

    No

    The list of tags.

    object

    No

    Note

    You can call the DescribeDBClusters operation to query the tags of all clusters under your account. If this parameter is left empty, the default value is false.

    Key

    string

    No

    The tag key. To add multiple tags to the target 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 target 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: enables No-activity Suspension.

    • false: disables No-activity Suspension (default).

    Note

    Only serverless clusters support this parameter.

    Valid values:

    • false :

      Disabled (default)

    • true :

      Enabled.

    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, and 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.

    Valid values:

    • EQUAL :

      Enables both the hot standby storage cluster and the hot standby compute cluster.

    • STANDBY :

      Enables the hot standby cluster.

    • 3AZ :

      Enables multi-zone strong data consistency.

    • OFF :

      Disables the hot standby cluster.

    • ON :

      Enables the hot standby storage cluster.

    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 three-zone deployment scenario.

    • OFF: Multi-zone strong data consistency is not enabled.

    Valid values:

    • OFF :

      Multi-zone strong data consistency is not enabled.

    • ON :

      Multi-zone strong data consistency is enabled. This value applies to the Standard Edition three-zone deployment scenario.

    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 Binlog feature. Valid values:

    • ON: enables the Binlog feature for the cluster.

    • OFF: disables the Binlog feature for the cluster.

    Note

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

    Valid values:

    • OFF :

      Disables the Binlog feature for the cluster.

    • ON :

      Enables the Binlog feature for the cluster.

    ON
    LooseXEngine

    string

    No

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

    • ON: enables the X-Engine storage engine for the cluster.

    • OFF: disables the X-Engine storage engine 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 the node with X-Engine enabled must be 8 GB or more.

    Valid values:

    • OFF :

      Disables the X-Engine storage engine for the cluster.

    • ON :

      Enables the X-Engine storage engine for the cluster.

    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 method for storage. Valid values:

    • Postpaid: pay-by-capacity (pay-as-you-go).

    • Prepaid: pay-by-space (subscription).

    Valid values:

    • Prepaid :

      Pay-by-space (subscription).

    • Postpaid :

      Pay-by-capacity (pay-as-you-go).

    Prepaid
    StorageAutoScale

    string

    No

    Specifies whether to enable automatic storage scaling for Standard Edition clusters. Valid values:

    • Enable: enables automatic storage scaling.

    • Disable: disables automatic storage scaling.

    Valid values:

    • Enable :

      Enables automatic storage scaling.

    • Disable :

      Disables automatic storage scaling.

    Enable
    StorageUpperBound

    integer

    No

    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 ESSD AutoPL cloud disks. Valid values:

    • true: enables I/O performance burst.

    • false: does not enable I/O performance burst (default).

    Note

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

    Valid values:

    • false :

      Does not enable I/O performance burst (default).

    • true :

      Enabled.

    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: Enabled.

    • false: Disabled (default).

    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 a custom encryption key for cloud disk encryption in the same region as the instance. If you specify this parameter, cloud disk encryption is automatically enabled and cannot be disabled. To use the default service key for cloud disk encryption, leave this parameter empty.

    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 a cross-account backup restoration scenario.

    1022xxxxxxxx
    CloudProvider

    string

    No

    The cloud service provider to which the instance belongs.

    ENS
    EnsRegionId

    string

    No

    The ID of the Edge Node Service (ENS) node. This parameter is required when you create an ENS database.

    vn-hanoi-3
    AutoUseCoupon

    boolean

    No

    Specifies whether to automatically use coupons. Valid values:

    • true (default): Uses coupons.

    • false: Does not use coupons.

    true
    PromotionCode

    string

    No

    The coupon code. If you do not specify this parameter, the default coupon is used.

    727xxxxxx934
    AgenticDbType

    string

    No

    The Agentic database engine type. Valid values:

    • dedicated

    dedicated
    AgenticDbClusterId

    string

    No

    The Agentic cluster ID.

    pagc-******
    AgenticDbClusterDescription

    string

    No

    The Agentic cluster description.

    pagc-******

    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 ID of the resource group.

    rg-***************
    AgenticDbClusterId

    string

    The Agentic cluster ID.

    pagc-***************
    AgenticDbClusterDescription

    string

    The Agentic cluster description.

    pagc-***************

    Examples

    Success response

    JSON format

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

    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.