From 26bf358fb6bf598a5fff45d333fb4bf69eecca54 Mon Sep 17 00:00:00 2001
From: Ti Chi Robot <ti-community-prow-bot@tidb.io>
Date: Thu, 26 Aug 2021 16:24:05 +0800
Subject: [PATCH] br: add restore to systables (#6004) (#6273)

---
 br/use-br-command-line-tool.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/br/use-br-command-line-tool.md b/br/use-br-command-line-tool.md
index 6921d73670a03..f9f5ed28495a7 100644
--- a/br/use-br-command-line-tool.md
+++ b/br/use-br-command-line-tool.md
@@ -442,6 +442,39 @@ In the above command, `--table` specifies the name of the table to be restored.
 
 Restoring incremental data is similar to [restoring full data using BR](#restore-all-the-backup-data). Note that when restoring incremental data, make sure that all the data backed up before `last backup ts` has been restored to the target cluster.
 
+### Restore tables created in the `mysql` schema (experimental feature)
+
+BR backs up tables created in the `mysql` schema by default.
+
+When you restore data using BR, the tables created in the `mysql` schema are not restored by default. If you need to restore these tables, you can explicitly include them using the [table filter](/table-filter.md#syntax). The following example restores `mysql.usertable` created in `mysql` schema. The command restores `mysql.usertable` along with other data.
+
+{{< copyable "shell-regular" >}}
+
+```shell
+br restore full -f '*.*' -f '!mysql.*' -f 'mysql.usertable' -s $external_storage_url
+```
+
+In the above command, `-f '*.*'` is used to override the default rules and `-f '!mysql.*'` instructs BR not to restore tables in `mysql` unless otherwise stated. `-f 'mysql.usertable'` indicates that `mysql.usertable` is required for restore. For detailed implementation, refer to the [table filter document](/table-filter.md#syntax).
+
+If you only need to restore `mysql.usertable`, use the following command:
+
+{{< copyable "shell-regular" >}}
+
+```shell
+br restore full -f 'mysql.usertable' -s $external_storage_url
+```
+
+> **Warning:**
+>
+> Although you can back up and restore system tables (such as `mysql.tidb`) using the BR tool, some unexpected situations might occur after the restore, including:
+>
+> - the statistical information tables (`mysql.stat_*`) cannot be restored.
+> - the system variable tables (`mysql.tidb`，`mysql.global_variables`) cannot be restored.
+> - the user information tables (such as `mysql.user` and `mysql.columns_priv`) cannot be restored.
+> - GC data cannot be restored.
+> 
+> Restoring system tables might cause more compatibility issues. To avoid unexpected issues, **DO NOT** restore system tables in the production environment.
+
 ### Restore Raw KV (experimental feature)
 
 > **Warning:**