Restoring Data to a New instance

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.

Debugging

You can debug this API in API Explorer.

URI

POST /v3/{project_id}/instances

**Table 1** Parameter description
Name	Mandatory	Type	Description
project_id	Yes	String	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** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. You can obtain the token by calling the IAM API used to obtain a user token. After a response is returned, the value of X-Subject-Token in the response header is the token. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Language. Constraints N/A Range zh-cn: Chinese en-us: English Default Value en-us

**Table 3** 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 The value cannot be left blank. Range You can specify one or multiple AZs to deploy an instance. Use commas (,) to separate AZs. The AZ ID can be obtained from the response returned after the API Querying Instance Specifications is called. Default Value N/A
flavor_ref	Yes	String	Definition Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications. Constraints The value cannot be left blank. Range N/A Default Value N/A
volume	Yes	Object	Definition Volume information. For details, see Table 4. Constraints N/A
disk_encryption_id	No	String	Definition ID of the key used for disk encryption. To obtain the value, call the Data Encryption Workshop API for creating a key and use the key_id returned in the response. For details about key grant, see Creating a Grant in Data Encryption Workshop User Guide. 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 5. Constraints N/A
backup_strategy	No	Object	Definition Automated backup policy. For details, see Table 7. Constraints N/A
restore_point	Yes	Object	Definition Restoration information. For details, see Table 6. Constraints N/A
enable_parallel_restore	No	Boolean	Definition Whether to support parallel restoration. Constraints If this parameter is not specified, the function is disabled for enterprise edition instances and enabled by default for centralized instances. Range true: Parallel restoration is supported. false: Parallel restoration is not supported. Default Value N/A
configuration_id	No	String	Definition Parameter template ID. To obtain the value, see Obtaining Parameter Templates. Constraints N/A Range N/A Default Value If this parameter is not specified, the default parameter template is used and this parameter is not returned in the response body.
enterprise_project_id	No	String	Definition Enterprise project ID. For details, see id in the enterprise_project field data structure table in Querying Enterprise Projects of Enterprise Management API Reference. Constraints This parameter is suitable only for enterprise tenants. 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 4** volume field data structure description
Parameter	Mandatory	Type	Description
type	Yes	String	Definition Storage type. Constraints N/A Range ULTRAHIGH (SSD storage) or ESSD (extreme SSD storage). The value is case-sensitive. Default Value N/A
size	Yes	Integer	Definition Storage space, in GB. For example, if this parameter is set to 40, 40 GB of storage is allocated to the created instance. Constraints N/A Range ECS-based deployment: The value ranges from (number_of_shards x 40 GB) to (number_of_shards x 24,000 GB) and must be a multiple of (number_of_shards x 4 GB). Default Value N/A

**Table 5** 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. If period_type is set to month, the unit is month. If period_type is set to year, the unit is year. 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 6** restore_point field data structure description
Parameter	Mandatory	Type	Description
instance_id	Yes	String	Definition ID of an instance that a backup is created for, which uniquely identifies the instance. You can obtain the ID by calling Querying Backups. Constraints N/A Range N/A Default Value N/A
backup_id	No	String	Definition ID of the backup used for restoration. It indicates the ID of the full backup corresponding to schema_type. You can obtain the ID by calling Querying Backups. Constraints This parameter must be specified when a backup is used for restoration. 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 7** 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 8** Parameter description
Parameter	Type	Description
instance	Object	Definition Instance information. For details, see Table 9.
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 9** 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. Range BUILD: The instance is being created. BUILD_FAILED: The instance failed to be created. ACTIVE: The instance is normal. FAILED: The instance is abnormal. FROZEN: The instance is frozen. MODIFYING: The storage is being scaled up, or instance specifications are being changed. EXPANDING: Read replicas, CNs, or DN shards are being added to the instance. REBOOTING: The instance is being rebooted. REDUCING: Read replicas are being deleted. UPGRADING: The instance is being upgraded. RESTORING: The instance is being restored. SWITCHOVER: A primary/standby switchover is being performed. MIGRATING: The instance is being migrated. BACKING UP: The instance is being backed up. UPGRADE TO BE OBSERVED: The instance upgrade is in the observation period. MODIFYING DATABASE PORT: The database port is being changed. STORAGE FULL: The instance storage is full. REPAIRING: The instance is being repaired. SHUTDOWN: The instance is stopped.
datastore	Object	Definition Database information. For details, see Table 10.
ha	Object	Definition Instance deployment model. For details, see Table 11.
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 12.
backup_strategy	Object	Definition Automated backup policy. For details, see Table 13.
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 14.

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

**Table 11** 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 12** 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 13** 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 14** 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: The order is manually paid from the account.

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"
}