br, sql-statements: document BACKUP, RESTORE and SHOW [BACKUPS|RESTORES] (#3925)

TOC.md

@@ -63,6 +63,7 @@
     + 使用 BR 工具（推荐）
       + [使用 BR 进行备份与恢复](/br/backup-and-restore-tool.md)
       + [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md)
+      + [BR 存储](/br/backup-and-restore-storages.md)
     + [使用 Dumpling 和 TiDB Lightning 进行备份与恢复（推荐）](/backup-and-restore-using-dumpling-lightning.md)
     + [使用 Mydumper 和 TiDB Lightning 进行备份与恢复](/backup-and-restore-using-mydumper-lightning.md)
   + [读取历史数据](/read-historical-data.md)
@@ -243,6 +244,7 @@
       - [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md)
       - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md)
       - [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md)
+      - [`BACKUP`](/sql-statements/sql-statement-backup.md)
       - [`BEGIN`](/sql-statements/sql-statement-begin.md)
       - [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md)
       - [`CHANGE DRAINER`](/sql-statements/sql-statement-change-drainer.md)
@@ -288,6 +290,7 @@
       - [`RENAME INDEX`](/sql-statements/sql-statement-rename-index.md)
       - [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md)
       - [`REPLACE`](/sql-statements/sql-statement-replace.md)
+      - [`RESTORE`](/sql-statements/sql-statement-restore.md)
       - [`REVOKE <privileges>`](/sql-statements/sql-statement-revoke-privileges.md)
       - [`ROLLBACK`](/sql-statements/sql-statement-rollback.md)
       - [`SELECT`](/sql-statements/sql-statement-select.md)
@@ -296,6 +299,7 @@
       - [`SET ROLE`](/sql-statements/sql-statement-set-role.md)
       - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md)
       - [`SET [GLOBAL|SESSION] <variable>`](/sql-statements/sql-statement-set-variable.md)
+      - [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md)
       - [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md)
       - [`SHOW BINDINGS`](/sql-statements/sql-statement-show-bindings.md)
       - [`SHOW BUILTINS`](/sql-statements/sql-statement-show-builtins.md)

br/backup-and-restore-storages.md

@@ -0,0 +1,81 @@
+---
+title: BR 存储
+summary: 了解 BR 中所用存储服务的 URL 格式。
+---
+
+# BR 存储
+
+Backup & Restore (BR) 支持在本地文件系统、Amazon S3 和 Google Cloud Storage (GCS) 上读写数据。通过传入 BR 的 `--storage` 参数中的不同 URL scheme，可以区分不同的存储方式。
+
+## Scheme
+
+BR 支持以下存储服务：
+
+| 服务 | Scheme | 示例 |
+|---------|---------|-------------|
+| 本地文件系统（分布在各节点上） | local | `local:///path/to/dest/` |
+| Amazon S3 及其他兼容 S3 的服务 | s3 | `s3://bucket-name/prefix/of/dest/` |
+| GCS | gcs, gs | `gcs://bucket-name/prefix/of/dest/` |
+| 不写入任何存储（仅作为基准测试） | noop | `noop://` |
+
+## 参数
+
+S3 和 GCS 等云存储有时需要额外的连接配置，你可以为这类配置指定参数。例如：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+./br backup full -u 127.0.0.1:2379 -s 's3://bucket-name/prefix?region=us-west-2'
+```
+
+### S3 参数
+
+| 参数 | 描述 |
+|----------:|---------|
+| `access-key` | 访问密钥 |
+| `secret-access-key` | secret 访问密钥 |
+| `region` | Amazon S3 服务区域（默认为 `us-east-1`） |
+| `use-accelerate-endpoint` | 是否在 Amazon S3 上使用加速端点（默认为 `false`） |
+| `endpoint` | S3 兼容服务自定义端点的 URL（例如 `https://s3.example.com/`）|
+| `force-path-style` | 使用 path-style，而不是 virtual-hosted style（默认为 `false`） |
+| `storage-class` | 上传对象的存储类别（例如 `STANDARD`、`STANDARD_IA`） |
+| `sse` | 用于加密上传的服务器端加密算法（可以设置为空，`AES256` 或 `aws:kms`） |
+| `sse-kms-key-id` | 如果 `sse` 设置为 `aws:kms`，则使用该参数指定 KMS ID |
+| `acl` | 上传对象的 canned ACL（例如，`private`、`authenticated-read`） |
+
+> **注意：**
+>
+> 不建议在存储 URL 中直接传递访问密钥和 secret 访问密钥，因为这些密钥是明文记录的。BR 尝试按照以下顺序从环境中推断这些密钥：
+
+1. `$AWS_ACCESS_KEY_ID` 和 `$AWS_SECRET_ACCESS_KEY` 环境变量。
+2. `$AWS_ACCESS_KEY` 和 `$AWS_SECRET_KEY` 环境变量。
+3. BR 节点上的共享凭证文件，路径由 `$AWS_SHARED_CREDENTIALS_FILE` 环境变量指定。
+4. BR 节点上的共享凭证文件，路径为 `~/.aws/credentials`。
+5. 当前 Amazon EC2 容器的 IAM 角色。
+6. 当前 Amazon ECS 任务的 IAM 角色。
+
+### GCS 参数
+
+| 参数 | 描述 |
+|----------:|---------|
+| `credentials-file` | TiDB 节点上的凭证 JSON 文件的路径 |
+| `storage-class` | 上传对象的存储类别（例如 `STANDARD`、`COLDLINE`） |
+| `predefined-acl` | 上传对象的预定义 ACL（例如 `private`、`project-private` |
+
+如果没有指定 `credentials-file`，BR 尝试按照以下顺序从环境中推断出凭证：
+
+1. BR 节点上位于 `$GOOGLE_APPLICATION_CREDENTIALS` 环境变量所指定路径的文件内容。
+2. BR 节点上位于 `~/.config/gcloud/application_default_credentials.json` 的文件内容。
+3. 在 GCE 或 GAE 中运行时，从元数据服务器中获取的凭证。
+
+## 向 TiKV 发送凭证
+
+在默认情况下，使用 S3 和 GCS 存储时，BR 会将凭证发送到每个 TiKV 节点，以减少设置的复杂性。
+
+但是，这个操作不适合云端环境，因为每个节点都有自己的角色和权限。在这种情况下，你需要用 `--send-credentials-to-tikv=false`（或简写为 `-c=0`）来禁止发送凭证：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+./br backup full -c=0 -u pd-service:2379 -s 's3://bucket-name/prefix'
+```

sql-statements/sql-statement-backup.md

@@ -0,0 +1,185 @@
+---
+title: BACKUP
+summary: TiDB 数据库中 BACKUP 的使用概况。
+---
+
+# BACKUP
+
+`BACKUP` 语句用于对 TiDB 集群执行分布式备份操作。
+
+`BACKUP` 语句使用的引擎与 [BR](/br/backup-and-restore-use-cases.md) 相同，但备份过程是由 TiDB 本身驱动，而非单独的 BR 工具。BR 工具的优势和警告也适用于 `BACKUP` 语句。
+
+执行 `BACKUP` 需要 `SUPER` 权限。此外，执行备份的 TiDB 节点和集群中的所有 TiKV 节点都必须有对目标存储的读或写权限。
+
+`BACKUP` 语句开始执行后将会加锁，直到整个备份任务完成、失败或取消。因此，执行 `BACKUP` 时需要准备一个持久的连接。如需取消任务，可执行 [`KILL TIDB QUERY`](/sql-statements/sql-statement-kill.md) 语句。
+
+一次只能执行一个 `BACKUP` 和 [`RESTORE`](/sql-statements/sql-statement-restore.md) 任务。如果 TiDB server 上已经在执行一个 `BACKUP` 或 `RESTORE` 语句，新的 `BACKUP` 将等待前面所有的任务完成后再执行。
+
+## 语法图
+
+**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)
+
+## 示例
+
+### 备份数据库
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP DATABASE `test` TO 'local:///mnt/backup/2020/04/';
+```
+
+```sql
++------------------------------+-----------+-----------------+---------------------+---------------------+
+| Destination                  | Size      | BackupTS        | Queue Time          | Execution Time      |
++------------------------------+-----------+-----------------+---------------------+---------------------+
+| local:///mnt/backup/2020/04/ | 248665063 | 416099531454472 | 2020-04-12 23:09:48 | 2020-04-12 23:09:48 |
++------------------------------+-----------+-----------------+---------------------+---------------------+
+1 row in set (58.453 sec)
+```
+
+上述示例中，`test` 数据库被备份到本地，数据以 SST 文件的形式存储在分布于所有 TiDB 和 TiKV 节点的 `/mnt/backup/2020/04/` 目录中。
+
+输出结果的第一行描述如下：
+
+| 列名 | 描述 |
+| :-------- | :--------- |
+| `Destination` | 目标存储的 URL |
+| `Size` |  备份文件的总大小，单位为字节 |
+| `BackupTS` | 创建备份时的快照 TSO（用于[增量备份](#增量备份)） |
+| `Queue Time` | `BACKUP` 任务开始排队的时间戳（当前时区） |
+| `Execution Time` | `BACKUP` 任务开始执行的时间戳（当前时区） |
+
+### 备份表
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP TABLE `test`.`sbtest01` TO 'local:///mnt/backup/sbtest01/';
+```
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP TABLE sbtest02, sbtest03, sbtest04 TO 'local:///mnt/backup/sbtest/';
+```
+
+### 备份集群
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP DATABASE * TO 'local:///mnt/backup/full/';
+```
+
+注意，备份中不包含系统表 (`mysql.*`、`INFORMATION_SCHEMA.*`、`PERFORMANCE_SCHEMA.*` 等)。
+
+### 远端存储
+
+BR 支持备份数据到 Amazon S3 或 Google Cloud Storage (GCS)：
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP DATABASE `test` TO 's3://example-bucket-2020/backup-05/?region=us-west-2';
+```
+
+有关详细的 URL 语法，见 [BR 存储](/br/backup-and-restore-storages.md)。
+
+当运行在云环境中时，不能分发凭证，可设置 `SEND_CREDENTIALS_TO_TIKV` 选项为 `FALSE`：
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP DATABASE `test` TO 's3://example-bucket-2020/backup-05/?region=us-west-2'
+    SEND_CREDENTIALS_TO_TIKV = FALSE;
+```
+
+### 性能调优
+
+如果你需要减少网络带宽占用，可以通过 `RATE_LIMIT` 来限制每个 TiKV 节点的平均上传速度。
+
+默认情况下，每个 TiKV 节点上运行 4 个备份线程。可以通过 `CONCURRENCY` 选项来调整这个值。
+
+在备份完成之前，`BACKUP` 将对集群上的数据进行校验，以验证数据的正确性。如果你确信无需进行校验，可以通过 `CHECKSUM` 选项禁用这一步骤。
+
+{{< copyable "sql" >}}
+
+```sql
+BACKUP DATABASE `test` TO 's3://example-bucket-2020/backup-06/'
+    RATE_LIMIT = 120 MB/SECOND
+    CONCURRENCY = 8
+    CHECKSUM = FALSE;
+```
+
+### 快照
+
+可以指定一个时间戳、TSO 或相对时间，来备份历史数据。
+
+{{< copyable "sql" >}}
+
+```sql
+-- 相对时间
+BACKUP DATABASE `test` TO 'local:///mnt/backup/hist01'
+    SNAPSHOT = 36 HOUR AGO;
+-- 时间戳（当前时区）
+BACKUP DATABASE `test` TO 'local:///mnt/backup/hist02'
+    SNAPSHOT = '2020-04-01 12:00:00';
+-- TSO
+BACKUP DATABASE `test` TO 'local:///mnt/backup/hist03'
+    SNAPSHOT = 415685305958400;
+```
+
+对于相对时间，支持以下时间单位：
+
+* MICROSECOND（微秒）
+* SECOND（秒）
+* MINUTE（分钟）
+* HOUR（小时）
+* DAY（天）
+* WEEK（周）
+
+注意，相对时间的单位遵循 SQL 标准，永远使用单数。
+
+### 增量备份
+
+提供 `LAST_BACKUP` 选项，只备份从上一次备份到当前快照之间的增量数据。
+
+{{< copyable "sql" >}}
+
+```sql
+-- 时间戳（当前时区）
+BACKUP DATABASE `test` TO 'local:///mnt/backup/hist02'
+    LAST_BACKUP = '2020-04-01 12:00:00';
+
+-- TSO
+BACKUP DATABASE `test` TO 'local:///mnt/backup/hist03'
+    LAST_BACKUP = 415685305958400;
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+* [RESTORE](/sql-statements/sql-statement-restore.md)
+* [SHOW BACKUPS](/sql-statements/sql-statement-show-backups.md)