This is an automated email from the ASF dual-hosted git repository.
sunnianjun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shardingsphere-on-cloud.git
The following commit(s) were added to refs/heads/main by this push:
new 96611b3 docs: update Pitr readme (#473)
96611b3 is described below
commit 96611b3331ec361bb2ba84298b76d84db0eff2af
Author: liyao <[email protected]>
AuthorDate: Thu Nov 23 17:01:46 2023 +0800
docs: update Pitr readme (#473)
* chore: add hyperlink to Readme-zh
Signed-off-by: mlycore <[email protected]>
* chore: adjust hyperlink
Signed-off-by: mlycore <[email protected]>
* chore: add index
Signed-off-by: mlycore <[email protected]>
* chore: add glt and update instruction
Signed-off-by: mlycore <[email protected]>
* docs: update readme environment description
Signed-off-by: mlycore <[email protected]>
* docs: add glt description
Signed-off-by: mlycore <[email protected]>
* docs: update english version of Pitr readme
Signed-off-by: mlycore <[email protected]>
* docs: update english content
Signed-off-by: mlycore <[email protected]>
---------
Signed-off-by: mlycore <[email protected]>
---
pitr/README-zh.md | 110 +++++++++++++++++++++++++++++++++--------------------
pitr/README.md | 111 ++++++++++++++++++++++++++++++++++--------------------
2 files changed, 139 insertions(+), 82 deletions(-)
diff --git a/pitr/README-zh.md b/pitr/README-zh.md
index 249c91c..6c4738d 100644
--- a/pitr/README-zh.md
+++ b/pitr/README-zh.md
@@ -1,27 +1,28 @@
# 目录
-```shell
-使用说明
- 前置准备
- 服务器说明
- 环境说明
- 编译说明（可选）
- SSL 配置
- 生成新的 SSL 密钥对（可选）
- 部署说明
- 步骤1：获取 Pitr 二进制
- 下载二进制包
- 自行编译
- 步骤2：准备 ShardingSphere Proxy 配置
- 步骤3：配置 OpenGauss
- 步骤4：为 Pitr Agent 部署 SSL 证书
- 步骤5：启动 Pitr Agent
- 测试说明
- 准备测试数据
- 测试用例
- 备份
- 恢复
-```
+* [使用说明](#使用说明)
+ * [前置准备](#前置说明)
+ * [服务器说明](#服务器说明)
+ * [环境说明](#环境说明)
+ * [编译说明（可选）](#编译说明可选)
+ * [SSL 配置](#ssl-配置)
+ * [生成新的 SSL 密钥对（可选）](#生成新的-ssl-密钥对可选)
+ * [部署说明](#部署说明)
+ * [步骤1：获取 Pitr 二进制](#步骤1-获取-pitr-二进制)
+ * [下载二进制包](#下载二进制包)
+ * [自行编译](#自行编译)
+ * [步骤2：准备 ShardingSphere Proxy 配置](#步骤-2-准备-shardingsphere-proxy-配置)
+ * [步骤3：配置 OpenGauss](#步骤-3-配置-opengauss)
+ * [步骤4：为 Pitr Agent 部署 SSL 证书](#步骤-4-为-pitr-agent-部署-ssl-证书)
+ * [步骤5：启动 Pitr Agent](#步骤-5-启动-pitr-agent)
+ * [测试说明](#测试说明)
+ * [准备测试数据](#准备测试数据)
+ * [测试用例](#测试用例)
+ * [备份](#备份)
+ * [查看备份](#查看备份)
+ * [恢复](#恢复)
+ * [删除备份](#删除备份)
+* [使用限制](#使用限制)
# 使用说明
@@ -47,7 +48,7 @@
| | 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 |
@@ -56,14 +57,16 @@
在服务器都准备就绪后，你需要检查和确认如下内容：
- Apache ShardingSphere 所在的服务器允许访问呢 OpenGauss 所在的服务器
-- 允许从外部访问 Apache ShardingSphere
-- 允许从外部通过 18080 端口访问 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
#### 编译说明（可选）
@@ -115,7 +118,7 @@ make openssl-local
## 部署说明
-Pitr cli （即 `gs_pitr`）和 Pitr agent （即 `pitr-agent`）二进制都可以在[Apache
ShardingSphere on Cloud
的发布页](https://github.com/apache/shardingsphere-on-cloud/releases)下载，或者在你的环境中按前述步骤手动编译得到。
+Pitr cli （即 `gs_pitr`）和 Pitr agent （即 `pitr-agent`）二进制都可以在 [Apache
ShardingSphere on Cloud
的发布页](https://github.com/apache/shardingsphere-on-cloud/releases)下载，或者在你的环境中按前述步骤手动编译得到。
整个部署过程由如下两个步骤构成：
@@ -164,6 +167,14 @@ authority:
privilege:
type: ALL_PERMITTED
+transaction:
+ defaultType: XA
+ providerType: Atomikos
+
+props:
+ proxy-frontend-database-protocol-type: openGauss
+
+# 以下配置为 GLT 相关配置
globalClock:
enabled: true
type: TSO
@@ -172,13 +183,6 @@ globalClock:
host: 127.0.0.1
port: 6379
-transaction:
- defaultType: XA
- providerType: Atomikos
-
-props:
- proxy-frontend-database-protocol-type: openGauss
-
```
config-sharding.yaml
@@ -332,7 +336,7 @@ select * from t_user;
执行备份：
```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
```
参数说明:
@@ -345,9 +349,11 @@ select * from t_user;
- dn-threads-path: OpenGauss 备份文件路径
- b: 备份模式
-检查备份并查看备份 id：
+#### 查看备份
+
+查看备份：
```Shell
-./gs_pitr show
+./gs_pitr show
```
#### 恢复
@@ -360,7 +366,7 @@ delete from t_user where user_id=2;
执行恢复：
```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}
```
参数说明:
@@ -370,6 +376,7 @@ delete from t_user where user_id=2;
- password: ShardingSphere Proxy 连接密码
- agent-port: Pitr Agent 监听端口
- dn-backup-path: OpenGauss 备份文件路径
+- dn-threads-num: OpenGauss 并发恢复数量
- id: 备份 id
验证数据:
@@ -377,12 +384,33 @@ delete from t_user where user_id=2;
select * from t_user;
```
+#### 删除备份
+
+删除备份：
+```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}
+```
+
+参数说明：
+- host: ShardingSphere Proxy 服务器
+- port: ShardingSphere Proxy 监听端口
+- username: ShardingSphere Proxy 连接用户名
+- password: ShardingSphere Proxy 连接密码
+- agent-port: Pitr Agent 监听端口
+- dn-backup-path: OpenGauss 备份文件路径
+- id: 备份 id
+
# 使用限制
+- Pitr 备份恢复功能的使用需要开启 GLT，并在 ShardingSphere 中进行配置。如果没有 GLT，那么 Pitr 无法依据 CSN
保证一致性
+- GLT 部署可以使用 Redis，无需对 Redis 进行额外配置
- 全局备份任务需要在没有进行中的事务的时间点进行开启，由 ShardingSphere 来加锁保证
-- ShardingSphere 备份元数据存储在 Pitr cli 本地，如果需要另一台设备上需要恢复，需要复制对应备份数据到对应设备
-- 恢复操作需要停机，并且为同步操作，用户需保证完全恢复成功
-- 恢复前后 OpenGauss 数据节点的 IP 地址和端口需保持不变
+- 备份开始后 ShardingSphere 会一直持有锁，当备份结束后才会释放锁
- 多个 Pitr cli 客户端同时操作，只有一个 Pitr cli 客户端可执行成功
+- 恢复前后 OpenGauss 数据节点的 IP 地址和端口需保持不变，即和 ShardingSphere 中逻辑库注册的数据源保持一致
+- 恢复时，保证 ShardingSphere 在备份时和恢复时使用的版本一致，确保元数据兼容
+- 恢复操作需要停机，并且为同步操作，用户需保证完全恢复成功
- 当恢复失败时，OpenGauss 数据节点存在状态不一致，需用户重新发起恢复操作，保证最终恢复成功
-- 恢复时，保证 ShardingSphere 备份和恢复的版本一致，确保元数据兼容
\ No newline at end of file
+- 当执行备份后，会在当前用户的 `$HOME` 下创建 `.gs_pitr/backup` 目录，并在该目录下存放备份元数据文件
+- 如果需要另一台设备上需要恢复，需要复制该路径下的备份数据到对应设备的相同路径
+- 当执行删除备份后，当前用户的 `$HOME/.gs_pitr/backup` 下的备份文件将被删除
\ No newline at end of file
diff --git a/pitr/README.md b/pitr/README.md
index 5455cb0..ae6af00 100644
--- a/pitr/README.md
+++ b/pitr/README.md
@@ -1,26 +1,28 @@
# 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)
+ * [Show](#show-backup-info)
+ * [Recovery](#recovery)
+ * [Deletion](#deletion)
+* [Limitations](#limitations)
# README
@@ -48,7 +50,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 |
@@ -57,14 +59,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)
@@ -166,14 +170,6 @@ 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
@@ -181,6 +177,14 @@ transaction:
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
@@ -333,7 +337,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:
@@ -346,7 +350,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
@@ -362,7 +368,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:
@@ -371,6 +377,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
@@ -379,12 +386,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.
\ No newline at end of file
+- 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`
