Help Center/ GaussDB/ API Reference/ Historical APIs/ DB Instance Management/ Creating a DB Instance
Updated on 2025-08-18 GMT+08:00
View PDF

Creating a DB Instance

Function

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

URI

POST https://{Endpoint}/v3.1/{project_id}/instances
Table 1 Parameter description

Name

Mandatory

Description

project_id

Yes

Explanation:

Project ID of a tenant in a region.

For details about how to obtain the value, 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

Instance name.

Instances of the same type can have same names under the same tenant.

The name must consist of 4 to 64 characters and start with a letter. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

datastore

Yes

Object

Database information.

For details, see Table 3.

ha

Yes

Object

Instance deployment model. For details, see Table 4.

configuration_id

No

String

Parameter template ID. If this parameter is not specified, the default parameter template is used and this parameter is not returned in the response body.

port

No

String

Port number used by the database to provide services for external systems. If you do not configure this parameter, the default value 8000 is used. Value range: 1024 to 39998. The following ports are not allowed: 2378, 2379, 2380, 4999, 5000, 5999, 6000, 6001, 8097, 8098, 12016, 12017, 20049, 20050, 21731, 21732, 32122, 32123, and 32124.

password

Yes

String

Database password.

The password must:

Consist of 8 to 32 characters, including at least three of the following: uppercase letters, lowercase letters, digits, and special characters (~!@#%^*-_=+?,).

Enter a strong password to improve security, preventing security risks such as brute force cracking.

backup_strategy

No

Object

Backup policy.

For details, see Table 5.

enterprise_project_id

No

String

Enterprise project ID. This parameter is suitable only for enterprise tenants.

flavor_ref

Yes

String

Specification code. The value cannot be left blank. To obtain its value, see the spec_code field in Querying Instance Specifications.

volume

Yes

Object

Volume information.

For details, see Table 6.

region

Yes

String

Region ID.

availability_zone

Yes

String

AZ ID.

The value cannot be left blank. You can deploy a GaussDB instance in the same AZ or different AZs, and use commas (,) to separate AZs.

vpc_id

Yes

String

VPC ID. To obtain this parameter value, use either of the following methods:

  • Method 1: Log in to the VPC console and view the VPC ID in the VPC details page.
  • Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

subnet_id

Yes

String

Network ID of the subnet. To obtain this parameter value, use either of the following methods:

  • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.
  • Method 2: Query the subnet ID through the VPC API. For details, see Querying Subnets.

security_group_id

Yes

String

Security group which the instance is associated with.

  • Method 1: Log in to the VPC console. Choose Access Control > Security Groups in the navigation pane. 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.

charge_info

No

Object

Billing mode.

For details, see Table 7.

os_type

No

String

OS type. The default value is Euler, which is case sensitive.

Values:

  • Euler
  • Hce: Huawei Cloud EulerOS 2.0.
Table 3 datastore field data structure description

Parameter

Mandatory

Type

Description

type

Yes

String

DB engine. Value:

GaussDB. It is case-insensitive.

version

No

String

DB engine version. If this parameter is not specified, the latest version is used by default.
Table 4 ha field data structure description

Parameter

Mandatory

Type

Description

mode

Yes

String

Deployment model. The value is case-insensitive and can be enterprise (enterprise edition) for distributed instances and centralization_standard for centralized instances.

consistency

Yes

String

Transaction consistency type. The value is case-insensitive and can be:

  • strong: strong consistency
  • eventual: eventual consistency

replication_mode

Yes

String

Replication mode for the standby node. The value can only be set to sync, indicating that data is synchronized in synchronous mode.
Table 5 backup_strategy field data structure description

Parameter

Mandatory

Type

Description

start_time

Yes

String

Backup time window. The creation of an automated backup will be triggered during the backup time window.

The value cannot be left blank or negative. It 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 00.

Example value:

  • 08:00-09:00
  • 23:00-00:00

keep_days

No

Integer

Retention days for specific backup files.

Value: 1 to 36500.
Table 6 volume field data structure description

Parameter

Mandatory

Type

Description

type

Yes

String

Disk type.

size

Yes

Integer

Storage. For example, if this parameter is set to 40, 40 GB of storage is allocated to the created instance.

ECS deployment: The value is from (Number of shards x 40 GB) to (Number of shards x 24 TB) and must be a multiple of (Number of shards x 4 GB).
Table 7 chargeInfo field data structure description

Parameter

Mandatory

Type

Description

charge_mode

Yes

String

Billing mode.

Response Parameters

Table 8 Response parameters

Parameter

Type

Description

instance

Object

Instance information.

For details, see Table 9.

job_id

String

Instance creation task ID.
Table 9 instance description

Parameter

Type

Description

id

String

Instance ID.

name

String

Instance name. Instances of the same type can have same names under the same tenant.

The value must consist of 4 to 64 characters and start with a letter. Only letters (case-insensitive), digits, hyphens (-), and underscores (_) are allowed.

status

String

Instance status. For example, BUILD indicates that the instance is being created.

datastore

Object

Database information.

For details, see Table 10.

ha

Object

Database deployment model.

For details, see Table 11.

replica_num

Integer

Number of replicas.

port

String

Database port, which is the same as the request parameter.

backup_strategy

Object

Automated backup policy.

For details, see Table 12.

flavor_ref

String

Specification code. The value cannot be left blank.

volume

Object

Volume information.

For details, see Table 13.

region

String

Region ID.

availability_zone

String

AZ ID.

vpc_id

String

VPC ID.

subnet_id

String

Network ID of the subnet.

security_group_id

String

Security group which the instance is associated with.

charge_info

Object

Payment mode.

For details, see Table 14.
Table 10 datastore field data structure description

Parameter

Type

Description

type

String

DB engine. Value:

GaussDB

version

String

DB engine version.
Table 11 ha field data structure description

Parameter

Type

Description

mode

String

Deployment model. The value is case-insensitive and can be and enterprise (enterprise edition).

replication_mode

String

Replication mode for the standby node. The value can only be set to sync, indicating that data is synchronized in synchronous mode.

consistency

String

Transaction consistency type. This parameter is reserved for GaussDB. Values:

  • strong: strong consistency
  • eventual: eventual consistency

consistency_protocol

String

Replica consistency protocol. The value can be quorum (default value) or paxos. If it is not specified, the default value is used.
Table 12 backup_strategy field data structure description

Parameter

Type

Description

start_time

String

Backup time window. The creation of an automated backup will be triggered during the backup time window.

The value cannot be left blank. It 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 00.

Example value:

  • 08:00-09:00
  • 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.

keep_days

Integer

Retention days for specific backup files.

Value range: 1–732. If the backup_strategy field is not specified in the request body, keep_days in the response body is set to .
Table 13 volume field data structure description

Parameter

Type

Description

type

String

Disk type.

Its value is case-sensitive and can be:

  • ULTRAHIGH, indicating SSD.

size

Integer

Storage.
Table 14 charge_Info field data structure description

Parameter

Type

Description

charge_mode

String

Billing mode.

Example Request

  • Creating a distributed instance in the independent deployment (one-year yearly/monthly billing, DB engine 2.7, three AZs, three CNs, three shards, three replicas, and 8 vCPUs and 64 GB) 
    POST https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-independent-02", 
    "datastore": {
        "type": "GaussDB", 
        "version": "2.7"
    }, 
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", 
    "volume": {
        "type": "ULTRAHIGH", 
        "size": 120
    },
    "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": "", 
 
    "time_zone": "UTC+08:00",
    "ha":{
        "mode":"enterprise",
        "consistency":"strong",
        "replication_mode":"sync"
    },
    "sharding_num": 3,
    "coordinator_num": 3,
    "replica_num": 3,
    "port":8000
}
  • Creating a centralized instance with the following configurations: HA (1 primary + 2 standby) deployment, pay-per-use billing, DB engine 2.7, single AZ, and 8 vCPUs | 64 GB 
    POST https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-01",
    "datastore": {
        "type": "GaussDB",
        "version": "2.7"
    },
    "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 120
    },
    "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": "", 
    "time_zone": "UTC+08:00",
    "ha": {
        "mode": "centralization_standard",
        "consistency": "strong",
        "replication_mode": "sync"
    },
    "replica_num": 3,
    "port": 8000
}
  • Creating a centralized instance with the following configurations: HA (1 primary + 2 standby) deployment, yearly/monthly billing (1 year), DB engine 2.7, three AZs, and 8 vCPUs | 64 GB 
    POST https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3.1/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "user1-v3-ha-02",
    "datastore": {
        "type": "GaussDB",
        "version": "2.7"
    },
    "flavor_ref": "gaussdb.opengauss.ee.km1.2xlarge.arm8.ha",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 120
    },
    "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": "", 
    "time_zone": "UTC+08:00",
    "ha": {
        "mode": "centralization_standard",
        "consistency": "strong",
        "replication_mode": "sync"
    },
    "replica_num": 3,
    "port": 8000
}

Example Response

  • Distributed instance in the independent deployment (pay-per-use billing, DB engine 2.7, single AZ, 3 CNs, 3 shards, 3 replicas, 8 vCPUs and 64 GB) created. 
    {
 "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-independent-01",
        "status": "BUILD",
        "datastore": {
            "type": "GaussDB",
            "version": "2.7"
        },
        "ha": {
            "mode": "Enterprise",
            "replication_mode": "sync",
            "consistency": "strong"
            
        },
        "port": "8000",
        "volume": {
            "type": "ULTRAHIGH",
            "size": 120
        },
        "replica_num": 3,
        "region": "aaa",
        "backup_strategy": {
            "start_time": "17:00-18:00",
            "keep_days": 7
        },
        "enterprise_project_id": "0",
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        "availability_zone": "bbb,ccc",
        "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"
}
  • Distributed instance (one-year yearly/monthly billing, DB engine 2.7, three AZs, three CNs, three shards, three replicas, 8 vCPUs and 64 GB) created. 
    {
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-independent-02",
        "datastore": {
            "type": "GaussDB",
            "version": "2.7"
        },
        "ha": {
            "mode": "Enterprise",
            "replication_mode": "sync",
            "consistency": "strong"
            
        },
        "port": "8000",
        "volume": {
            "type": "ULTRAHIGH",
            "size": 120
        },
        "replica_num": 3,
        "region": "aaa",
        "backup_strategy": {
            "start_time": "17:00-18:00",
            "keep_days": 7
        },
        "enterprise_project_id": "0",
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        "availability_zone": "bbb,ccc",
        "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": "prePaid",
            "period_type": "year",
            "period_num": 1,
            "is_auto_renew": false,
            "is_auto_pay": false
        }
    },
    "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af"
}

  • Centralized instance with the following configurations created: HA (1 primary + 2 standby) deployment, pay-per-use billing, DB engine 2.7, single AZ, and 8 vCPUs | 64 GB 
    {
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-ha-01",
        "status": "BUILD",
        "datastore": {
            "type": "GaussDB",
            "version": "2.7"
        },
        "ha": {
            "mode": "Enterprise",
            "replication_mode": "sync",
            "consistency": "strong"
            
        },
        "port": "8000",
        "volume": {
            "type": "ULTRAHIGH",
            "size": 120
        },
        "region": "aaa",
        "replica_num": 3,
        "backup_strategy": {
            "start_time": "17:00-18:00",
            "keep_days": 7
        },
        "enterprise_project_id": "0",
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        "availability_zone": "bbb,ccc",
        "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329",
        "charge_info": {
            "charge_mode": "postPaid"
        },
        "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189",
        "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f"
    },
    "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af"
}
  • Centralized instance with the following configurations created: HA (1 primary + 2 standby) deployment, yearly/monthly billing (1 year), DB engine 2.7, three AZs, and 8 vCPUs | 64 GB 
    {
    "instance": {
        "id": "ad8cd1440aa94a02ae4580fcbebb3143in14",
        "name": "user1-v3-ha-02",
        "datastore": {
            "type": "GaussDB",
            "version": "2.7"
        },
        "ha": {
            "mode": "Enterprise",
            "replication_mode": "sync",
            "consistency": "strong"
            
        },
        "port": "8000",
        "volume": {
            "type": "ULTRAHIGH",
            "size": 120
        },
        "replica_num": 3,
        "region": "aaa",
        "backup_strategy": {
            "start_time": "17:00-18:00",
            "keep_days": 7
        },
        "enterprise_project_id": "0",
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        "availability_zone": "bbb,ccc",
        "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": "prePaid",
            "period_type": "year",
            "period_num": 1,
            "is_auto_renew": false,
            "is_auto_pay": false
        }
    },
    "job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af"
}

Status Code

Error Code

For details, see Error Codes.

Parent topic: DB Instance Management