Skip to content

sql-statements: use EBNF to render syntax diagrams for BACKUP and RESTORE #4342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 7, 2020
Merged

sql-statements: use EBNF to render syntax diagrams for BACKUP and RESTORE #4342

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ea8d98
sql-statements: use ENBF to render syntax diagrams for BACKUP and RES…
kennytm Dec 4, 2020
8733440
Merge branch 'master' into use-ebnf-diagram-for-backup-and-restore
TomShawn Dec 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed media/sqlgram/BRIETables.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/BackupOption.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/BackupStmt.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/BackupTSO.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/Boolean.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/RestoreOption.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/RestoreStmt.png
View file
Open in desktop
Binary file not shown.
Binary file removed media/sqlgram/ShowBRIEStmt.png
View file
Open in desktop
Binary file not shown.
41 changes: 22 additions & 19 deletions sql-statements/sql-statement-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,25 +20,28 @@ Only one `BACKUP` and [`RESTORE`](/sql-statements/sql-statement-restore.md) task

## Synopsis

**BackupStmt:**

![BackupStmt](/media/sqlgram/BackupStmt.png)

**BRIETables:**

![BRIETables](/media/sqlgram/BRIETables.png)

**BackupOption:**

![BackupOption](/media/sqlgram/BackupOption.png)

**Boolean:**

![Boolean](/media/sqlgram/Boolean.png)

**BackupTSO:**

![BackupTSO](/media/sqlgram/BackupTSO.png)
```ebnf+diagram
BackupStmt ::=
"BACKUP" BRIETables "TO" stringLit BackupOption*

BRIETables ::=
"DATABASE" ( '*' | DBName (',' DBName)* )
| "TABLE" TableNameList

BackupOption ::=
"RATE_LIMIT" '='? LengthNum "MB" '/' "SECOND"
| "CONCURRENCY" '='? LengthNum
| "CHECKSUM" '='? Boolean
| "SEND_CREDENTIALS_TO_TIKV" '='? Boolean
| "LAST_BACKUP" '='? BackupTSO
| "SNAPSHOT" '='? ( BackupTSO | LengthNum TimestampUnit "AGO" )

Boolean ::=
NUM | "TRUE" | "FALSE"

BackupTSO ::=
LengthNum | stringLit
```

## Examples

Expand Down
30 changes: 16 additions & 14 deletions sql-statements/sql-statement-restore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,33 @@ The `RESTORE` statement uses the same engine as the [BR tool](/br/backup-and-res
* When a full restore is being performed, the tables being restored should not already exist, because existing data might be overridden and causes inconsistency between the data and indices.
* When an incremental restore is being performed, the tables should be at the exact same state as the `LAST_BACKUP` timestamp when the backup is created.

Running `RESTORE` requires `SUPER` privilege. Additionally, both the TiDB node executing the backup and all TiKV nodes in the cluster must have read permission from the destination.
Running `RESTORE` requires `SUPER` privilege. Additionally, both the TiDB node executing the restore and all TiKV nodes in the cluster must have read permission from the destination.

The `RESTORE` statement is blocking, and will finish only after the entire backup task is finished, failed, or canceled. A long-lasting connection should be prepared for running `RESTORE`. The task can be canceled using the [`KILL TIDB QUERY`](/sql-statements/sql-statement-kill.md) statement.
The `RESTORE` statement is blocking, and will finish only after the entire restore task is finished, failed, or canceled. A long-lasting connection should be prepared for running `RESTORE`. The task can be canceled using the [`KILL TIDB QUERY`](/sql-statements/sql-statement-kill.md) statement.

Only one `BACKUP` and `RESTORE` task can be executed at a time. If a `BACKUP` or `RESTORE` task is already running on the same TiDB server, the new `RESTORE` execution will wait until all previous tasks are done.

`RESTORE` can only be used with "tikv" storage engine. Using `RESTORE` with the "mocktikv" engine will fail.

## Synopsis

**RestoreStmt:**
```ebnf+diagram
RestoreStmt ::=
"RESTORE" BRIETables "FROM" stringLit RestoreOption*

![RestoreStmt](/media/sqlgram/RestoreStmt.png)
BRIETables ::=
"DATABASE" ( '*' | DBName (',' DBName)* )
| "TABLE" TableNameList

**BRIETables:**
RestoreOption ::=
"RATE_LIMIT" '='? LengthNum "MB" '/' "SECOND"
| "CONCURRENCY" '='? LengthNum
| "CHECKSUM" '='? Boolean
| "SEND_CREDENTIALS_TO_TIKV" '='? Boolean

![BRIETables](/media/sqlgram/BRIETables.png)

**RestoreOption:**

![RestoreOption](/media/sqlgram/RestoreOption.png)

**Boolean:**

![Boolean](/media/sqlgram/Boolean.png)
Boolean ::=
NUM | "TRUE" | "FALSE"
```

## Examples

Expand Down
13 changes: 7 additions & 6 deletions sql-statements/sql-statement-show-backups.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ Use `SHOW BACKUPS` to query `BACKUP` tasks and use `SHOW RESTORES` to query `RES

## Synopsis

**ShowBRIEStmt:**
```ebnf+diagram
ShowBRIEStmt ::=
"SHOW" ("BACKUPS" | "RESTORES") ShowLikeOrWhere?

![ShowBRIEStmt](/media/sqlgram/ShowBRIEStmt.png)

**ShowLikeOrWhereOpt:**

![ShowLikeOrWhereOpt](/media/sqlgram/ShowLikeOrWhereOpt.png)
ShowLikeOrWhere ::=
"LIKE" SimpleExpr
| "WHERE" Expression
```

## Examples

Expand Down