tencent cloud

云数据库 MySQL

CreateDBInstanceHour

下载
聚焦模式
字号
最后更新时间: 2026-06-03 10:37:31

1. API Description

Domain name for API request: cdb.intl.tencentcloudapi.com.

This API is used to create pay-as-you-go instances. You can create a cloud database instance by inputting the instance specification, MySQL version number, quantity, etc. It supports the creation of primary instances, disaster recovery instances, and read-only instances.

This API is an async API. You can also use the API for the query (https://www.tencentcloud.com/document/api/236/15872?from_cn_redirect=1) to check the instance details. When the instance Status is 1 and TaskStatus is 0, it means the instance has been delivered successfully.

  1. First, please use the API for the query (https://www.tencentcloud.com/document/api/236/17229?from_cn_redirect=1) to obtain the purchasable specifications of cloud databases, then please use the API for the query (https://www.tencentcloud.com/document/api/236/18566?from_cn_redirect=1) to query the instance selling price.
  2. Supports a maximum of 100 instances created at a time, with a maximum duration of 36 months;
  3. Support creating MySQL 5.5, MySQL 5.6, MySQL 5.7, and MySQL 8.0 versions.
  4. Support creating primary instances, disaster recovery instances, and read-only instances.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateDBInstanceHour.
Version Yes String Common Params. The value used for this API: 2017-03-20.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
GoodsNum Yes Integer

Instance count. Default value is 1, minimum value 1, maximum value 100.

Memory Yes Integer

Instance memory size. Unit: MB. Please use the obtain the purchasable specifications of cloud databases API to obtain creatable memory specifications.

Volume Yes Integer

Instance disk size, unit: GB. Please use the obtain the purchasable specifications of cloud databases API to get the creatable disk range.

EngineVersion No String

MySQL version, including 5.5, 5.6, 5.7, and 8.0. Please use the obtain the purchasable specifications of cloud databases API to get the instance version created.
Note: When creating a non-cloud disk edition instance, specify the instance version as needed (recommend 5.7 or 8.0). If this parameter is left blank, the default value is 8.0. If creating a cloud disk edition instance, this parameter can only be set to 5.7 or 8.0.

UniqVpcId No String

VPC ID. Please use Querying VPC List.
Description: If you create a cloud disk edition instance, this item is required and must be VPC type. If this item is left blank, the system will select the default VPC by default.

UniqSubnetId No String

Subnet ID in the private network. If UniqVpcId is set up, UniqSubnetId is required. Please use query subnet list.
Description: If this item is not filled, the system will select the default subnet in the Default VPC.

ProjectId No Integer Project ID. If this is left empty, the default project will be used.
Zone No String

For availability zone information, please use the obtain the purchasable specifications of cloud databases API to get the availability zones where instances can be created.

If you create a single-node, two-node, three-node, or four-node instance, this parameter is required. Please specify an availability zone. If you do not specify one, the system will automatically select an availability zone (which may not be the one you want to deploy in). If you create a cloud disk edition instance, leave this parameter blank and configure the availability zones for read-write nodes and read-only nodes with parameter ClusterTopology.

MasterInstanceId No String

Instance ID, required when you purchase a read-only instance or disaster recovery instance. This field represents the primary instance ID of the read-only instance or disaster recovery instance. Please use the Query Instance List API to query the cloud database instance ID.

InstanceRole No String

Instance type. Supported values include: master - primary instance, dr - disaster recovery instance, ro - read-only instance.
Description: Select instance type. master is selected by default if left blank.

MasterRegion No String

Region of the primary instance. This field is required when you purchase a disaster recovery or RO instance.

Port No Integer

Custom port. Supported range: [1024-65535].
Description: If left blank, it defaults to 3306.

Password No String

Set the root account password. The password must contain 8 to 64 characters and at least two of the following: letters, digits, or characters (supported characters: _+-&=!@#$%^*()). You can specify this parameter when purchasing a primary instance. This parameter is invalid when purchasing a read-only instance or disaster recovery instance.

ParamList.N No Array of ParamInfo

Parameter list. The parameter format is ParamList.0.Name=auto_increment&ParamList.0.Value=1.

Query the configurable parameters by referring to querying the default configurable parameter list.
Note: table Name case sensitivity can be enabled or disabled with the parameter lower_case_table_names. a parameter Value of 0 means enabling, and a Value of 1 means disabling. If not set, the default Value is 0. If you create a MySQL 8.0 edition instance, you need to set the lower_case_table_names parameter when creating the instance to enable or disable table Name case sensitivity. After the instance is created, the parameter cannot be modified, meaning table Name case sensitivity cannot be changed once created. Instances of other database versions support modifying the lower_case_table_names parameter after creation. For the function invocation method to set table Name case sensitivity when creating an instance, please see examples in this document.

ProtectMode No Integer

Data replication method, defaults to 0. Supported values include: 0 - means async replication, 1 - means semi-sync replication, 2 - means strong sync replication. You can specify this parameter when purchasing a primary instance. This parameter is invalid when purchasing a read-only instance or disaster recovery instance.

DeployMode No Integer

Multiple Availability Zones, defaults to 0. Supported values include: 0 - means single availability zone, 1 - means multi-availability zone. Specify this parameter when purchasing the primary instance. This parameter is invalid when purchasing a read-only instance or disaster recovery instance.

SlaveZone No String

AZ information of standby database 1.

For two-node, three-node, or four-node instances, specify this parameter. If not specified, it defaults to the Zone value. For cloud disk edition instances, this parameter is optional. Configure the AZ for read-write and read-only nodes with parameter ClusterTopology. Single-node instances are in a single availability zone, so no need to specify this parameter.

BackupZone No String

AZ information of standby 2, empty by default.

Specify this parameter when you proceed to purchase a three-node primary instance or a four-node primary instance.

SecurityGroup.N No Array of String

Security group parameters. Use the API Query Project Security Group Information to query security group details of a certain project.

RoGroup No RoGroup

Read-only instance information. This parameter is required when you purchase a read-only instance.

AutoRenewFlag No Integer

This field is meaningless for pay-as-you-go instances.

InstanceName No String

Instance name. When you purchase multiple instances only once, suffix numbers are used for case-sensitive instance naming. For example, instanceName=db and goodsNum=3, the instance names are db1, db2, and db3 respectively.

ResourceTags.N No Array of TagInfo

Tag information of the instance.

DeployGroupId No String

Placement group ID.

ClientToken No String

String used to ensure request idempotency. This string is generated by the customer and must be unique between different requests within 48 hours, with a maximum value of 64 ASCII characters. If not specified, request idempotency cannot be guaranteed.

DeviceType No String

Instance isolation type. Supported values include: "UNIVERSAL" - general-purpose instance, "EXCLUSIVE" - dedicated instance, "BASIC_V2" - ONTKE single-node instance, "CLOUD_NATIVE_CLUSTER" - CLOUD disk edition standard type, "CLOUD_NATIVE_CLUSTER_EXCLUSIVE" - CLOUD disk edition enhanced. If not specified, it defaults to general-purpose instance.
Description: If a CLOUD disk edition instance is created, this parameter is required.

ParamTemplateId No Integer

Parameter template ID.
Remark: If you use a custom parameter template ID, you can input the custom parameter template ID. If you plan to use the default parameter template, the input ID is invalid and you need to set ParamTemplateType.

AlarmPolicyList.N No Array of Integer

Array of alarm policy IDs. OriginId returned by the Tencent Cloud observability platform DescribeAlarmPolicy API.

InstanceNodes No Integer

Number of instance nodes.

For RO and basic edition instances, the value defaults to 1. To purchase a three-node instance, set this value to 3 or specify the BackupZone parameter. When purchasing a primary instance without specifying this parameter or the BackupZone parameter, the default value is 2, which means purchasing a dual-node instance. To purchase a four-node instance, set this value to 4 or specify the FourthZone parameter.

Cpu No Integer

Number of Cpu cores of the instance.

When multiple Cpu configurations exist for the Memory specification (for example, 64000MB Memory corresponds to 8-core/16-core/32-core), the Cpu parameter must be provided.

AutoSyncFlag No Integer

Whether to automatically initiate disaster recovery sync. This parameter only takes effect when purchasing a disaster recovery instance. Available values are: 0 - Do not automatically initiate disaster recovery sync; 1 - Automatically initiate disaster recovery sync. The default is 0.

CageId No String

Financial Enclosure ID.

ParamTemplateType No String

Default parameter template type. Supported values include "HIGH_STABILITY" - HIGH-STABILITY template, "HIGH_PERFORMANCE" - HIGH-PERFORMANCE template. Default value is "HIGH_STABILITY".
Remark: If you need to use the cloud database MySQL default parameter template, set up ParamTemplateType.

AlarmPolicyIdList.N No Array of String

Alarm policy name array, such as ["policy-uyoee9wg"]. This parameter is invalid when AlarmPolicyList is not empty.

DryRun No Boolean

Whether to only pre-check this request. true: Send a check request without creating an instance. Check items include required parameters, request format, and service limits. If the check fails, return the corresponding error code; if the check passes, return RequestId. Default false: Send a normal request and create the instance directly after passing the check.

EngineType No String

Instance engine type, defaults to "InnoDB". Supported values include "InnoDB" and "RocksDB".

Vips.N No Array of String

Specify the IP list of the instance. Only the primary instance is supported. Process by instance sequence. Handle as unspecified if insufficient.

DataProtectVolume No Integer

The data protection space size of the cloud disk edition instance, in GB, has a setting range of 1 - 10.

ClusterTopology No ClusterTopology

Topology configuration for cloud disk edition nodes.
Description: If a cloud disk edition instance is purchased, this parameter is required. Set the topology for RW and RO nodes of the cloud disk edition instance. The node scope for RO nodes is 1-5. Set at least 1 RO node.

DiskType No String

Disk type. This parameter can be specified for single-node (cloud disk) or cloud disk edition instances. CLOUD_SSD means SSD Cloud Block Storage, CLOUD_HSSD means enhanced SSD cloud disk, and CLOUD_PREMIUM means high-performance cloud block storage.
Note: The supported regions for disk types of single-node (cloud disk) and cloud disk edition instances vary slightly. For specific support situation, refer to Regions and Availability Zones.

ClusterType No String

ClusterType: cage—Financial Enclosure, cdc—CDB ON CDC; dedicate—dedicated cluster

DestroyProtect No String

Turn on or off instance destruction protection. on - turn on, off - turn off.

FourthZone No String

AZ information of standby 3, empty by default. Specify this parameter when you proceed to purchase a four-node primary instance.

3. Output Parameters

Parameter Name Type Description
DealIds Array of String

Short order ID.

InstanceIds Array of String

Instance ID list.

RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Shipping

Input Example

POST / HTTP/1.1
Host: cdb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateDBInstanceHour
<Common request parameters>

{
    "GoodsNum": 1,
    "Memory": 1000,
    "Volume": 150,
    "EngineVersion": "8.0",
    "UniqVpcId": "vpc-xxxxxx",
    "UniqSubnetId": "subnet-xxxxxx",
    "ProjectId": 0,
    "Zone": "540001",
    "InstanceRole": "master",
    "Port": 3306,
    "ParamList": [
        {
            "Name": "lower_case_table_names",
            "Value": "1"
        }
    ],
    "ProtectMode": 1,
    "DeployMode": 0,
    "SlaveZone": "540001",
    "BackupZone": "0",
    "SecurityGroup": [
        "sg-xxxxx"
    ],
    "InstanceName": "xxxxxxx",
    "AlarmPolicyList": [
        -1
    ],
    "Cpu": 1,
    "ParamTemplateType": "HIGH_STABILITY",
    "EngineType": "InnoDB",
    "DestroyProtect": "off"
}

Output Example

{
    "Response": {
        "DealIds": [
            "20260330601111111111"
        ],
        "InstanceIds": [
            "cdb-xxxzz"
        ],
        "RequestId": "d30a3795-ee9e-4dc7-bf93-1e7ab751b6f5"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
CdbError Backend or process error.
FailedOperation.StatusConflict Task status conflict.
InternalError.CdbError System error.
InternalError.DatabaseAccessError Internal database error.
InternalError.DfwError Security group operation error.
InternalError.TradeError Transaction system error.
InternalError.UndefinedError Unknown error
InternalError.VpcError VPC or subnet error.
InvalidParameter Parameter error.
InvalidParameter.InstanceNotFound The instance does not exist.
OperationDenied Operation denied.
OperationDenied.ActionNotSupport Unsupported operation.
OperationDenied.OtherOderInProcess There are other orders being submitted. Please try again later.
OperationDenied.UserHasNoStrategy This account is not authorized to access the requested resource.
OperationDenied.WrongPassword Incorrect password or verification failed.

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈