Skip to content

Commit

Permalink
docs: update pitr readme (#484)
Browse files Browse the repository at this point in the history 
* docs: update pitr zh readme

Signed-off-by: mlycore <[email protected]>

* docs: fix link

Signed-off-by: mlycore <[email protected]>

* docs: fix link

Signed-off-by: mlycore <[email protected]>

* docs: fix link

Signed-off-by: mlycore <[email protected]>

* docs: fix link

Signed-off-by: mlycore <[email protected]>

* docs: update english version readme

Signed-off-by: mlycore <[email protected]>

---------

Signed-off-by: mlycore <[email protected]>
  • Loading branch information
@mlycore
mlycore authored Dec 26, 2023
1 parent 829f4b8 commit 28e0c37
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 90 deletions.
104 changes: 59 additions & 45 deletions pitr/README-zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,24 +49,28 @@
| | Role | Components |
|:-:|:-:|:-:|
|1| Pitr cli operation server | Pitr Cli + ShardingSphere Proxy + Zookeeper + GLT |
|2| OpenGauss Server 1 | OpenGauss Server + Pitr Agent |
|2| OpenGauss Server 1 | OpenGauss Server + Pitr Agent |
|3| OpenGauss Server 2 | OpenGauss Server + Pitr Agent |

### 环境说明

在服务器都准备就绪后，你需要检查和确认如下内容：

- Apache ShardingSphere 所在的服务器允许访问呢 OpenGauss 所在的服务器
- 允许从外部通过 3307 端口访问 Apache ShardingSphere
- 允许从外部通过 18080 端口访问 OpenGauss 服务器上的 Pitr Agent
- 在 OpenGauss 服务器上设置如下环境变量：
- export PGDATABASE=tpccdb
- export PGPORT=13100
- OpenGauss 使用用户 `omm` 并且可以访问数据库 `omm`
- OpenGauss 开启了 `cbm tracking`
- SSL 密钥对。用来提供 Pitr 命令行工具和 Pitr Agent 之间的安全通信，可以使用任何有效的密钥对
- 需要手动在每个节点创建期望的备份数据路径，并保证多个节点路径是一致的
- 需要部署 GLT 服务，比如 Redis，用来向 ShardingSphere 和 OpenGauss 构成的分布式数据库提供全局 CSN
- Apache ShardingSphere
- 所在的服务器允许访问 OpenGauss 所在的服务器
- 如果通过 3307 暴露服务，则允许外部访问服务器的 3307 端口
- GLT
- 需要部署 Redis 作为 GLT 服务，用来向 ShardingSphere 和 OpenGauss 构成的分布式数据库提供全局 CSN
- OpenGauss
- OpenGauss 使用用户 `omm` 并且可以访问数据库 `omm`
- OpenGauss 开启了 `cbm tracking`
- 设置环境变量
- export PGDATABASE=tpccdb
- export PGPORT=13100
- Pitr
- 如果通过 18080 暴露 Pitr Agent 服务，则允许外部访问服务器的 18080 端口
- SSL 密钥对。用来提供 Pitr 命令行工具和 Pitr Agent 之间的安全通信，可以使用任何有效的密钥对。可见[SSL 配置](#ssl-配置)


#### 编译说明（可选）

Expand Down Expand Up @@ -210,18 +214,16 @@ dataSources:
minPoolSize: 1
```
然后使用脚本 `bin/start.sh` 来启动 ShardingSphere Proxy。脚本可以在 apache-shardingsphere-{version}-shardingsphere-proxy-bin.tar.gz 中找到。
然后使用脚本 `bin/start.sh` 来启动 ShardingSphere Proxy。脚本包含在 apache-shardingsphere-{version}-shardingsphere-proxy-bin.tar.gz 中。

### 步骤 3: 配置 OpenGauss
### 步骤 3: 配置并启动 OpenGauss

a. 在 postgres.conf 中开启 `cbm tracking`
在 postgres.conf 中开启 `cbm tracking`

```shell
enable_cbm_tracking = on
```

b. 执行 `gs_probackup init -B ${backup-path}` 来设置期望的备份路径

然后可以启动所有的 OpenGauss 服务。


Expand Down Expand Up @@ -270,7 +272,10 @@ drwx------ 29 omm omm 4.0K May 23 11:37 pgdata
```

参数说明:
- pgdata: OpenGauss 数据存储路径。当未指定时，可以通过 `--env-source-file` 或通过环境变量 `PGDATA` 进行指定
- pgdata: OpenGauss 数据存储路径。可以通过该参数、 环境变量 `PGDATA` 和`--env-source-file` 进行指定。优先级如下：
- pgdata 参数
- 环境变量 `PGDATA`
- `env-source-file`
- port: Pitr agent 暴露端口
- tls-crt: TLS 证书文件路径
- tls-key: TLS 私钥文件路径
Expand Down Expand Up @@ -341,14 +346,15 @@ select * from t_user;
```

参数说明:
- host: SharidngSphere Proxy 服务器
- port: ShardingSphere Proxy 监听端口
- username: ShardingSphere Proxy 连接用户名
- password: ShardingSphere Proxy 连接密码
- agent-port: Pitr Agent 监听端口
- dn-threads-num: OpenGauss 并发备份数量
- dn-threads-path: OpenGauss 备份文件路径
- b: 备份模式
- -a，--agent-port: Pitr Agent 监听端口
- -b，--dn-backup-mode: OpenGauss 备份模式
- -B，--dn-backup-path：OpenGauss 备份文件路径
- -j，--dn-threads-num: OpenGauss 并发备份数量
- -h，--help：帮助文档
- -H，--host: SharidngSphere Proxy 服务器
- -p，--password: ShardingSphere Proxy 连接密码
- -P，--port: ShardingSphere Proxy 监听端口
- -u，--username: ShardingSphere Proxy 连接用户名

#### 查看备份

Expand All @@ -357,6 +363,11 @@ select * from t_user;
./gs_pitr show
```

参数说明:
- --csn: 备份记录 CSN 序号
- -h，--help：帮助文档
- --id: 备份记录 ID

#### 恢复

你需要先删除部分 `t_user` 表中的记录：
Expand All @@ -371,14 +382,16 @@ delete from t_user where user_id=2;
```

参数说明:
- host: ShardingSphere Proxy 服务器
- port: ShardingSphere Proxy 监听端口
- username: ShardingSphere Proxy 连接用户名
- password: ShardingSphere Proxy 连接密码
- agent-port: Pitr Agent 监听端口
- dn-backup-path: OpenGauss 备份文件路径
- dn-threads-num: OpenGauss 并发恢复数量
- id: 备份 id
- -a，--agent-port: Pitr Agent 监听端口
- --csn：备份记录 CSN 序列号
- -B，--dn-backup-path：OpenGauss 备份文件路径
- -j，--dn-threads-num: OpenGauss 并发恢复数量
- -h，--help：帮助文档
- -H，--host: SharidngSphere Proxy 服务器
- --id，备份记录 ID
- -p，--password: ShardingSphere Proxy 连接密码
- -P，--port: ShardingSphere Proxy 监听端口
- -u，--username: ShardingSphere Proxy 连接用户名

验证数据:
```SQL
Expand All @@ -392,19 +405,20 @@ select * from t_user;
./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}
```

参数说明：
- host: ShardingSphere Proxy 服务器
- port: ShardingSphere Proxy 监听端口
- username: ShardingSphere Proxy 连接用户名
- password: ShardingSphere Proxy 连接密码
- agent-port: Pitr Agent 监听端口
- dn-backup-path: OpenGauss 备份文件路径
- id: 备份 id
参数说明:
- -a，--agent-port: Pitr Agent 监听端口
- --csn：备份记录 CSN 序列号
- -B，--dn-backup-path：OpenGauss 备份文件路径
- -h，--help：帮助文档
- -H，--host: SharidngSphere Proxy 服务器
- --id，备份记录 ID
- -p，--password: ShardingSphere Proxy 连接密码
- -P，--port: ShardingSphere Proxy 监听端口
- -u，--username: ShardingSphere Proxy 连接用户名

# 使用限制

- Pitr 备份恢复功能的使用需要开启 GLT，并在 ShardingSphere 中进行配置。如果没有 GLT，那么 Pitr 无法依据 CSN 保证一致性
- GLT 部署可以使用 Redis，无需对 Redis 进行额外配置
- Pitr 备份恢复功能的使用依赖 GLT，通过部署 Redis 实现。如果没有 GLT，那么生成的 CSN 会为空，导致恢复无法根据 CSN 保证一致性，此时恢复命令执行只能使用备份 ID
- 全局备份任务需要在没有进行中的事务的时间点进行开启，由 ShardingSphere 来加锁保证
- 备份开始后 ShardingSphere 会一直持有锁，当备份结束后才会释放锁
- 多个 Pitr cli 客户端同时操作，只有一个 Pitr cli 客户端可执行成功
Expand All @@ -415,4 +429,4 @@ select * from t_user;
- 当执行备份后，会在当前用户的 `$HOME` 下创建 `.gs_pitr/backup` 目录，并在该目录下存放备份元数据文件
- 如果需要另一台设备上需要恢复，需要复制路径 `$HOME/.gs_pitr/backup` 下的备份数据到对应设备的相同路径
- 当执行删除备份后，当前用户的 `$HOME/.gs_pitr/backup` 下的备份文件将被删除
- 当命令行执行过程中，`Ctrl-C` 取消或者 `kill` 中止进程，不会同时停止服务端正在执行的任务
- 当命令行执行过程中，`Ctrl-C` 取消或者 `kill` 中止进程，不会同时停止服务端正在执行的任务
103 changes: 58 additions & 45 deletions pitr/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,17 +58,20 @@ 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 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
- Apache ShardingSphere
- Allow access to openGauss server from ShardingSphere server
- Allow external access to ShardingSphere Proxy via port 3307 if using this port
- GLT
- GLT is required to provide global CSN for distributed database, this can be done by Redis
- OpenGauss
- OpenGauss has user `omm` and database `omm` which can be accessed
- OpenGauss enables `cbm tracking`
- Set below environment variables on OpenGauss Servers
- export PGDATABASE=tpccdb
- export PGPORT=13100
- Pitr
- External access to Pitr agent on OpenGauss servers via port 18080 if using this port
- SSL key pairs. Any valid key pairs are acceptable, they will be used for Pitr cli-agent secure communication

#### Compilation (optional)

Expand Down Expand Up @@ -216,12 +219,11 @@ And using the script `bin/start.sh` to start ShardingSphere Proxy. This script c

### Step 3: Set OpenGauss Configurations

a. Enable `cbm tracking` in postgres.conf
Enable `cbm tracking` in postgres.conf

```shell
enable_cbm_tracking = on
```
b. Execute `gs_probackup init -B ${backup-path}` to set the expected backup path.

Then you can start both OpenGauss servers.

Expand Down Expand Up @@ -271,7 +273,10 @@ drwx------ 29 omm omm 4.0K May 23 11:37 pgdata
```

Parameters:
- pgdata: OpenGauss data storage path. Using `--env-source-file` or envvar `PGDATA` if it is not specified in command line.
- pgdata: OpenGauss data storage path. Using `--env-source-file` or envvar `PGDATA` if it is not specified in command line. Priority is :
- commandline parameter `pgdata`
- environment variable `PGDATA`
- environment source file `env-source-file`
- port: Pitr agent exposed port
- tls-crt: TLS crt file path
- tls-key: TLS key file path
Expand Down Expand Up @@ -341,14 +346,16 @@ select * from t_user;
```

Parameters:
- host: ShardingSphere Proxy server
- port: ShardingSphere Proxy port
- username: ShardingSphere Proxy user
- password: ShardingSphere Proxy password
- agent-port: Pitr agent port
- dn-threads-num: OpenGauss concurrent backup
- dn-threads-path: OpenGauss backup files path
- b: Backup mode
- -a, --agent-port: Pitr agent port
- -b, --dn-backup-mode: Backup mode
- -B, --dn-threads-path: OpenGauss backup files path
- -j, --dn-threads-num: OpenGauss concurrent backup
- -h, --help: help manual
- -H, --host: ShardingSphere Proxy server
- -p, --password: ShardingSphere Proxy password
- -P, --port: ShardingSphere Proxy port
- -u, --username: ShardingSphere Proxy user


#### Show backup info

Expand All @@ -357,6 +364,9 @@ Show backups:
```Shell
./gs_pitr show
```
- --csn: csn of backup record
- -h, --help: help manual
- --id: id of backup record

#### Recovery

Expand All @@ -372,14 +382,16 @@ Do recovery:
```

Parameters:
- host: ShardingSphere Proxy server
- port: ShardingSphere Proxy port
- 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
- -a, --agent-port: Pitr agent port
- --csn: csn of backup record
- -B, --dn-threads-path: OpenGauss backup files path
- -j, --dn-threads-num: OpenGauss concurrent backup
- -h, --help: help manual
- -H, --host: ShardingSphere Proxy server
- -id: id of backup record
- -p, --password: ShardingSphere Proxy password
- -P, --port: ShardingSphere Proxy port
- -u, --username: ShardingSphere Proxy user

Verify data:
```SQL
Expand All @@ -394,27 +406,28 @@ Delete backup :
```

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
- -a, --agent-port: Pitr agent port
- --csn: csn of backup record
- -B, --dn-threads-path: OpenGauss backup files path
- -h, --help: help manual
- -H, --host: ShardingSphere Proxy server
- -id: id of backup record
- -p, --password: ShardingSphere Proxy password
- -P, --port: ShardingSphere Proxy port
- -u, --username: ShardingSphere Proxy user


# 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.
- Pitr backup and restore depends on GLT which is implemented using Redis. Pitr can not ensure consistency without CSN if there is no GLT, and only backup id could be used for pitr restore
- Global backup tasks need to be executed while there is no uncommitted transaction, and this will be ensuranced by ShardingSphere lock
- 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, such as one data node succeed while another failed. Users need to handle the exception and 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
- 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, such as one data node succeed while another failed. Users need to handle the exception and try to recovery again until it is succeed
- 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 under `$HOME/.gs_pitr/bakcup` to the another host first where you want to restore.
- You need to copy this metadata backup under `$HOME/.gs_pitr/bakcup` 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`
- Canceling the executing `gs_pitr` command on client side using either `Ctrl-C` or `kill` will do nothing about the execution of server task.
- Canceling the executing `gs_pitr` command on client side using either `Ctrl-C` or `kill` will do nothing about the execution of server task

0 comments on commit 28e0c37

Please sign in to comment.