Restoring Data to a New instance_Backup and Restoration_APIs (Recommended)_API Reference

Function

This API is used to restore data to a new DB instance using backups. Before calling this API:

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

Constraints

The DB engine versions and instance types of the original and new instances must be the same.

The specifications of the new instance must be greater than or equal to those of the original instance.

URI

POST /v3/{project_id}/instances

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A

Request Parameters

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
name	Yes	String	Definition DB instance name. Instances of the same type can have same names under the same tenant. Constraints N/A Range The name can contain 4 to 64 characters and must start with a letter. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Default Value N/A
availability_zone	Yes	String	Definition AZ ID. Constraints N/A Range The value cannot be empty. You can specify one or three AZs and use commas (,) to separate the 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. The value cannot be empty. For details about how to obtain this parameter value, see Regions and Endpoints. Default Value N/A
flavor_ref	Yes	String	Definition Specification code. Range The value cannot be empty. To obtain its value, see the spec_code field in Querying Instance Specifications. Default Value N/A
volume	Yes	Object	Definition Volume information. For details, see Table 3. Constraints N/A
disk_encryption_id	No	String	Definition ID of the key used for disk encryption. Constraints N/A Range N/A Default Value It is left blank by default.
vpc_id	Yes	String	Definition VPC ID. To obtain this parameter value, use the following methods: Method 1: Log in to the VPC console and view the VPC ID in the VPC details. Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference. Constraints N/A Range N/A Default Value N/A
subnet_id	Yes	String	Definition 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. Method 2: See section "Querying Subnets" in the Virtual Private Cloud API Reference. Constraints N/A Range N/A Default Value N/A
security_group_id	Yes	String	Definition Security group which the instance is associated with. To obtain this parameter value, use either of the following methods: 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. Method 2: See the section "Querying Security Groups" in the Virtual Private Cloud API Reference. Constraints N/A Range N/A Default Value N/A
password	Yes	String	Definition Database password. Constraints N/A Range Consist of 8 to 32 characters, including at least three of the following: uppercase letters, lowercase letters, digits, and special characters ~!@#%^-_=+?, A strong password helps improve security and mitigate potential threats like brute force attacks. Default Value* N/A
charge_info	No	Object	Definition Billing mode, which can be pay-per-use or yearly/monthly. For details, see Table 4. Constraints N/A
backup_strategy	No	Object	Definition Automated backup policy. For details, see Table 6. Constraints N/A
restore_point	Yes	Object	Definition Restoration information. For details, see Table 5. Constraints N/A
enable_parallel_restore	No	Boolean	Definition Whether to support parallel restoration. If this parameter is not specified, the function is not supported for instances of the enterprise edition, and supported for centralized instances by default. Constraints N/A Range true: Parallel restoration is supported. false: Parallel restoration is not supported. Default Value N/A
configuration_id	No	String	Definition Parameter template ID. If this parameter is not specified, the default parameter template is used. Constraints N/A Range N/A Default Value N/A
enterprise_project_id	No	String	Definition Enterprise project ID. Constraints N/A Range N/A Default Value N/A
port	No	String	Definition Port for applications to access the database. Constraints 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. Range 1024–39998 Default Value 8000
time_zone	No	String	Definition UTC time zone. Constraints N/A Range 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. Default Value UTC time for GaussDB in the international website
enable_force_switch	No	Boolean	Definition Whether to enable the function of forcibly promoting a standby node to primary. Constraints This function is available only for instances of version 1.2.2 or later. Range true: The function of forcibly promoting a standby node to primary is enabled. false: The function of forcibly promoting a standby node to primary is disabled. Default Value false NOTE: If the primary node fails, this function enables a standby node to be forcibly promoted to primary to provide services, ensuring the instance availability. This function ensures service recovery as soon as possible at the cost of partial data loss. You are not advised to use this function if you are not clear about the impact of data loss on services.

**Table 3** volume field data structure description
Parameter	Mandatory	Type	Description
type	Yes	String	Definition Disk type. Constraints N/A Range LOCALSSD indicates the local SSD and is available for centralized instances. ULTRAHIGH indicates the cloud disk and is available for distributed instances in the independent deployment. The value is case-sensitive. ULTRAHIGH: local disk. ESSD: extreme SSD. Default Value N/A
size	Yes	Integer	Definition Storage space, which must be at least equal to that of the original instance. For example, if this parameter is set to 40, 40 GB of storage is allocated to the instance. Constraints The storage capacity of the new instance must be at least equal to that of the original instance. Range ECS-based deployment: The value ranges 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 GB). Default Value N/A

**Table 4** charge_info field data structure description
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Definition Billing mode. Constraints N/A Range postPaid: pay-per-use billing. prePaid: yearly/monthly billing. Default Value N/A
period_type	No	String	Definition Subscription type. Constraints This parameter is valid and mandatory only when charge_mode is set to prePaid. Range month: monthly subscription. year: yearly subscription. Default Value N/A
period_num	No	Integer	Definition Subscription time. Constraints This parameter is valid and mandatory only when charge_mode is set to prePaid. Range If period_type is set to month, this parameter value ranges from 1 to 9. If period_type is set to year, the value ranges from 1 to 3. When a floating-point value is used, the value is automatically truncated to an integer. Default Value N/A
is_auto_renew	No	Boolean	Definition Whether automatic renewal is enabled for yearly/monthly instances. If you enable this function, the order will be automatically paid during the subscription renewal. The default renewal period is one month for monthly subscription and one year for yearly subscription. The renewal period can be configured as needed. Constraints N/A Range true: Automatic renewal is enabled. false: Automatic renewal is disabled. Default Value false
is_auto_pay	No	Boolean	Definition Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. Constraints N/A Range true: The order will be automatically paid. false: The order will be manually paid. Default Value false

**Table 5** restore_point field data structure description
Parameter	Mandatory	Type	Description
instance_id	Yes	String	Definition Source instance ID. Constraints N/A Range N/A Default Value N/A
backup_id	No	String	Definition ID of the backup to be restored. Constraints N/A Range N/A Default Value N/A
type	No	String	Definition Restoration mode. Constraints N/A Range backup: indicates that data is restored using backups. In this mode, type is optional and backup_id is mandatory. timestamp: indicates that data is restored using point-in-time recovery (PITR). In this mode, type and restore_time are both mandatory. Default Value N/A
restore_time	No	Long	Definition Time point of data restoration in the UNIX timestamp format. The unit is millisecond and the time zone is UTC. Constraints N/A Range N/A Default Value N/A

**Table 6** backup_strategy field data structure description
Parameter	Mandatory	Type	Description
start_time	Yes	String	Definition Deprecated field. Leave it blank. Constraints N/A Range N/A Default Value N/A
keep_days	No	Integer	Definition Deprecated field. Leave it blank. Constraints N/A Range N/A Default Value N/A

Response Parameters

**Table 7** Parameter description
Parameter	Type	Description
instance	Object	Definition Instance information. For details, see Table 8.
job_id	String	Definition ID of the job for restoring data to a new instance. Range N/A
order_id	String	Definition ID of the order for creating an instance. This parameter is returned only when a yearly/monthly instance is created. Range N/A

**Table 8** instance description
Parameter	Type	Description
id	String	Definition Instance ID. Range N/A
name	String	Definition DB instance name. Instances of the same type can have same names under the same tenant. Range The name can contain 4 to 64 characters and must start with a letter. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.
status	String	Definition Instance status. For example, BUILD indicates that the instance is being created. Range N/A
datastore	Object	Definition Database information. For details, see Table 9.
ha	Object	Definition Instance deployment model. For details, see Table 10.
port	String	Definition Database port. Range 1024–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.
enterprise_project_id	String	Definition Project ID. Range N/A
volume	Object	Definition Volume information. For details, see Table 11.
backup_strategy	Object	Definition Automated backup policy. For details, see Table 12.
replica_num	Integer	Definition Number of replicas. Range N/A
region	String	Definition Region ID. Range The value cannot be empty. To obtain this value, see Regions and Endpoints.
flavor_ref	String	Definition Specification code. Range N/A
availability_zone	String	Definition AZ ID. You can deploy your instance in the same AZ or across three different AZs, and use commas (,) to separate AZs. The value cannot be empty. To obtain this value, see Regions and Endpoints.
vpc_id	String	Definition VPC ID. Range N/A
subnet_id	String	Definition Subnet ID. Range N/A
security_group_id	String	Definition Security group ID. Range N/A
charge_info	Object	Definition Billing mode, which can be pay-per-use or yearly/monthly. For details, see Table 13.

**Table 9** datastore field data structure description
Parameter	Type	Description
type	String	Definition Database engine. Range GaussDB
version	String	Definition DB engine version. Range N/A

**Table 10** ha field data structure description
Parameter	Type	Description
mode	String	Definition Mode. Range For distributed instances, the return value is enterprise (enterprise edition). For centralized instances, the return value is centralization_standard (centralized edition).
replication_mode	String	Definition Replication mode for the standby instance. Range The value can only be set to sync, indicating that data is synchronized in synchronous mode.
consistency	String	Definition (GaussDB reserved parameter) Instance consistency type. Range strong: strong consistency eventual: eventual consistency

**Table 11** volume field data structure description
Parameter	Type	Description
type	String	Definition Disk type. Range The value is case-sensitive. ULTRAHIGH: indicates the SSD. ESSD: indicates the extreme SSD.
size	Integer	Definition Disk size. Range When restoring a distributed GaussDB instance, you need to specify the size 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 12** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Definition This field has been deprecated. Range N/A
keep_days	Integer	Definition This field has been deprecated. Range N/A

**Table 13** charge_info field data structure description
Parameter	Type	Description
charge_mode	String	Definition Billing mode. Range postPaid: pay-per-use billing. prePaid: yearly/monthly billing.
period_type	String	Definition Subscription type. This parameter is only available when charge_mode is set to prePaid. Range month: monthly subscription. year: yearly subscription.
period_num	Integer	Definition Subscription period. This parameter is valid and mandatory only when charge_mode is set to prePaid. Range If period_type is set to month, the value ranges from 1 to 9. If period_type is set to year, the value ranges from 1 to 3.
is_auto_renew	Boolean	Definition Whether automatic renewal is enabled for yearly/monthly instances. If you enable this function, the order will be automatically paid during the subscription renewal. The default renewal period is one month for monthly subscription and one year for yearly subscription. The renewal period can be configured as needed. Range true: Automatic renewal is enabled. false (default value): Automatic renewal is disabled.
is_auto_pay	Boolean	Definition Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment mode of automatic renewal. Range true: The order is automatically paid from the account. false (default value): The order needs to be manually paid.

Example Request

Restoring data to a new DB instance using backups. The new DB instance features 8 vCPUs, 64 GB memory, and 160 GB storage.

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
    "disk_encryption_id": "2gfdsh-844a-4023-a776-fc5c5fb71fb4",
    "vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
    "subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
    "security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
    "password": "******",
    "restore_point": {
        "instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
        "backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14"
    },
    "enable_parallel_restore": false,
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "enterprise_project_id": "ba1f7fc8-3307-42a7-aa6f-42c8b9b8f85c",
    "port": 8000,
    "enable_force_switch": true,
    "time_zone": "UTC+04:00"
}

Restoring data to a new DB instance using backups. The new DB instance features 8 vCPUs, 64 GB memory, and 160 GB storage.

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
    "disk_encryption_id": "2gfdsh-844a-4023-a776-fc5c5fb71fb4",
    "vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
    "subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
    "security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
    "password": "******",
    "restore_point": {
        "instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
        "backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14",
        "type": "backup"
    },
    "enable_parallel_restore": false,
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "enterprise_project_id": "ba1f7fc8-3307-42a7-aa6f-42c8b9b8f85c",
    "port": 8000,
    "enable_force_switch": true,
    "time_zone": "UTC+04:00"
}

Restoring data to a new DB instance using PITR. The new DB instance features 8 vCPUs, 64 GB memory, and 160 GB storage.

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances
{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
    "disk_encryption_id": "2gfdsh-844a-4023-a776-fc5c5fb71fb4",
    "vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
    "subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
    "security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
    "password": "******",
    "restore_point": {
        "instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
        "type": "timestamp", 
        "restore_time": 1532001446987
    },
    "enable_parallel_restore": false,
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "enterprise_project_id": "ba1f7fc8-3307-42a7-aa6f-42c8b9b8f85c",
    "port": 8000,
    "enable_force_switch": true,
    "time_zone": "UTC+04:00"
}

Response

Data is resorted to the new instance.

{
    "instance": {
        "id": "2gfdsh844a4023a776fc5c5fb71fb4in14",
        "name": "gaussdb-instance-rep2",
        "status": "BUILD",
        "datastore": {
            "type": "GaussDB",
            "version": "1.4"
        },
        "ha": {
            "mode": "enterprise",
            "consistency": "strong",
            "replication_mode": "sync"
        },
        "volume": {
            "type": "ULTRAHIGH",
            
            "size": 160
        },
        "port": "8000",
        "replica_num": 3,
        "region": "regionA",
        "enable_parallel_restore": false,
        "flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in",
        
        "availability_zone": "aaa,bbb,ccc",
        "vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
        "subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
        "security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
        "charge_info": {
            "charge_mode": "postPaid"
        },
        "enterprise_project_id": "fdsa-3rds",
    },
    "job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}

Status Codes

Normal
202
Abnormal
For details, see Status Codes.

Error Codes

For details, see Error Codes.

Restoring Data to a New instance