Skip to content

Commit

Permalink
docs: update english version of Pitr readme
Browse files Browse the repository at this point in the history 
Signed-off-by: mlycore <miaoliyao@apache.org>
  • Loading branch information
@mlycore
mlycore committed Nov 23, 2023
1 parent 80ae679 commit 7bfa025
Showing 1 changed file with 67 additions and 39 deletions.
106 changes: 67 additions & 39 deletions pitr/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,26 @@
# Content
```shell
README
Prerequisition
Servers
Environment
Compilation (optional)
SSL Configurations
Generate new SSL keypair (Optional)
Deployment
Step 1: Get Pitr tools
Get binary release
Compile it yourself
Step 2: Get ShardingSphere Proxy Configurations
Step 3: Set OpenGauss Configurations
Step 4: Deploy SSL certs for Pitr Agent
Step 5: Start Pitr Agent
Test
Prepare Test Data
Test Case
Backup
Recovery
* [README](#readme)
* [Prerequisition](#prerequisition)
* [Servers](#servers)
* [Environment](#environment)
* [Compilation (optional) ](#compilation-optional)
* [SSL Configurations](#ssl-configurations)
* [Generate new SSL keypair (Optional) ](#generate-new-ssl-keypair-optional)
* [Deployment](#deployment)
* [Step 1: Get Pitr tools](#step-1-get-pitr-tools)
* [Get binary release](#get-binary-release)
* [Compile it yourself](#compile-it-yourself)
* [Step 2: Get ShardingSphere Proxy Configurations](#step-2-get-shardingsphere-proxy-configurations)
* [Step 3: Set OpenGauss Configurations](#step-3-set-opengauss-configurations)
* [Step 4: Deploy SSL certs for Pitr Agent](#step-4-deploy-ssl-certs-for-pitr-agent)
* [Step 5: Start Pitr Agent](#step-5-start-pitr-agent)
* [Test](#test)
* [Prepare Test Data](#prepare-test-data)
* [Test Case](#test-case)
* [Backup](#backup)
* [Recovery](#recovery)
* [Limitations](#limitations)
```
# README
Expand Down Expand Up @@ -48,7 +49,7 @@ You need to prepare at least three servers: one server for the Pitr commandline
| | Role | Components |
|:-:|:-:|:-:|
|1| Pitr cli operation server | Pitr Cli + ShardingSphere Proxy + Zookeeper|
|1| Pitr cli operation server | Pitr Cli + ShardingSphere Proxy + Zookeeper + GLT |
|2| OpenGauss Server 1 | OpenGauss Server + Pitr Agent |
|3| OpenGauss Server 2 | OpenGauss Server + Pitr Agent |
Expand All @@ -57,14 +58,16 @@ You need to prepare at least three servers: one server for the Pitr commandline
After the servers are ready, you should check and ensure the following items:
- Apache ShardingSphere Proxy is allowed to access OpenGauss Servers
- External access to Apache ShardingSphere Proxy
- External access to OpenGauss Server via port 18080
- External access to Apache ShardingSphere Proxy via port 3307
- External access to Pitr agent on OpenGauss servers via port 18080
- Set below environment variables on OpenGauss Servers
- export PGDATABASE=tpccdb
- export PGPORT=13100
- OpenGauss has user `omm` and database `omm` which can be accessed
- OpenGauss enables `cbm tracking`
- SSL key pairs. Any valid key pairs are acceptable, they will be used for Pitr cli-agent secure communication
- Create OpenGauss backup path manually and keep it same between OpenGauss servers
- Deploy GLT service such a Redis, in order to provide CSN to ShardingSphere and OpenGauss distributed database
#### Compilation (optional)
Expand Down Expand Up @@ -166,21 +169,21 @@ authority:
privilege:
type: ALL_PERMITTED
globalClock:
enabled: true
type: TSO
provider: redis
props:
host: 127.0.0.1
port: 6379

transaction:
defaultType: XA
providerType: Atomikos
props:
proxy-frontend-database-protocol-type: openGauss
# Below is GLT related configs
globalClock:
enabled: true
type: TSO
provider: redis
props:
host: 127.0.0.1
port: 6379
```
config-sharding.yaml
Expand Down Expand Up @@ -333,7 +336,7 @@ select * from t_user;
#### Backup
```Shell
./gs_pitr backup --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307 --username sharding --agent-port 18080 --dn-threads-num 1 --dn-backup-path "/home/omm/data" -b FULL
./gs_pitr backup --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307 --username sharding --agent-port 18080 --dn-threads-num 10 --dn-backup-path "/home/omm/data" -b FULL
```
Parameters:
Expand All @@ -346,7 +349,9 @@ Parameters:
- dn-threads-path: OpenGauss backup files path
- b: Backup mode
Check backups and get the backup id for recovery.
#### Show backup info
Show backups:
```Shell
./gs_pitr show
Expand All @@ -362,7 +367,7 @@ delete from t_user where user_id=2;
Do recovery:
```Shell
./gs_pitr restore --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307 --username sharding --agent-port 18080 --dn-backup-path "/home/omm/data" --id ${BACKUP_ID}
./gs_pitr restore --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307 --username sharding --agent-port 18080 --dn-threads-num 10 --dn-backup-path "/home/omm/data" --id ${BACKUP_ID}
```
Parameters:
Expand All @@ -371,6 +376,7 @@ Parameters:
- username: ShardingSphere Proxy user
- password: ShardingSphere Proxy password
- agent-port: Pitr agent port
- dn-threads-num: OpenGauss concurrent restore
- dn-backup-path: OpenGauss backup files path
- id: Backup id
Expand All @@ -379,12 +385,34 @@ Verify data:
select * from t_user;
```
# Restrictions
#### Deletion
Delete backup :
```Shell
./gs_pitr delete --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307 --username sharding --agent-port 18080 --dn-backup-path "/home/omm/data" --id ${BACKUP_ID}
```
Parameters:
- host: ShardingSphere Proxy server
- port: ShardingSphere Proxy port
- username: ShardingSphere Proxy user
- password: ShardingSphere Proxy password
- agent-port: Pitr agent port
- dn-backup-path: OpenGauss backup files path
- id: Backup id
# Limitations
- Pitr backup and restore depends on GLT which is configured in ShardingSphere. Pitr can not ensure consistency without CSN if there is no GLT
- Redis can be deployed as GLT service without any extra configuration
- Global backup tasks need to be executed while there is no uncommitted transaction, and this will be ensuranced by ShardingSphere lock.
- The backup metadata of ShardingSphere will be stored on the same host with the Pitr cli. You need to copy this metadata backup to the another host first where you want to start recovery.
- The recovery operation need to stop service, and it is a synchonized operation. Users have to make sure the success of the recovery operation.
- OpenGauss data nodes should use the same IP and port while backup and recovery
- ShardingSphere will hold the lock until the whole backup process is done
- Only one Pitr cli could successfully if multiple cli are executed simutaneously
- OpenGauss data nodes should use the same IP and port while backup and recovery
- Using the same version of ShardingSphere while backup and recovery to make sure the metadata is compatible.
- The recovery operation need to stop service, and it is a synchonized operation. Users have to make sure the success of the recovery operation.
- OpenGauss servers may under inconsistent status if recovery fails. Users need to try to recovery again until it is succeed.
- Using the same version of ShardingSphere while backup and recovery to make sure the metadata is compatible.
- Pitr cli will create a directory `.gs_pitr/backup` under user `$HOME` and save backup metadata files under it
- You need to copy this metadata backup to the another host first where you want to restore.
- The backup file under directory `$HOME/.gs_pitr/backup` will be deleted after the execution of `gs_pitr delete`

0 comments on commit 7bfa025

Please sign in to comment.