Creating a DB Instance_GaussDB

Function

This API is used to create a GaussDB instance. GaussDB supports distributed instances. Before calling this API:

This API will be unavailable on March 31, 2025. You are advised to switch workloads to the new API (Creating a DB Instance (v3.1)) before then.

Learn how to authenticate this API.
Obtain the required region and endpoint.

URI

POST https://{Endpoint}/opengauss/v3/{project_id}/instances

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Explanation: Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None

Request Parameters

**Table 2** Request Parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Explanation: Instance name. Instances of the same type can have same names under the same tenant. Restrictions: None Value range: The value must start with a letter and contain 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Default value: None
datastore	Yes	Object	Explanation: Database information. For details, see Table 3. Restrictions: None
ha	Yes	Object	Explanation: Instance deployment model. For details, see Table 4. Restrictions: None
configuration_id	No	String	Explanation: Parameter template ID. Restrictions: None Value range: The value can contain 36 characters. Only letters and digits are allowed. Default value: If this parameter is not specified, the default parameter template is used.
port	No	String	Explanation: Database port. Restrictions: None Value range: The GaussDB database port ranges from 1024 to 39998 (excluding the following which are occupied by the system and cannot be used: 2378, 2379, 2380, 4999, 5000, 5999, 6000, 6001, 8097, 8098, 12016, 12017, 20049, 20050, 21731, 21732, 32122, 32123, and 32124). Default value: 8000
password	Yes	String	Explanation: Database password. Enter a strong password to improve security, preventing security risks such as brute force cracking. Restrictions: None Value range: The value cannot be left blank. It can consist of 8 to 32 characters, including at least three of the following: uppercase letters, lowercase letters, digits, and special characters (~!@#%^-_=+?,). Default value*: None
backup_strategy	No	Object	Explanation: Backup policy. For details, see Table 5. Restrictions: None
enterprise_project_id	No	String	Explanation: Enterprise project ID. This parameter is suitable only for enterprise tenants. Restrictions: None Value range: None Default value: None
flavor_ref	Yes	String	Explanation: Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications. Restrictions: None Value range: None Default value: None
volume	Yes	Object	Explanation: Volume information. For details, see Table 6. Restrictions: None Value range: None Default value: None
region	Yes	String	Explanation: Region ID. It indicates the region where the instance is created. For details about how to obtain the value, see Regions and Endpoints. Restrictions: None Value range: None Default value: None
availability_zone	Yes	String	Explanation: ID of the AZ where the instance is created. You can deploy your instance in the same AZ or across three different AZs, and use commas (,) to separate AZs. For example: To deploy a DB instance in the same AZ, enter three same AZ IDs. To deploy a DB instance across three different AZs, enter three different AZ IDs. For details about how to obtain the value, see Regions and Endpoints. Restrictions: None Value range: None Default value: None
vpc_id	Yes	String	Explanation: ID of the VPC where the instance is located. Method 1: Log in to the VPC console and view the VPC ID in the VPC details page. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference. Restrictions: None Value range: None Default value: None
subnet_id	Yes	String	Explanation: Network ID of the subnet where the instance is created. Method 1: Log in to VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: See section "Querying Subnets" in the Virtual Private Cloud API Reference. Restrictions: None Value range: None Default value: None
security_group_id	Yes	String	Explanation: Security group which the instance is associated with. If you do not need to specify a security group, contact customer service. Method 1: Log in to VPC console. Choose Access Control > Security Groups in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page. Method 2: Query the security group through the VPC API. For details, see Querying Security Groups. Method 2: See the section "Querying Security Groups" in the Virtual Private Cloud API Reference. Restrictions: None Value range: None Default value: None
charge_info	No	Object	Explanation: Billing type, which can only be pay-per-use. For details, see Table 7. Restrictions: None
time_zone	No	String	Explanation: UTC time zone. If this parameter is not specified, GaussDB uses UTC in the International website by default. If this parameter is specified, the value ranges from UTC-12:00 to UTC+12:00 at the full hour. For example, the parameter can be UTC+08:00 rather than UTC+08:30. Restrictions: None Value range: None Default value: None

**Table 3** datastore field data structure description
Parameter	Mandatory	Type	Description
type	Yes	String	Explanation: DB engine. Restrictions: None Value range: GaussDB Default value: None
version	No	String	Explanation: DB engine version. For details about the versions supported by GaussDB, see Querying DB Engine Versions. Restrictions: None Value range: GaussDB Default value: Latest version

**Table 4** ha field data structure description
Parameter	Mandatory	Type	Description
mode	Yes	String	Explanation: Deployment mode. Only distributed mode is supported. Restrictions: None Value range: enterprise (enterprise edition). The value is case insensitive. Default value: None
replication_mode	Yes	String	Explanation: Replication mode for the standby node. Restrictions: None Value range: sync Default value: None NOTE: sync indicates synchronous replication.
consistency	Yes	String	Explanation: Transaction consistency type. Restrictions: None Value range: strong (strong consistency) or eventual (eventual consistency). The value is case insensitive. Default value: None

**Table 5** backup_strategy field data structure description
Parameter	Mandatory	Type	Description
start_time	Yes	String	Explanation: Backup time window. The creation of an automated backup will be triggered during the backup time window. The value must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to any of the following: 00, 15, 30, or 45. Example: 08:15-09:15 23:00-00:00 Restrictions: None Value range: None Default value: None
keep_days	No	Integer	Explanation: Retention days for specific backup files. Restrictions: None Value range: [1, 732] Default value: 7

**Table 6** volume field data structure description
Parameter	Mandatory	Type	Description
type	Yes	String	Explanation: Disk type. Restrictions: None Value range: ULTRAHIGH (case-sensitive): SSD Default value: None
size	Yes	Integer	Explanation: Storage. For example, if this parameter is set to 40, 40 GB of storage is allocated to the created instance. : The value is from (Number of shards x 40 GB) to (Number of shards x 16 TB) and must be a multiple of (Number of shards x 4). Restrictions: None Value range: None Default value: None

**Table 7** chargeInfo field data structure description
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Explanation: Billing mode. Restrictions: None Value range: postPaid: pay-per-use billing Default value: None

Response Parameters

**Table 8** Response parameters
Parameter	Type	Description
instance	Object	Explanation: Instance information. For details, see Table 9.
job_id	String	Explanation: Instance creation task ID. This parameter is returned only when pay-per-use instances are created. Value range: None

**Table 9** instance description
Parameter	Type	Description
id	String	Explanation: Instance ID, which is the unique identifier of an instance. Value range: The value can contain 32 characters. Only letters and digits are allowed.
name	String	Explanation: Instance name. Instances of the same type can have same names under the same tenant. Value range: The value must start with a letter and contain 4 to 64 characters. Only letters (case-insensitive), digits, hyphens (-), and underscores (_) are allowed.
status	String	Explanation: Instance status. For example, BUILD indicates that the instance is being created. Value range: This parameter is returned only when pay-per-use instances are created.
datastore	Object	Explanation: Database information. For details, see Table 10.
ha	Object	Explanation: Database deployment model. For details, see Table 11.
replica_num	Integer	Explanation: Number of replicas. Value range: None
port	String	Explanation: Database port, which is the same as the request parameter. Value range: None
backup_strategy	Object	Explanation: Automated backup policy. For details, see Table 12.
enterprise_project_id	String	Explanation: Project ID. Value range: None
flavor_ref	String	Explanation: Specification code, which cannot be left blank. Value range: None
volume	Object	Explanation: Volume information. For details, see Table 13.
region	String	Explanation: Region ID. Value range: None
availability_zone	String	Explanation: AZ ID. Value range: None
vpc_id	String	Explanation: VPC ID. Value range: None
subnet_id	String	Explanation: Network ID of the subnet. Value range: None
security_group_id	String	Explanation: Security group which the instance is associated with. Value range: None
charge_info	Object	Explanation: Payment mode. Only pay-per-use is supported. For details, see Table 14.

**Table 10** datastore field data structure description
Parameter	Type	Description
type	String	Explanation: DB engine. Value range: GaussDB
version	String	Explanation: DB engine version. Value range: None

**Table 11** ha field data structure description
Parameter	Type	Description
mode	String	Explanation: Distributed deployment model. The value enterprise (Enterprise Edition) and is case-insensitive. Value range: None
replication_mode	String	Explanation: Replication mode for the standby node. Value range: sync NOTE: sync indicates synchronous replication.
consistency	String	Explanation: (GaussDB reserved parameter) Instance consistency type. Value range: strong (strong consistency) \| eventual (eventual consistency)

**Table 12** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Explanation: Backup time window. The creation of an automated backup will be triggered during the backup time window. The value must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to any of the following: 00, 15, 30, or 45. Example value: 08:15-09:15 23:00-00:00 If backup_strategy in the request body is left blank, 02:00-03:00 is returned for start_time by default. Value range: None
keep_days	Integer	Explanation: Retention days for specific backup files. If backup_strategy in the request body is empty, 7 is returned for keep_days by default. Value range: [1, 732]

**Table 13** volume field data structure description
Parameter	Type	Description
type	String	Explanation: Disk type. Value range: ULTRAHIGH: SSD
size	Integer	Explanation: Storage. Value range: When creating a distributed instance, you need to specify the storage to be a multiple of (Number of shards x 4 GB). Value range: (Number of shards x 40 GB) to (Number of shards x 16 TB).

**Table 14** chargeInfo field data structure description
Parameter	Type	Description
charge_mode	String	Explanation: Billing information, which is pay-per-use. Value range: None

Example Request

Creating a distributed DB instance in the independent deployment (pay-per-use billing, DB engine 1.4, single AZ, three CNs, three shards, three replicas, and 8 vCPUs and 64 GB)

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-independent-01", 
    "datastore": {
        "type": "GaussDB", 
        "version": "1.4"
    }, 
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", 
    "volume": {
        "type": "ULTRAHIGH", 
        "size": 120
    },
    "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
    "region": "aaa", 
    "availability_zone": "bbb,bbb,bbb", 
    "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", 
    "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", 
    "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", 
    "backup_strategy": {
        "start_time": "17:00-18:00", 
        "keep_days": 7
    }, 
    "charge_info": {
        "charge_mode": "postPaid"
    }, 
    "password": "xxxxxx", 
    "configuration_id": "", 
    "enterprise_project_id": "", 
    "time_zone": "UTC+08:00",
    "ha":{
        "mode":"enterprise",
        "consistency":"strong",
        "replication_mode":"sync"
    },
    "sharding_num": 3,
    "coordinator_num": 3,
    "replica_num": 3,
    "port":8000,
    "enable_force_switch":true
}

Creating a distributed DB instance in the independent deployment (one-year yearly/monthly billing, DB engine 1.4, three AZs, three CNs, three shards, three replicas, and 8 vCPUs and 64 GB)

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-independent-02", 
    "datastore": {
        "type": "GaussDB", 
        "version": "1.4"
    }, 
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", 
    "volume": {
        "type": "ULTRAHIGH", 
        "size": 120
    },
    "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
    "region": "aaa",
    "availability_zone": "bbb,ccc,ddd", 
    "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", 
    "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", 
    "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", 
    "backup_strategy": {
        "start_time": "17:00-18:00", 
        "keep_days": 7
    }, 
    "charge_info": {
        "charge_mode": "prePaid",
        "period_type": "year",
        "period_num": 1
    },
    "password": "xxxxxx", 
    "configuration_id": "", 
    "enterprise_project_id": "", 
    "time_zone": "UTC+08:00",
    "ha":{
        "mode":"enterprise",
        "consistency":"strong",
        "replication_mode":"sync"
    },
    "sharding_num": 3,
    "coordinator_num": 3,
    "replica_num": 3,
    "port":8000,
    "enable_force_switch":true
}

Creating a primary/standby (1 primary + 2 standby) DB instance (pay-per-use billing, DB engine 1.4, single AZ, 8 vCPUs and 64 GB)

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-01",
    "datastore": {
        "type": "GaussDB",
        "version": "1.4"
    },
    "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 120
    },
    "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
    "region": "aaa",
    "availability_zone": "bbb,bbb,bbb", 
    "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329",
    "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189",
    "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f",
    "backup_strategy": {
        "start_time": "17:00-18:00",
        "keep_days": 7
    },
    "charge_info": {
        "charge_mode": "postPaid",
    },
    "password": "xxxxxx",
    "configuration_id": "", 
    "enterprise_project_id": "",
    "time_zone": "UTC+08:00",
    "ha": {
        "mode": "centralization_standard",
        "consistency": "strong",
        "replication_mode": "sync"
    },
    "replica_num": 3,
    "port": 8000,
    "enable_force_switch": true
}

Creating a primary/standby (1 primary + 2 standby) DB instance (one-year yearly/monthly billing, DB engine 1.4, three AZs, 8 vCPUs and 64 GB)

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-02",
    "datastore": {
        "type": "GaussDB",
        "version": "1.4"
    },
    "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 120
    },
    "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
    "region": "aaa",
    "availability_zone": "bbb,ccc,ddd", 
    "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329",
    "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189",
    "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f",
    "backup_strategy": {
        "start_time": "17:00-18:00",
        "keep_days": 7
    },
    "charge_info": {
        "charge_mode": "prePaid",
        "period_type": "year",
        "period_num": 1
    },
    "password": "xxxxxx",
    "configuration_id": "", 
    "enterprise_project_id": "",
    "time_zone": "UTC+08:00",
    "ha": {
        "mode": "centralization_standard",
        "consistency": "strong",
        "replication_mode": "sync"
    },
    "replica_num": 3,
    "port": 8000,
    "enable_force_switch": true
}

Example Response

Creating an instance of the enterprise edition

{
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-independent",
        "status": "BUILD",
        "datastore": {
            "type": "GaussDB",
            "version": "1.4"
        },
        "ha": {
            "mode": "Enterprise",
            "replication_mode": "sync",
            "consistency": "strong"
        },
        "port": "8000",
        "volume": {
            "type": "ULTRAHIGH",
            "size": 120
        },
        "replica_num": 3,
        "backup_strategy": {
            "start_time": "17:00-18:00",
            "keep_days": 7
        },
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329",
        "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189",
        "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f",
        "charge_info": {
            "charge_mode": "postPaid"
        }
    },
    "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af"
}

Status Code

Normal
202
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Creating a DB Instance

Function

URI

Request Parameters

Response Parameters

Example Request

Example Response

Status Code

Error Code

Feedback

Was this page helpful?