Restore data with BR (Enterprise Edition)¶

For the backed-up NebulaGraph data with the BR tool, you can restore the data. This topic describes how to restore data from backup files.

Notes¶

There will be a period of NebulaGraph service unavailability for data restoration, so it is recommended to operate during the low business peak period.
Restoration requires that the number of the storage servers in the original cluster is the same as that of the storage servers in the target cluster.
After the data restoration is executed successfully, the existing data on the target cluster will be deleted and then replaced with the data in the backup directory. It is recommended to back up the data on the target cluster in advance.

Prerequisites¶

You have installed BR Enterprise Edition and Agent, and have started the Agent(s) that are installed in each machine.

No application is connected to the target NebulaGraph cluster.

Make sure the number of the storage servers in the original cluster is the same as that in the target cluster.

Steps¶

In the BR Enterprise Edition installation directory, follow these steps:

View backup files.

List the backup files in a local path.

./br show --storage local://<storage_path>

For example, you can view the backup files in the local /backup/ path with the following command.

./br show --storage "local:///backup/"
+----------------------------+---------------------+------------------------+-------------+------------+----------------------------+
|            NAME            |     CREATE TIME     |         SPACES         | FULL BACKUP | ALL SPACES |      BASE BACKUP NAME      |
+----------------------------+---------------------+------------------------+-------------+------------+----------------------------+
| BACKUP_2022_08_11_06_12_43 | 2022-08-11 06:12:43 | basketballplayer       | true        | true       |                            |
| BACKUP_2022_08_11_08_27_14 | 2022-08-11 08:27:15 | basketballplayer,br    | false       | true       | BACKUP_2022_08_11_06_12_43 |

List backups in the / path under the nebula-br-test bucket of the S3 protocol-compliant object storage service.

./br show --s3.access_key QImbbGDjfQEYxxxx --s3.secret_key dVSJZfl7tnoFq7Z5zt6sfYnvi63bxxxx  --s3.region us-east-1 --storage s3://nebula-br-test/ --s3.endpoint http://192.168.8.xxx:9000/

List backups in the / path under the nebula-br-test bucket of Google Cloud Storage.

./br show --gs.credentials='{"type":"service_account","project_id":"<project_id>","project_key":"<project_key>","private_key":"<private_key>","client_email":"<service_account_email>","client_id":"<client_id>","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/<service_account_email>","universe_domain":"googleapis.com"}' --storage gs://nebula-br-test/

Restore data.
- Restore data based on local backups.
```
./br restore full --meta <ip_address> --storage <storage_path> --name <backup_name>
```
  For example, restore the BACKUP_2022_08_11_09_11_07 file data from the local /backup/ path to the cluster with the meta address 192.168.8.129:9559:
```
./br restore full --meta "192.168.8.129:9559" --storage "local:///backup/" --name BACKUP_2022_08_11_09_11_07
```
- Restore data based on an S3 protocol-compliant object storage service.
  
  Restore the BACKUP_2022_08_12_07_37_02 backup data from the / path under the nebula-br-test bucket of the S3-compliant object storage service to the cluster with the meta address 192.168.8.129:9559, and specify the restoration log path.
```
./br restore full --meta 192.168.8.129:9559 --s3.accesskey QImbbGDjfQEYxxxx --s3.secretkey dVSJZfl7tnoFq7Z5zt6sfYnvi63bxxxx  --s3.region us-east-1 --storage s3://nebula-br-test/ --s3.endpoint http://192.168.8.xxx:9000/ --log "3.log" --name BACKUP_2022_08_12_07_37_02
```
- Restore data based on Google Cloud Storage.
  Restore the BACKUP_2022_08_12_07_37_02 backup data from the / path under the nebula-br-test bucket of Google Cloud Storage to the cluster with the meta address 168.8.xxx:9559, and specify the restoration log path.
```
./br restore full --meta 168.8.xxx:9559 --gs.credentials='{"type":"service_account","project_id":"<project_id>","project_key":"<project_key>","private_key":"<private_key>","client_email":"<service_account_email>","client_id":"<client_id>","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/<service_account_email>","universe_domain":"googleapis.com"}' --storage gs://nebula-br-test/ --log "3.log" --name BACKUP_2022_08_12_07_37_02
```
If the following information is returned, the data is restored successfully.
```
Restore succeed.
```
Note

If the data restoration fails, BR Enterprise Edition automatically performs a rollback and the cluster's data is automatically recovered back to the pre-restoration data.

If the cluster has mTLS authentication encryption enabled, you need to add additional parameters --enable-ssl, --ca-path, --cert-path, --key-path, and --insecure-skip-verify when executing data restore commands.

For example:
- Restoring data based on local backups in a cluster with mTLS enabled:
```
./br restore full --meta "192.168.8.xxx:9559" --storage "local:///backup/" --name BACKUP_2022_08_11_09_11_07 --enable-ssl --ca-path=<ca_cert_path> --cert-path=<client_cert_path> --key-path=<client_key_path> --insecure-skip-verify=true
```
- Restoring data based on S3 protocol-compliant cloud storage backups in a cluster with mTLS enabled:
  
  bash ./br restore full --meta 192.168.8.xxx:9559 --s3.accesskey QImbbGDjfQEYxxxx --s3.secretkey dVSJZfl7tnoFq7Z5zt6sfYnvi63bxxxx --s3.region us-east-1 --storage s3://nebula-br-test/ --s3.endpoint http://192.168.8.xxx:9000/ --log "3.log" --name BACKUP_2022_08_12_07_37_02 --enable-ssl --ca-path=<ca_cert_path> --cert-path=<client_cert_path> --key-path=<client_key_path> --insecure-skip-verify=true
- Restoring data based on Google Cloud backups in a cluster with mTLS enabled:
```
./br restore full --meta 192.168.8.xxx:9559 --gs.credentials '{"type":"service_account","project_id":"<project_id>","project_key":"<project_key>","private_key":"<private_key>","client_email":"<service_account_email>","client_id":"<client_id>","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/<service_account_email>","universe_domain":"googleapis.com"}' --storage gs://nebula-br-test/ --log "3.log" --name BACKUP_2022_08_12_07_37_02 --enable-ssl --ca-path=<ca_cert_path> --cert-path=<client_cert_path> --key-path=<client_key_path> --insecure-skip-verify=true
```
For descriptions about these parameters, see the section Options below.

Alternatively, you can configure environment variables CA_CERT_PATH, CLIENT_CERT_PATH, and CLIENT_KEY_PATH to specify the storage paths of the CA root certificate, public key certificate, and private key certificate respectively. After these environment variables are configured, you do not need to set the --ca-path, --cert-path, and --key-path parameters in the preceding examples because the environment variables override the corresponding parameters.

Run the following command to clean temporary files. This command will clean up temporary files in the cluster or external storage, and you can also use this command to clean up old backup directories. The example is as follows.

Note

By default, BR automatically cleans up the temporary files when an error occurs during data restoration. If the automatic cleanup fails, you need to execute the command to clean up the temporary files manually.

Clear a local backup directory.

./br cleanup --meta 192.168.8.129:9559 --storage "local:///backup/" --name BACKUP_2022_08_11_09_11_07

Clear the backup directory in a S3 protocol-compliant cloud storage service.

./br cleanup --meta 192.168.8.129:9559 --s3.accesskey QImbbGDjfQEYxxxx --s3.secretkey dVSJZfl7tnoFq7Z5zt6sfYnvi63bxxxx  --s3.region us-east-1 --storage s3://nebula-br-test/ --s3.endpoint http://192.168.8.xxx:9000/ --name BACKUP_2022_08_12_07_37_02

Clear the backup directory in Google Cloud Storage:

    ./br cleanup --meta 192.168.8.xxx:9559 --gs.credentials '{"type":"service_account","project_id":"<project_id>","project_key":"<project_key>","private_key":"<private_key>","client_email":"<service_account_email>","client_id":"<client_id>","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/<service_account_email>","universe_domain":"googleapis.com"}' --storage gs://nebula-br-test/ --name BACKUP_2022_08_12_07_37_02

Options¶

The following options are for data restorations.

Option	Data type	Required	Default value	Description
`-h,-help`	-	No	-	View more information about NebulaGraph Backup&Restore commands.
`--debug`	-	No	None	View more information for NebulaGraph Backup&Restore logs.
`--log`	string	No	"br.log"	The path of NebulaGraph Backup&Restore logs.
`--concurrency`	int	No	None	Used to control the number of concurrent file downloads during data restoration. The default value is `5`.
`--meta`	string	Yes	None	The IP address and port number of any Meta service in the cluster.
`--name`	string	Yes	None	The name of the backup file.
`--storage`	string	Yes	None	The storage URL of the backup is to be restored. The format is `<schema>://<storage_path>`. `schema`: Three options: `local`, `s3`, and `gs`. When `schema` is `s3`, you need to add options of `--s3.access_key`、`--s3.endpoint`、`--s3.region`, and `--s3.secret_key`. When `schema` is `gs`, you need to add the `--gs.credentials` option. `<storage_path>`: The storage path of the backup to be restored.
`--s3.access_key`	string	No	None	The Access Key ID that is used to identify a user.
`--s3.endpoint`	string	No	None	The S3 endpoint URL. You need to specify the HTTP or HTTPS scheme explicitly.
`--s3.region`	string	No	None	The physical location of a data center.
`--s3.secret_key`	string	No	None	The Access Key Secret that is used to verify the identity of the user.
`--enable-ssl`	-	No	None	Enable mTLS encryption for mutual authentication with NebulaGraph.
`--ca-path`	string	No	None	Storage path for the CA root certificate. The default path is `/usr/local/certs/ca.crt`.
`--cert-path`	string	No	None	Storage path for the public key certificate. The default path is `/usr/local/certs/client.crt`.
`--key-path`	string	No	None	Storage path for the private key certificate. The default path is `/usr/local/certs/client.key`.
`--insecure-skip-verify`	bool	No	False	Specify whether to skip verifying the server's certificate chain and hostname. The default is `false`, meaning it verifies the server's provided certificate chain and hostname. If set to `true`, verification is skipped.
`--gs.credentials`	string	No	None	The JSON string that represents your service account key provided by Google Cloud. For more information, see Create and delete service account keys.

View restoration progress¶

The log file br.log of BR can be viewed in the installation directory. The log file will record the restoration progress and will look like as follows:

{"level":"info","msg":"download storaged partition finished, progress: 1/20","time":"2023-03-15T02:16:43.430Z"}
{"level":"info","msg":"download storaged partition finished, progress: 2/20","time":"2023-03-15T02:16:43.431Z"}
{"level":"info","msg":"download storaged partition finished, progress: 3/20","time":"2023-03-15T02:16:43.763Z"}

Last update: February 6, 2024