文档首页/ 云数据库 GaussDB/ API参考/ 历史API/ 实例管理/ 创建数据库实例（v3.1）

更新时间：2025-10-14 GMT+08:00

查看PDF

创建数据库实例（v3.1）

功能介绍

创建GaussDB实例。

调用接口前，您需要了解API 认证鉴权。
调用接口前，您需要提前获取到地区和终端节点。

调试

您可以在API Explorer中调试该接口。

URI

POST /v3.1/{project_id}/instances

表1 参数说明
名称	是否必选	说明
project_id	是	参数解释：租户在某一Region下的项目ID。获取方法请参见获取项目ID。约束限制：不涉及。取值范围：只能由英文字母、数字组成，且长度为32个字符。默认取值：不涉及。

请求参数

表2 请求参数
名称	是否必选	参数类型	说明
name	是	String	实例名称。用于表示实例的名称，同一租户下，同类型的实例名可重名。取值范围：4~64个字符之间，必须以字母开头，区分大小写，可以包含字母、数字、中划线或者下划线，不能包含其他的特殊字符。
datastore	是	Object	数据库信息。详情请参见表3。
ha	是	Object	实例部署形态。详情请参见表4。
configuration_id	否	String	参数模板ID。当不传该参数时，使用系统默认的参数模板，且响应体中不返回该参数。
port	否	String	数据库对外开放的端口，不填默认为8000，可选范围为：1024-39998。限制端口： 2378,2379,2380,4999,5000,5999,6000,6001,8097,8098,12016,12017,20049,20050,21731,21732,32122,32123,32124。
password	是	String	数据库密码。 GaussDB密码取值范围: 非空; 至少包含大写字母(A-Z)，小写字母(a-z)，数字(0-9)，非字母数字字符(限定为~!@#%^*-_=+?,)四类字符中的三类字符;长度8~32个字符。建议您输入高强度密码，以提高安全性，防止出现密码被暴力破解等安全风险。
backup_strategy	否	Object	备份策略。详情请参见表5。
enterprise_project_id	否	String	企业项目ID。只有企业租户时该参数才生效。使用请参考《企业管理 API参考》的“查询企业项目列表”响应消息表“enterprise_project字段数据结构说明”的“id”。
disk_encryption_id	否	String	用于磁盘加密的密钥ID，默认为空。密钥授权请参考《密码安全中心用户指南》的“创建授权”章节。
flavor_ref	是	String	规格码，取值范围：非空。参考查询数据库规格中“spec_code”字段获取。
volume	是	Object	volume信息。详情请参见表6。
region	是	String	区域ID。取值范围：非空，请参见地区和终端节点。
availability_zone	是	String	可用区ID。 GaussDB取值范围：非空，可选部署在相同可用区或不同可用区，可用区之间用逗号隔开。取值范围：非空，请参见地区和终端节点。
vpc_id	是	String	虚拟私有云ID，获取方法如下：方法1：登录虚拟私有云服务的控制台界面，在虚拟私有云的详情页面查找VPC ID。方法2：通过虚拟私有云服务的API接口查询，具体操作可参考查询VPC列表。
subnet_id	是	String	子网的网络ID信息，获取方法如下：方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找网络ID。方法2：通过虚拟私有云服务的API接口查询，具体操作可参考查询子网列表。
security_group_id	是	String	指定实例所属的安全组。如果不需要指定安全组，请联系客服申请白名单。方法1：登录虚拟私有云服务的控制台界面，在安全组的详情页面查找安全组ID。方法2：通过虚拟私有云服务的API接口查询，具体操作可参考查询安全组列表。
charge_info	否	Object	计费类型信息，仅支持按需和包周期。详情请参见表7。
time_zone	否	String	UTC时区。不选择时，GaussDB国内站默认为UTC时间。选择填写时，取值范围为UTC-12:00~UTC+12:00，且只支持整段时间，如UTC+08:00，不支持UTC+08:30。
sharding_num	否	Integer	仅分布式形态需要填写该参数。分片数量，取值范围1~9。
coordinator_num	否	Integer	仅分布式形态需要填写该参数。协调节点数量，取值范围1~9。CN数量必须小于或等于两倍的分片数。
replica_num	否	Integer	实例副本集数，支持取值3。不填默认为3。
enable_force_switch	否	Boolean	enable_force_switch表示是否开启备机强升主功能，仅支持取值true，false。true表示开启备机强升主功能，false表示关闭，默认关闭。仅支持1.2.2及以上版本。说明：备机强升主功能适用场景：在主机发生故障后，为了保障集群的可用性，强制拉起备机作为新主机对外提供服务。本功能在集群故障状态下，以丢失部分数据为代价换取集群尽可能快的恢复服务，是集群状态为不可用时的一个逃生方法。
enable_single_float_ip	否	Boolean	单浮动IP策略，仅V2.0-3.206及以上版本的集中式版实例支持。默认值是false，表示不开启单浮动IP策略。取值范围： true：开启单浮动IP策略，实例将只有一个浮动IP绑定主节点，如果发生主备倒换，浮动IP不会发生变化。 false：不开启单浮动IP策略，每个节点都会绑定一个浮动IP，如果发生主备倒换，浮动IP会发生变化。

表3 datastore字段数据结构说明
名称	是否必选	参数类型	说明
type	是	String	数据库引擎，取值如下： GaussDB。不区分大小写。
version	否	String	数据库版本。不填时，默认为当前最新版本。 GaussDB支持的版本参考查询数据库引擎的版本查询。

表4 ha字段数据结构说明
名称	是否必选	参数类型	说明
mode	是	String	GaussDB为分布式模式取值：enterprise(企业版) ，combined(基础版混合部署)，集中式版取值:centralization_standard，不区分大小写。
consistency	是	String	指定事务一致性类型，取值如下，不区分大小写： strong：强一致性。 eventual：最终一致性。
replication_mode	是	String	备机同步模式。固定取值为sync，表示数据同步方式为“同步模式”。
instance_mode	否	String	指定创建实例的产品类型。不传该参数默认创建企业版实例，创建基础版和生态版需要指定参数值。 enterprise：创建企业版实例。 basic：创建基础版实例。 ecology：创建生态版实例。

表5 backup_strategy字段数据结构说明
名称	是否必选	参数类型	说明
start_time	是	String	备份时间段。自动备份将在该时间段内触发。取值范围：非空且非负，格式必须为hh:mm-HH:MM且有效，当前时间指UTC时间。 HH取值必须比hh大1。 mm和MM取值必须相同，且取值必须为00。取值示例： 08:00-09:00 23:00-00:00
keep_days	否	Integer	指定备份文件的可保存天数。取值范围： 1~36500。该参数缺省时，默认填写为7天。

表6 volume字段数据结构说明
名称	是否必选	参数类型	说明
type	是	String	磁盘类型。仅支持ULTRAHIGH和ESSD，区分大小写，分别表示SSD和极速云盘。
size	是	Integer	磁盘大小。例如：该参数填写为“40”，表示为创建的实例分配40GB的磁盘空间。 ECS部署方案：取值范围：（分片数40GB）~（分片数24TB），且大小只能为分片数*4GB的整数倍。

表7 chargeInfo字段数据结构说明
名称	是否必选	参数类型	说明
charge_mode	是	String	计费模式。 postPaid：后付费，即按需付费。 prePaid：预付费，即包年/包月。
period_type	否	String	订购周期类型。“charge_mode”为“prePaid”时生效，且为必选值。取值范围： month：包月。 year：包年。
period_num	否	Integer	“charge_mode”为“prePaid”时生效，且为必选值，指定订购的时间。取值范围：当“period_type”为“month”时，取值为1~9。当“period_type”为“year”时，取值为1~3。当传入浮点型时，会自动截取为整型。
is_auto_renew	否	Boolean	创建包周期实例时可指定,表示是否自动续订,续订时会自动支付。按月订购时续订周期默认为1个月,按年订购时续订周期默认为1年,续订周期可自定义修改。 true，为自动续订。 false，为不自动续订，默认该方式。
is_auto_pay	否	Boolean	创建包周期时可指定，表示是否自动从客户的账户中支付，此字段不影响自动续订的支付方式。 true，为自动支付。 false，为手动支付，默认该方式。

响应参数

表8 响应参数
名称	参数类型	说明
instance	Object	实例信息。详情请参见表9。
job_id	String	实例创建的任务ID。仅创建按需实例时会返回该参数。
order_id	String	订单号，创建包年包月时返回该参数。

表9 instance说明
名称	参数类型	说明
id	String	实例ID。
name	String	实例名称。用于表示实例的名称，同一租户下，同类型的实例名称可相同。取值范围：4~64个字符之间，必须以字母开头，不区分大小写，可以包含字母、数字、中划线或者下划线，不能包含其他的特殊字符。
status	String	实例状态。如BUILD，表示创建中。仅创建按需实例时会返回该参数。
datastore	Object	数据库信息。详情请参见表10。
ha	Object	数据库部署形态。详情请参见表11。
replica_num	Integer	实例副本集数。
port	String	数据库端口信息，与请求参数相同。
backup_strategy	Object	自动备份策略。详情请参见表12。
enterprise_project_id	String	项目标签。
flavor_ref	String	规格码，取值范围：非空。
volume	Object	volume信息。详情请参见表13。
region	String	区域ID。
availability_zone	String	可用区ID。
vpc_id	String	虚拟私有云ID。
subnet_id	String	子网的网络ID信息。
security_group_id	String	实例所属的安全组。
charge_info	Object	付费方式信息。详情请参见表14。

**表10** datastore字段数据结构说明
名称	参数类型	说明
type	String	数据库引擎，返回值如下： GaussDB
version	String	数据库版本。

**表11** ha字段数据结构说明
名称	参数类型	说明
mode	String	GaussDB分布式模式支持取值：enterprise(企业版) ，combined(基础版混合部署)，集中式版取值:centralization_standard，不区分大小写。
replication_mode	String	备机同步模式。固定取值为sync，表示数据同步方式为“同步模式”。
consistency	String	GaussDB的预留参数：指定事务一致性类型，取值范围： strong：强一致性。 eventual：最终一致性。
consistency_protocol	String	指定副本一致性协议类型，取值范围：quorum 、paxos。不填时，默认为quorum。

**表12** backup_strategy字段数据结构说明
名称	参数类型	说明
start_time	String	备份时间段。自动备份将在该时间段内触发。取值范围：非空，格式必须为hh:mm-HH:MM且有效，当前时间指UTC时间。 HH取值必须比hh大1。 mm和MM取值必须相同，且取值必须为00。取值示例： 08:00-09:00 23:00-00:00 如果请求体中不填写“backup_strategy”字段，则响应体中 “start_time”默认返回“02:00-03:00”。
keep_days	Integer	指定已生成备份文件的可保存天数。取值范围：1～732。如果请求体中不填写“backup_strategy”字段，则响应体中 “keep_days”默认填写为7天。

**表13** volume字段数据结构说明
名称	参数类型	说明
type	String	磁盘类型。取值如下，区分大小写： ULTRAHIGH，表示SSD盘。 ESSD,表示极速云盘。
size	Integer	磁盘大小。

**表14** charge_Info字段数据结构说明
名称	参数类型	说明
charge_mode	String	计费模式。 postPaid：后付费，即按需付费。 prePaid：预付费，即包年/包月。
period_type	String	订购周期类型。month：包月。year：包年。说明：“charge_mode”为“prePaid”时生效，且为必选值。枚举值： month year
period_num	Integer	“charge_mode”为“prePaid”时生效，且为必选值，指定订购的时间。取值范围：当“period_type”为“month”时，取值为1~9。当“period_type”为“year”时，取值为1~3。
is_auto_renew	Boolean	创建包周期实例时可指定,表示是否自动续订,续订时会自动支付。按月订购时续订周期默认为1个月,按年订购时续订周期默认为1年,续订周期可自定义修改。 true,表示自动续订。 false,表示不自动续订,默认为该方式。
is_auto_pay	Boolean	创建包周期实例时可指定，表示是否自动从账户中支付，该字段不影响自动续订的支付方式。 true，表示自动从账户中支付。 false，表示手动从账户中支付，默认为该支付方式。

请求示例

创建一个GaussDB实例，实例部署形态为分布式独立部署，包周期付费（1年），引擎版本为2.7，三个不同可用区下，3个协调节点，3个分片，3个副本，规格为8U64G。

POST https://gaussdb-opengauss.cn-north-4.myhuaweicloud.com/v3.1/054b61972980d4552f0bc00ac8d3f5cd/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
    },
    "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
}

创建一个GaussDB实例，实例部署形态为集中式版高可用（1主2备），按需付费，引擎版本为2.7，同一可用区下，规格为8U64G。

POST https://gaussdb-opengauss.cn-north-4.myhuaweicloud.com/v3.1/054b61972980d4552f0bc00ac8d3f5cd/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
    },
    "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
}

创建一个GaussDB实例，实例部署形态为集中式版高可用（1主2备），包周期付费（1年），引擎版本为2.7，三个不同可用区下，规格为8U64G。

POST https://gaussdb-opengauss.cn-north-4.myhuaweicloud.com/v3.1/054b61972980d4552f0bc00ac8d3f5cd/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
    },
    "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
}

响应示例

创建一个GaussDB分布式独立部署，按需付费，引擎版本为2.7，同一可用区下，3个协调节点，3个分片，3个副本，规格为8U64G的实例：

{
 "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,bbb,bbb",
        "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"
}

GaussDB分布式部署形态，包周期付费（1年），引擎版本为2.7，三个不同可用区下，3个协调节点，3个分片，3个副本，规格为8U64G的实例响应：

{
    "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,bbb,bbb",
        "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"
}

GaussDB集中式版高可用（1主2备），按需付费，引擎版本为2.7，同一可用区下，规格为8U64G的实例响应：

{
    "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,bbb,bbb",
        "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"
}

GaussDB集中式版高可用（1主2备），包周期付费（1年），引擎版本为2.7，三个不同可用区下，规格为8U64G的实例响应：

{
    "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,bbb,bbb",
        "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"
}

状态码

正常
 200
异常
 请参见状态码。

错误码

请参见错误码。

父主题： 实例管理

上一篇：实例管理

下一篇：创建数据库实例（v3）

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

盘古Doer提问云社区提问