Skip to content

Commit b6dbf74

Browse files
BornChangerBornChanger
committed
sql-statements: BR / PITR SQL enhancement
Signed-off-by: BornChanger <[email protected]>
1 parent c35b7e9 commit b6dbf74

File tree

6 files changed

+412
-0
lines changed

6 files changed

+412
-0
lines changed

‎TOC.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -698,6 +698,7 @@
698698
- [`BACKUP`](/sql-statements/sql-statement-backup.md)
699699
- [`BATCH`](/sql-statements/sql-statement-batch.md)
700700
- [`BEGIN`](/sql-statements/sql-statement-begin.md)
701+
- [`BR JOB ADMIN](/sql-statements/sql-statement-br-job-admin.md)
701702
- [`CANCEL LOAD DATA` 和 `DROP LOAD DATA`](/sql-statements/sql-statement-operate-load-data-job.md)
702703
- [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md)
703704
- [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md)
@@ -750,6 +751,7 @@
750751
- [`LOCK STATS`](/sql-statements/sql-statement-lock-stats.md)
751752
- [`LOCK TABLES` 和 `UNLOCK TABLES`](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md)
752753
- [`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md)
754+
- [`PITR](/sql-statements/sql-statement-pitr.md)
753755
- [`PREPARE`](/sql-statements/sql-statement-prepare.md)
754756
- [`RECOVER TABLE`](/sql-statements/sql-statement-recover-table.md)
755757
- [`RENAME INDEX`](/sql-statements/sql-statement-rename-index.md)
@@ -770,6 +772,7 @@
770772
- [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md)
771773
- [`SET [GLOBAL|SESSION] <variable>`](/sql-statements/sql-statement-set-variable.md)
772774
- [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md)
775+
- [`SHOW BACKUP METADATA](/sql-statements/sql-statement-show-backup-meta.md)
773776
- [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md)
774777
- [`SHOW [GLOBAL|SESSION] BINDINGS`](/sql-statements/sql-statement-show-bindings.md)
775778
- [`SHOW BUILTINS`](/sql-statements/sql-statement-show-builtins.md)

‎sql-statements/sql-statement-backup.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,3 +187,6 @@ BACKUP DATABASE `test` TO 'local:///mnt/backup/hist03'
187187

188188
* [RESTORE](/sql-statements/sql-statement-restore.md)
189189
* [SHOW BACKUPS](/sql-statements/sql-statement-show-backups.md)
190+
* [PITR](/sql-statements/sql-statement-pitr.md)
191+
* [BR_JOB_ADMIN](/sql-statements/sql-statement-br-job-admin.md)
192+
* [SHOW_BACKUP_META](/sql-statements/sql-statement-show-backup-meta.md)

‎sql-statements/sql-statement-br-job-admin.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: BR JOB ADMIN
3+
summary: TiDB 数据库中 BR 作业管理语句的使用概况。
4+
aliases: ['/docs-cn/dev/sql-statements/sql-statement-br-job-admin']
5+
---
6+
7+
本文介绍 TiDB BR (BACKUP & RESTORE) 作业管理语句，包括下面几种语句：
8+
```sql
9+
SHOW BR JOB --show information of a br task
10+
SHOW BR JOB QUERY --show the query statement of a br task
11+
CANCEL BR JOB --cancel a br task
12+
```
13+
> **警告：**
14+
>
15+
> TiDB BR 作业管理语句在 v7.1.0 是实验特性，其语法或者行为表现在 GA 前可能会发生变化。
16+
>
17+
### 显示 br 作业信息
18+
19+
按照 task id 展示一个 br 作业的信息
20+
21+
#### 语法图
22+
23+
```ebnf+diagram
24+
StreamShowJobStmt ::=
25+
"SHOW" "BR" "JOB" Int64Num
26+
```
27+
28+
#### 示例
29+
30+
{{< copyable "sql" >}}
31+
32+
```sql
33+
SHOW BR JOB 13456;
34+
```
35+
36+
### 显示 br 作业运行的 SQL 语句
37+
38+
按照 task id 展示一个 br 作业运行的 SQL 语句
39+
40+
#### 语法图
41+
42+
```ebnf+diagram
43+
StreamShowQueryStmt ::=
44+
"SHOW" "BR" "JOB" "QUERY" Int64Num
45+
```
46+
47+
#### 示例
48+
49+
{{< copyable "sql" >}}
50+
51+
```sql
52+
SHOW BR JOB QUERY 13456;
53+
```
54+
55+
### 取消一个 br 作业
56+
57+
按照 task id 取消一个 br 作业的运行
58+
59+
#### 语法图
60+
61+
```ebnf+diagram
62+
StreamCancelJobStmt ::=
63+
"CANCEL" "BR" "JOB" Int64Num
64+
```
65+
66+
#### 示例
67+
68+
{{< copyable "sql" >}}
69+
70+
```sql
71+
CANCEL BR JOB 13456;
72+
```
73+
74+
## MySQL 兼容性
75+
76+
该语句是 TiDB 对 MySQL 语法的扩展。
77+
78+
## 另请参阅
79+
80+
* [BACKUP](/sql-statements/sql-statement-backup.md)
81+
* [SHOW BACKUPS](/sql-statements/sql-statement-show-backups.md)
82+
* [SHOW RESTORES](/sql-statements/sql-statement-show-backups.md)
83+
* [RESTORE](/sql-statements/sql-statement-restore.md)
84+
* [PITR](/sql-statements/sql-statement-pitr.md)
85+
* [SHOW_BACKUP_META](/sql-statements/show-backp-meta.md)

‎sql-statements/sql-statement-pitr.md

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
title: TiDB 日志备份与 PITR 语句
3+
summary: 介绍 TiDB 日志备份与 PITR 的 SQL 语句。
4+
aliases: ['/zh/tidb/dev/br-log-statement/']
5+
---
6+
7+
# TiDB 日志备份与 PITR
8+
9+
> **警告：**
10+
>
11+
> TiDB 日志备份与 PITR SQL 语句支持在 v7.1.0 是实验特性，其语法或者行为表现在 GA 前可能会发生变化。
12+
13+
本文介绍 TiDB 日志备份和 PITR (Point-in-time recovery) SQL 语句。
14+
15+
TiDB 日志备份与 PITR SQL 语句的大部分功能功能以及使用的参数的含义，和 BR 工具命令行基本是一致的，不同的是 SQL 语句备份恢复过程是由 TiDB 本身驱动，而非单独的 BR 工具。BR 工具的优势和警告也适用。如果你想了解如何进行日志备份与 PITR，可以参考以下教程：
16+
17+
- [ TiDB 日志备份与 PITR 命令行手册](/br/br-pitr-manual.md)
18+
- [TiDB 日志备份与 PITR 使用指南](/br/br-pitr-guide.md)
19+
- [TiDB 集群备份与恢复实践示例](/br/backup-and-restore-use-cases.md)
20+
对于命令行已经存在功能，本文档重点是描述语法图和参数列表，对于 SQL 语句特有的功能会在本文档中做详细描述。
21+
22+
## 日志备份语句
23+
24+
执行日志备份语句需要 `BACKUP_ADMIN` 或 `SUPER` 权限。此外，执行备份的 TiDB 节点和集群中的所有 TiKV 节点都必须有对目标存储的读或写权限。
25+
26+
```sql
27+
BACKUP LOGS TO --start a log backup task
28+
SHOW BACKUP LOGS STATUS --get status for the log backup task\
29+
PAUSE BACKUP LOGS --pause a log backup task
30+
RESUME BACKUP LOGS --resume a log backup task
31+
STOP BACKUP LOGS --stop a log backup task
32+
SHOW BACKUP LOGS METADATA FROM --get the metadata of log dir
33+
PURGE BACKUP JOBS FROM --purge the log data until sometime
34+
```
35+
36+
### 启动日志备份
37+
38+
等价于执行 `br log start` 命令，你可以在备份集群启动一个日志备份任务。该任务在 TiDB 集群持续地运行，及时地将 KV 变更日志保存到备份存储中。
39+
40+
#### 语法图
41+
42+
```ebnf+diagram
43+
StreamStartStmt ::=
44+
"BACKUP" "LOGS" "TO" stringLit StreamStartOption*
45+
46+
StreamStartOption ::=
47+
"START_TS" '='? StartTSO
48+
49+
StartTSO ::=
50+
LengthNum | stringLit
51+
```
52+
53+
#### 示例
54+
55+
{{< copyable "sql" >}}
56+
57+
```sql
58+
BACKUP LOGS TO 'local:///mnt/backup/2020/07/26';
59+
BACKUP LOGS TO 'local:///mnt/backup/2022/07/26' START_TS = '2022-07-26 21:20:00+0800';
60+
```
61+
62+
### 查询日志备份任务
63+
64+
等价于执行 `br log status` 命令，查询日志备份任务状态。
65+
66+
#### 语法图
67+
68+
```ebnf+diagram
69+
StreamStatusStmt ::=
70+
"SHOW" "BACKUP" "LOGS" "STATUS"
71+
```
72+
73+
#### 示例
74+
75+
{{< copyable "sql" >}}
76+
77+
```sql
78+
SHOW BACKUP LOGS STATUS;
79+
```
80+
81+
### 暂停日志备份任务
82+
83+
等价于执行 `br log pause` 命令，暂停正在运行的日志备份任务。
84+
85+
#### 语法图
86+
87+
```ebnf+diagram
88+
StreamPauseStmt ::=
89+
"PAUSE" "BACKUP" "LOGS" StreamPauseOption*
90+
91+
StreamPauseOption ::=
92+
"GC_TTL" '='? GCTTLTSO
93+
94+
GCTTLTSO ::=
95+
LengthNum | stringLit
96+
```
97+
98+
#### 示例
99+
100+
{{< copyable "sql" >}}
101+
102+
```sql
103+
PAUSE BACKUP LOGS;
104+
PAUSE BACKUP LOGS GC_TTL = '2022-08-26 21:20:00+0800';
105+
```
106+
107+
### 恢复日志备份任务
108+
109+
等价于执行 `br log resume` 命令，恢复被暂停的日志备份任务。
110+
111+
#### 语法图
112+
113+
```ebnf+diagram
114+
StreamResumeStmt ::=
115+
"Resume" "BACKUP" "LOGS"
116+
```
117+
118+
#### 示例
119+
120+
{{< copyable "sql" >}}
121+
122+
```sql
123+
RESUME BACKUP LOGS;
124+
```
125+
126+
### 停止日志备份任务
127+
128+
等价于执行 `br log stop` 命令，停止日志备份任务。
129+
130+
#### 语法图
131+
132+
```ebnf+diagram
133+
StreamStopStmt ::=
134+
"Stop" "BACKUP" "LOGS"
135+
```
136+
137+
#### 示例
138+
139+
{{< copyable "sql" >}}
140+
141+
```sql
142+
STOP BACKUP LOGS;
143+
```
144+
145+
### 查看备份数据元信息
146+
147+
等价于执行 `br log metadata` 命令，查看备份存储中保存的日志备份的元信息，例如最早和最近的可恢复时间点。
148+
149+
#### 语法图
150+
151+
```ebnf+diagram
152+
StreamMetaDataStmt ::=
153+
"SHOW" "BACKUP" "LOGS" "METADATA" "FROM" stringLit
154+
```
155+
156+
#### 示例
157+
158+
{{< copyable "sql" >}}
159+
160+
```sql
161+
SHOW BACKUP LOGS METADATA FROM 's3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"';
162+
```
163+
164+
### 清理日志备份数据
165+
166+
等价于执行 `br log truncate` 命令，从备份存储中删除过期或不再需要的备份日志数据。
167+
168+
#### 语法图
169+
170+
```ebnf+diagram
171+
StreamMetaPurgeStmt ::=
172+
"PURGE" "BACKUP" "LOGS" "METADATA" "FROM" stringLit StreamPurgeOption*
173+
174+
StreamPurgeOption ::=
175+
"UNTIL_TS" '='? UNTILTSO
176+
177+
UNTILTSO ::=
178+
LengthNum | stringLit
179+
```
180+
181+
#### 示例
182+
183+
{{< copyable "sql" >}}
184+
185+
```sql
186+
PURGE BACKUP LOGS METADATA FROM 's3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"';
187+
PURGE BACKUP LOGS METADATA FROM 's3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"' UNTIL_TS = '2022-08-26 21:20:00+0800' ;
188+
```
189+
190+
## 恢复到指定时间点 PITR
191+
192+
执行 PITR 语句需要 `RESTORE_ADMIN` 或 `SUPER` 权限。此外，执行恢复的 TiDB 节点和集群中的所有 TiKV 节点都必须有对目标存储的读或写权限。
193+
194+
```sql
195+
RESTORE POINT FROM --restore cluster to a point
196+
```
197+
198+
### 恢复到指定时间点
199+
200+
等价于执行 `br restore point` 命令，在新集群上进行 PITR，或者只恢复日志备份数据。
201+
202+
#### 语法图
203+
204+
```ebnf+diagram
205+
StreamRestorePITStmt ::=
206+
"RESTORE" "POINT" "FROM" stringLit StreamRestorePITOption*
207+
208+
StreamRestorePITOption ::=
209+
"START_TS" '='? StartTSO
210+
| "FULL_BACKUP_STORAGE" '='? stringLit
211+
| "START_TS" '='? StartTSO
212+
| "STORED_TS" '='? StoredTSO
213+
214+
StartTSO ::=
215+
LengthNum | stringLit
216+
217+
StoredTSO ::=
218+
LengthNum | stringLit
219+
```
220+
221+
#### 示例
222+
223+
{{< copyable "sql" >}}
224+
225+
```sql
226+
RESTORE POINT FROM 's3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"' FULL_BACKUP_STORAGE = 's3://backup-101/snapshot-202205120000?access-key=${access-key}&secret-access-key=${secret-access-key}"';
227+
228+
```
229+
> **注意：**
230+
>
231+
> - 不支持重复恢复某段时间区间的日志，如多次重复恢复 `[t1=10, t2=20)` 区间的日志数据，可能会造成恢复后的数据不正确。
232+
> - 多次恢复不同时间区间的日志时，需保证恢复日志的连续性。如先后恢复 `[t1, t2)`、`[t2, t3)` 和 `[t3, t4)` 三个区间的日志可以保证正确性，而在恢复 `[t1, t2)` 后跳过 `[t2, t3)` 直接恢复 `[t3, t4)` 的区间可能导致恢复之后的数据不正确。
233+
234+
235+
## MySQL 兼容性
236+
237+
该语句是 TiDB 对 MySQL 语法的扩展。
238+
239+
## 另请参阅
240+
241+
* [BACKUP](/sql-statements/sql-statement-backup.md)
242+
* [SHOW BACKUPS](/sql-statements/sql-statement-show-backups.md)
243+
* [SHOW RESTORES](/sql-statements/sql-statement-show-backups.md)
244+
* [RESTORE](/sql-statements/sql-statement-restore.md)
245+
* [BR_JOB_ADMIN](/sql-statements/sql-statement-br-job-admin.md)
246+
* [SHOW_BACKUP_META](/sql-statements/show-backp-meta.md)

‎sql-statements/sql-statement-restore.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,3 +161,6 @@ RESTORE DATABASE * FROM 's3://example-bucket/inc-backup-2';
161161

162162
* [BACKUP](/sql-statements/sql-statement-backup.md)
163163
* [SHOW RESTORES](/sql-statements/sql-statement-show-backups.md)
164+
* [PITR](/sql-statements/sql-statement-pitr.md)
165+
* [BR_JOB_ADMIN](/sql-statements/sql-statement-br-job-admin.md)
166+
* [SHOW_BACKUP_META](/sql-statements/sql-statement-show-backup-meta.md)

0 commit comments

Comments
 (0)