From f5592779cfc26952343a16232757bdf793aea0d2 Mon Sep 17 00:00:00 2001 From: shichun-0415 <89768198+shichun-0415@users.noreply.github.com> Date: Wed, 8 Mar 2023 11:59:12 +0800 Subject: [PATCH] sql: add sql statements and document fields of TABLE_STORAGE_STATS (#12952) --- TOC.md | 2 + .../information-schema-cluster-info.md | 4 +- .../information-schema-table-storage-stats.md | 11 +++ sql-statements/sql-statement-admin-cleanup.md | 74 +++++++++++++++++++ sql-statements/sql-statement-admin-recover.md | 72 ++++++++++++++++++ 5 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 sql-statements/sql-statement-admin-cleanup.md create mode 100644 sql-statements/sql-statement-admin-recover.md diff --git a/TOC.md b/TOC.md index 90bd3bc5a1fe..c456fcfc3bf1 100644 --- a/TOC.md +++ b/TOC.md @@ -674,6 +674,8 @@ - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) + - [`ADMIN CLEANUP`](/sql-statements/sql-statement-admin-cleanup.md) + - [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md) - [`ADMIN SHOW DDL [JOBS|QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) - [`ADMIN SHOW TELEMETRY`](/sql-statements/sql-statement-admin-show-telemetry.md) - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) diff --git a/information-schema/information-schema-cluster-info.md b/information-schema/information-schema-cluster-info.md index ac573a539c2c..74d5b0983d6c 100644 --- a/information-schema/information-schema-cluster-info.md +++ b/information-schema/information-schema-cluster-info.md @@ -26,8 +26,9 @@ desc cluster_info; | GIT_HASH | varchar(64) | YES | | NULL | | | START_TIME | varchar(32) | YES | | NULL | | | UPTIME | varchar(32) | YES | | NULL | | +| SERVER_ID | bigint(21) | YES | | NULL | | +----------------+-------------+------+------+---------+-------+ -7 rows in set (0.00 sec) +8 rows in set (0.01 sec) ``` 字段解释： @@ -39,6 +40,7 @@ desc cluster_info; * `GIT_HASH`：编译节点版本时的 Git Commit Hash，用于识别两个节点是否是绝对一致的版本。 * `START_TIME`：对应节点的启动时间。 * `UPTIME`：对应节点已经运行的时间。 +* `SERVER_ID`：对应节点的服务器 ID。 {{< copyable "sql" >}} diff --git a/information-schema/information-schema-table-storage-stats.md b/information-schema/information-schema-table-storage-stats.md index 4f65ff94356d..28f263a2a199 100644 --- a/information-schema/information-schema-table-storage-stats.md +++ b/information-schema/information-schema-table-storage-stats.md @@ -50,3 +50,14 @@ EMPTY_REGION_COUNT: 1 TABLE_KEYS: 0 1 row in set (0.00 sec) ``` + +`TABLE_STORAGE_STATS` 表各列字段含义如下： + +* `TABLE_SCHEMA`：表所在 schema 名字 +* `TABLE_NAME`：表名 +* `TABLE_ID`：表 ID +* `PEER_COUNT`：副本个数 +* `REGION_COUNT`：表所在的 Region 个数 +* `EMPTY_REGION_COUNT`：没有该表数据的 Region 个数 +* `TABLE_SIZE`：数据量大小，单位 MiB +* `TABLE_KEYS`：表记录个数 diff --git a/sql-statements/sql-statement-admin-cleanup.md b/sql-statements/sql-statement-admin-cleanup.md new file mode 100644 index 000000000000..c9a3d7a6645f --- /dev/null +++ b/sql-statements/sql-statement-admin-cleanup.md @@ -0,0 +1,74 @@ +--- +title: ADMIN CLEANUP INDEX +summary: TiDB 数据库中 ADMIN CLEANUP 的使用概况。 +--- + +# ADMIN CLEANUP INDEX + +`ADMIN CLEANUP INDEX` 语句用于在表发生行数据和索引的一致性故障时，删除表中多余的索引，使表的行数据和索引恢复一致状态。注意，该语法尚不支持[外键约束](/foreign-key.md)。 + +## 语法图 + +```ebnf+diagram +AdminCleanupStmt ::= + 'ADMIN' 'CLEANUP' ( 'INDEX' TableName IndexName | 'TABLE' 'LOCK' TableNameList ) + +TableNameList ::= + TableName ( ',' TableName )* +``` + +## 示例 + +假设由于一些原因（例如灾难恢复场景，集群中丢失了部分行数据），数据库中的 `tbl` 表出现数据和索引不一致现象： + +```sql +SELECT * FROM tbl; +ERROR 1105 (HY000): inconsistent index idx handle count 3 isn't equal to value count 2 + +ADMIN CHECK INDEX tbl idx ; +ERROR 1105 (HY000): handle &kv.CommonHandle{encoded:[]uint8{0x1, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xf8}, colEndOffsets:[]uint16{0xa}}, index:types.Datum{k:0x5, decimal:0x0, length:0x0, i:0, collation:"utf8mb4_bin", b:[]uint8{0x0}, x:interface {}(nil)} != record: +``` + +从 `SELECT` 查询的错误信息可以看到，`tbl` 表中包含 2 条行数据和 3 条索引数据，这意味着行数据与索引数据出现了不一致故障，同时至少有 1 条索引处于悬空状态。此时可以使用 `ADMIN CLEANUP INDEX` 语句删除悬空的索引： + +```sql +ADMIN CLEANUP INDEX tbl idx; +``` + +执行结果示例如下： + +```sql +ADMIN CLEANUP INDEX tbl idx; ++---------------+ +| REMOVED_COUNT | ++---------------+ +| 1 | ++---------------+ +``` + +此时，可以重新使用 `ADMIN CHECK INDEX` 语句检查数据索引的一致性，验证数据是否恢复到正常状态： + +```sql +ADMIN CHECK INDEX tbl idx; +Query OK, 0 rows affected (0.01 sec) +``` + +> **注意：** +> +> 当由于副本丢失导致数据索引出现不一致时： +> +> - 通常行数据与索引数据都有丢失，此时需要同时使用 `ADMIN CLEANUP INDEX` 与 [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md) 语句保证行数据与索引数据的一致性。 +> - `ADMIN CLEANUP INDEX` 总是单并发执行。在表数据量大时，建议通过重建索引的方式进行索引数据的恢复。 +> - `ADMIN CLEANUP INDEX` 在执行期间，不会为对应的表或索引记录加锁，TiDB 允许其他的会话同时对表记录进行更新或修改。然而，在此情况下，`ADMIN CLEANUP INDEX` 可能无法正确处理所有表记录。因此，在执行 `ADMIN CLEANUP INDEX` 时，请避免同时修改表数据。 +> - 若你使用 TiDB 企业版，此时建议[提交工单](https://support.pingcap.cn/)联系 PingCAP 支持工程师进行处理。 +> +> `ADMIN CLEANUP INDEX` 命令不具有原子性：若该命令在执行期间中断，建议重新执行直到成功。 + +## MySQL 兼容性 + +`ADMIN CLEANUP INDEX` 语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +* [`ADMIN CHECK TABLE/INDEX`](/sql-statements/sql-statement-admin-check-table-index.md) +* [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md) diff --git a/sql-statements/sql-statement-admin-recover.md b/sql-statements/sql-statement-admin-recover.md new file mode 100644 index 000000000000..e420d2973f8d --- /dev/null +++ b/sql-statements/sql-statement-admin-recover.md @@ -0,0 +1,72 @@ +--- +title: ADMIN RECOVER INDEX +summary: TiDB 数据库中 ADMIN RECOVER INDEX 的使用概况。 +--- + +# ADMIN RECOVER INDEX + +`ADMIN RECOVER INDEX` 语句用于在表发生行数据和索引的一致性故障时，根据表中多余的索引，使表的行数据和索引重新恢复到一致状态。注意，该语法尚不支持[外键约束](/foreign-key.md)。 + +## 语法图 + +```ebnf+diagram +AdminCleanupStmt ::= + 'ADMIN' 'RECOVER' 'INDEX' TableName IndexName +``` + +## 示例 + +假设由于一些原因（例如灾难恢复场景，集群中丢失了部分索引数据），数据库中的 `tbl` 表出现行数据和索引不一致现象： + +```sql +SELECT * FROM tbl; +ERROR 1105 (HY000): inconsistent index idx handle count 2 isn't equal to value count 3 + +ADMIN CHECK INDEX tbl idx ; +ERROR 1105 (HY000): handle &kv.CommonHandle{encoded:[]uint8{0x1, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xf8}, colEndOffsets:[]uint16{0xa}}, index:types.Datum{k:0x5, decimal:0x0, length:0x0, i:0, collation:"utf8mb4_bin", b:[]uint8{0x0}, x:interface {}(nil)} != record: +``` + +从 `SELECT` 查询的错误信息可以看到，`tbl` 表中包含 3 条行数据和 2 条索引数据，这意味着行数据与索引数据出现了不一致故障，同时至少有 1 条行数据缺少了对应的索引。此时可以使用 `ADMIN RECOVER INDEX` 语句补充缺少的索引： + +```sql +ADMIN RECOVER INDEX tbl idx; +``` + +执行结果示例如下： + +```sql +ADMIN RECOVER INDEX tbl idx; ++-------------+------------+ +| ADDED_COUNT | SCAN_COUNT | ++-------------+------------+ +| 1 | 3 | ++-------------+------------+ +1 row in set (0.00 sec) +``` + +此时，可以重新使用 `ADMIN CHECK INDEX` 语句对数据索引的一致性进行检查，验证数据恢复到正常状态： + +```sql +ADMIN CHECK INDEX tbl idx; +Query OK, 0 rows affected (0.01 sec) +``` + +> **注意：** +> +> 当由于副本丢失导致数据索引出现不一致时： +> +> - 通常行数据与索引数据都有丢失，此时需要同时使用 [`ADMIN CLEANUP INDEX`](/sql-statements/sql-statement-admin-cleanup.md) 与 `ADMIN RECOVER INDEX` 语句保证行数据与索引数据的一致性。 +> - `ADMIN RECOVER INDEX` 总是单并发执行。在表数据量大时，建议通过重建索引的方式进行索引数据的恢复。 +> - `ADMIN RECOVER INDEX` 在执行期间，不会为对应的表或索引记录加锁，这意味着 TiDB 允许同时有其他的会话对表记录进行更新或修改。然而，在此情况下 `ADMIN RECOVER INDEX` 可能无法正确处理所有数据。因此，在执行 `ADMIN RECOVER INDEX` 时，请避免同时修改表数据。 +> - 若你使用 TiDB 企业版，此时建议[提交工单](https://support.pingcap.cn/)联系 PingCAP 支持工程师进行处理。 +> +> `ADMIN RECOVER INDEX` 命令不具有原子性：若该命令在执行期间中断，建议重新执行直到成功。 + +## MySQL 兼容性 + +`ADMIN RECOVER INDEX` 语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +* [`ADMIN CHECK TABLE/INDEX`](/sql-statements/sql-statement-admin-check-table-index.md) +* [`ADMIN CLEANUP INDEX`](/sql-statements/sql-statement-admin-cleanup.md)