Reviewed-by: Boka, Ladislav <ladislav.boka@t-systems.com>
Co-authored-by: Ru, Li Yi <liyiru7@huawei.com>
Co-committed-by: Ru, Li Yi <liyiru7@huawei.com>

2024-09-06 09:04:21 +00:00

67 KiB

Raw Permalink Blame History

Restoring Data to a New DB 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.
Understand the API in Using APIs.
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

URI format
POST https://{Endpoint}/v3/{project_id}/instances
Example
https://gaussdb.eu-de.otc.t-systems.com/v3/0483b6b16e954cb88930a360d2c4e663/instances
Parameter description
Table 1 Parameter description
Parameter

Mandatory

Description

project_id

Yes

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

Request

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
name	Yes	String	DB 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. It can contain only letters (case-sensitive), digits, hyphens (-), and underscores (_).
availability_zone	Yes	String	AZ ID. The value cannot be left blank. You can deploy GaussDB 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. The value cannot be left blank. For details about how to obtain this parameter value, see Regions and Endpoints.
flavor_ref	Yes	String	Specification code. The value cannot be empty. For details on how to obtain the GaussDB specification code, see DB Instance Specifications.
volume	Yes	Object	Volume information. For details, see Table 3.
vpc_id	Yes	String	VPC ID. To obtain this parameter value, use the following methods: Method 1: Log in to VPC console and view the VPC ID in the VPC details. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	Yes	String	Network ID. To obtain this parameter value, use either of the following methods: 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 the section "Querying Subnets" in the Virtual Private Cloud API Reference. Method 2: See section "Querying Subnets" under "APIs" or "Querying Networks" under "OpenStack Neutron APIs" in Virtual Private Cloud API Reference.
security_group_id	Yes	String	Security group which the instance is associated with. To obtain this parameter value, use either of the following methods: 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: See the section "Querying Security Groups" in the Virtual Private Cloud API Reference.
password	Yes	String	Database password. The password must: Consist of 8 to 32 characters and include 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.
charge_info	No	Object	Billing mode, which can be pay-per-use. For details, see Table 4.
backup_strategy	No	Object	Automated backup policy.
restore_point	Yes	Object	Restoration information. For details, see Table 5.
configuration_id	No	String	Parameter template ID. If this parameter is not specified, the default parameter template is used.
port	No	String	Port number used by the database to provide services for external systems, ranging from 1024 to 39998. It cannot be set to the default value 8000. 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.
time_zone	No	String	UTC time zone. If this parameter is not specified, GaussDB uses UTC 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.
enable_force_switch	No	Boolean	Whether to forcibly promote a standby node to primary. The value can only be true or false. true: The function is enabled. false: (default value) The function is disabled. Only 1.2.2 and later versions are supported. NOTE: The function is suitable for the following scenario: When the primary node is faulty, a standby node is forcibly promoted to primary to provide services, ensuring the instance availability. When the instance is faulty, this function is used to recover services 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	Disk type. Only ULTRAHIGH is supported, which indicates the local disk.
size	Yes	Integer	Storage space, which must be at least that of the original DB instance. For example, if this parameter is set to 40, 40 GB of storage is allocated to the instance. ECS deployment: The value must be a multiple of (Number of shards x 40 GB), ranging from (Number of shards x 40 GB) to (Number of shards x 16 TB).

**Table 4** charge_info field data structure description
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Billing mode. postPaid: pay-per-use billing.

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

Example Request

Restoring instance data

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

{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m4.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
   
    "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"
    },
  
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "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.

{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m4.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
   
    "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"
    },
  
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "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.

{
    "name": "targetInst",
    "availability_zone": "aaa,bbb,ccc",
    "flavor_ref": "gaussdb.opengauss.ee.dn.m4.2xlarge.8.in",
    "volume": {
        "type": "ULTRAHIGH",
        "size": 160
    },
   
    "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
    },
  
    "configuration_id": "52e86e87445847a79bf807ceda213165pr01",
    "port": 8000,
    "enable_force_switch": true,
    "time_zone": "UTC+04:00"
}

Response

Normal response

**Table 6** Parameter description
Parameter	Type	Description
instance	Object	Instance information. For details, see Table 7.
job_id	String	Task ID for restoring data to a new DB instance.

**Table 7** instance description
Parameter	Type	Description
id	String	Instance ID.
name	String	DB 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. It can contain only letters (case-sensitive), digits, hyphens (-), and underscores (_).
status	String	Instance status. For example, BUILD indicates that the instance is being created.
datastore	Object	Database information. For details, see Table 8.
ha	Object	Instance deployment model. For details, see Table 9.
port	String	Database port. The default value is 8000.
volume	Object	Volume information. For details, see Table 10.
backup_strategy	Object	Automated backup policy. For details, see Table 11.
replica_num	Integer	Number of replicas.
region	String	Region ID. The value cannot be left blank. For details about how to obtain this parameter value, see Regions and Endpoints.
flavor_ref	String	Specification code.
availability_zone	String	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 left blank. For details about how to obtain this parameter value, see Regions and Endpoints.
vpc_id	String	VPC ID.
subnet_id	String	Subnet ID.
security_group_id	String	Security group ID.
charge_info	Object	Billing mode, which can be pay-per-use. For details, see Table 12.
enable_parallel_restore	Boolean	Whether to support parallel restoration. false: not supported true: supported

**Table 8** datastore field data structure description
Parameter	Type	Description
type	String	DB engine. Value: GaussDB
version	String	DB engine version.

**Table 9** ha field data structure description
Parameter	Type	Description
mode	String	For distributed instances, the return value is enterprise (enterprise edition). For primary/standby instances, the return value is centralization_standard (primary/standby edition).
replication_mode	String	Replication mode for the standby node. Value: sync. NOTE: sync indicates synchronous replication. Value: sync
consistency	String	(GaussDB reserved parameter) Transaction consistency type. The value can be strong or eventual. Value: strong eventual

**Table 10** volume field data structure description
Parameter	Type	Description
type	String	Disk type. Its value is case-sensitive and can be: ULTRAHIGH: indicates the SSD.
size	Integer	Storage. When restoring a distributed instance, you need to specify the storage to be a multiple of (Number of shards x 40 GB). Value range: (Number of shards x 40 GB) to (Number of shards x 16 TB).

**Table 11** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	This field has been discarded.
keep_days	Integer	Retention days for specific backup files. Value: 0 to 732. If this parameter is not specified or is set to 0, the default value 7 is used.

**Table 12** charge_info field data structure description
Parameter	Type	Description
charge_mode	String	Billing mode. postPaid: pay-per-use billing.

Example normal response

{
    "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,
        
        "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"
        },
        
    },
    "job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}

Abnormal response
For details, see Abnormal Request Results.

Status Code

Normal
202
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Backup Management

67 KiB Raw Permalink Blame History