CreateDBInstance

Download

Focus Mode

Font Size

Last updated: 2026-06-03 10:37:32

1. API Description

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

This API is used to create a cloud database instance with an annual/monthly subscription, including primary instance, disaster recovery instance, and read-only instance. You can create a cloud database instance by importing instance specification, MySQL version number, purchase period, and quantity information.

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

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 database price.
You can create up to 100 instances at a time, with a maximum instance duration of 36 months.
Support creating MySQL 5.5, MySQL 5.6, MySQL 5.7, and MySQL 8.0 versions.
Support creating primary instance, read-only instance, disaster recovery instance.
When ParamTemplateId or AlarmPolicyList is specified in the input parameters, you need to upgrade the SDK to the latest version to support it.

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: CreateDBInstance.
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.
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.
Period	Yes	Integer	Instance duration, measurement unit: month, optional values include [1,2,3,4,5,6,7,8,9,10,11,12,24,36].
GoodsNum	Yes	Integer	Instance count. Default value is 1, minimum value 1, maximum value 100.
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.
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. The default project is used if left empty. When you purchase a read-only instance or disaster recovery instance, the project ID is consistent with the primary instance by default.
Port	No	Integer	Custom port. Supported range: [1024-65535]. Description: If this item is left blank, it defaults to 3306.
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.
MasterInstanceId	No	String	Instance ID, required when purchasing 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.
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.
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.
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.
DeployMode	No	Integer	Multiple Availability Zones, defaults to 0. Supported values include: 0 - means single availability zone, 1 - means multi-availability zone.
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.
ParamList.N	No	Array of ParamInfo	Parameter list. The parameter format is ParamList.0.Name=auto_increment&ParamList.0.Value=1. You can query the configurable parameters by referring to querying the default configurable parameter list. Description: table Name case sensitivity can be turned on or off by setting 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 turn on or off 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 example 3 in this document.
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.
AutoRenewFlag	No	Integer	Auto-renewal flag. Available values are: 0 - no auto-renewal; 1 - auto-renewal. Default is 0.
MasterRegion	No	String	Region of the primary instance. This field is required when you purchase a disaster recovery or RO 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 parameter. This parameter is required when you purchase a read-only instance.
InstanceName	No	String	Instance name. When you purchase multiple instances only once, suffix numbers are used for case-sensitive instance naming. For example, instnaceName=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 default value is 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 is 2, meaning a dual-node instance will be purchased. 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. Remark: If you need to use TencentDB for 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 perform a pre-check only for this request. true: Send a check request without creating an instance. Check items include whether required parameters are filled, request format, and service limit. If the check fails, return the corresponding error code; if the check passes, return RequestId. false: Send a normal request and create an instance directly after the check passes. Default to false.
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 edition) 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 hard disk types of single-node (cloud disk edition) and cloud disk edition instances vary slightly. For specific support situation, refer to Regions and Availability Zones.
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	Billing sub-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 Example 1 Purchase a Primary Instance

Input Example

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

{
    "Memory": 1000,
    "Volume": 200,
    "Period": 12,
    "GoodsNum": 1,
    "Zone": "ap-guangzhou-ziyan3",
    "UniqVpcId": "vpc-grpykq9v",
    "UniqSubnetId": "subnet-aq06sf6a",
    "Port": 3306,
    "InstanceRole": "master",
    "Password": "190228bh",
    "ProtectMode": 1,
    "DeployMode": 0,
    "SlaveZone": "ap-guangzhou-ziyan3",
    "SecurityGroup": [
        "sg-9c3k3gtd"
    ],
    "InstanceName": "test_create-api2",
    "InstanceNodes": 2,
    "Cpu": 1,
    "EngineType": "InnoDB"
}

Output Example

{
    "Response": {
        "DealIds": [
            "20251117217021754844851"
        ],
        "InstanceIds": [
            "cdb-4wixd9pn"
        ],
        "RequestId": "bae642bd-305a-40fe-b64c-356dc809977b"
    }
}

Example2 Sample Code 2 Purchasing a Read-Only Instance

Input Example

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

{
    "RoGroup": {
        "RoGroupMode": "allinone",
        "RoGroupName": "jersey",
        "RoMaxDelayTime": 5,
        "MinRoInGroup": 1,
        "RoOfflineDelay": 1
    },
    "GoodsNum": 1,
    "InstanceRole": "ro",
    "MasterInstanceId": "cdb-fn3f9xpx",
    "Period": 1,
    "Volume": 100,
    "Memory": 4000
}

Output Example

{
    "Response": {
        "RequestId": "6EF60BEC-0242-43AF-BB20-270359FB54A7",
        "DealIds": [
            "20171205110051"
        ],
        "InstanceIds": [
            "cdbro-hlpl4ik9"
        ]
    }
}

Example3 Example 3 Setting Table Name Case Sensitivity When Creating an Instance

Input Example

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

{
    "Memory": 1000,
    "Volume": 25,
    "Period": 1,
    "GoodsNum": 1,
    "Zone": "ap-beijing-3",
    "UniqVpcId": "vpc-4pagx2lk",
    "UniqSubnetId": "subnet-a2eaqb1t",
    "InstanceRole": "master",
    "EngineVersion": "8.0",
    "ParamList": [
        {
            "Name": "lower_case_table_names",
            "Value": "0"
        }
    ],
    "DeviceType": "UNIVERSAL",
    "Cpu": 1,
    "EngineType": "InnoDB"
}

Output Example

{
    "Response": {
        "RequestId": "6166b535-64e8-4372-86fc-d6e25791f4fc",
        "InstanceIds": [
            "cdb-grq113rc"
        ],
        "DealIds": [
            "20250519054092411681521"
        ]
    }
}

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

Tencent Cloud CLI 3.0

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.CauthError	Authentication failed.
InternalError.CdbError	System error.
InternalError.DatabaseAccessError	Internal database error.
InternalError.DfwError	Security group operation error.
InternalError.FtpError	File transfer exception
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.

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

TencentDB for MySQL

CreateDBInstance

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Example1 Example 1 Purchase a Primary Instance

Input Example

Output Example

Example2 Sample Code 2 Purchasing a Read-Only Instance

Input Example

Output Example

Example3 Example 3 Setting Table Name Case Sensitivity When Creating an Instance

Input Example

Output Example

5. Developer Resources

SDK

Command Line Interface

6. Error Code

Help and Support