Skip to content

Commit d7240cd

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

File tree

6 files changed

+399
-0
lines changed

6 files changed

+399
-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: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
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+
```sql
8+
SHOW BR JOB --show information of a br task
9+
SHOW BR JOB QUERY --show the query statement of a br task
10+
CANCEL BR JOB --cancel a br task
11+
```
12+
13+
### 显示 br 作业信息
14+
15+
按照 task id 展示一个 br 作业的信息
16+
17+
#### 语法图
18+
19+
```ebnf+diagram
20+
StreamShowJobStmt ::=
21+
"SHOW" "BR" "JOB" Int64Num
22+
```
23+
24+
#### 示例
25+
26+
{{< copyable "sql" >}}
27+
28+
```sql
29+
SHOW BR JOB 13456;
30+
```
31+
32+
### 显示 br 作业运行的 SQL 语句
33+
34+
按照 task id 展示一个 br 作业运行的 SQL 语句
35+
36+
#### 语法图
37+
38+
```ebnf+diagram
39+
StreamShowQueryStmt ::=
40+
"SHOW" "BR" "JOB" "QUERY" Int64Num
41+
```
42+
43+
#### 示例
44+
45+
{{< copyable "sql" >}}
46+
47+
```sql
48+
SHOW BR JOB QUERY 13456;
49+
```
50+
51+
### 取消一个 br 作业
52+
53+
按照 task id 取消一个 br 作业的运行
54+
55+
#### 语法图
56+
57+
```ebnf+diagram
58+
StreamCancelJobStmt ::=
59+
"CANCEL" "BR" "JOB" Int64Num
60+
```
61+
62+
#### 示例
63+
64+
{{< copyable "sql" >}}
65+
66+
```sql
67+
CANCEL BR JOB 13456;
68+
```
69+
70+
## MySQL 兼容性
71+
72+
该语句是 TiDB 对 MySQL 语法的扩展。
73+
74+
## 另请参阅
75+
76+
* [BACKUP](/sql-statements/sql-statement-backup.md)
77+
* [SHOW BACKUPS](/sql-statements/sql-statement-show-backups.md)
78+
* [SHOW RESTORES](/sql-statements/sql-statement-show-backups.md)
79+
* [RESTORE](/sql-statements/sql-statement-restore.md)
80+
* [PITR](/sql-statements/sql-statement-pitr.md)
81+
* [SHOW_BACKUP_META](/sql-statements/show-backp-meta.md)

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

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