Merge remote-tracking branch 'upstream/master'

hfxsd · Aug 8, 2023 · 6c835ce · 6c835ce
2 parents eb4ca13 + 402f5fc
commit 6c835ce
Show file tree

Hide file tree

Showing 92 changed files with 5,007 additions and 3,698 deletions.
diff --git a/TOC.md b/TOC.md
@@ -21,11 +21,21 @@
     - [使用 TiDB Serverless 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)
     - [使用 TiDB 的增删改查 SQL](/develop/dev-guide-tidb-crud-sql.md)
   - 示例程序
-    - [Golang](/develop/dev-guide-sample-application-golang.md)
-    - [Java (Spring Boot)](/develop/dev-guide-sample-application-spring-boot.md)
-    - [Java](/develop/dev-guide-sample-application-java.md)
-    - [Python (Django)](/develop/dev-guide-sample-application-django.md)
-    - [Python](/develop/dev-guide-sample-application-python.md)
+    - Java
+      - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md)
+      - [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md)
+      - [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md)
+      - [Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md)
+    - Go
+      - [Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md)
+      - [GORM](/develop/dev-guide-sample-application-golang-gorm.md)
+    - Python
+      - [mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md)
+      - [MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md)
+      - [PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md)
+      - [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)
+      - [peewee](/develop/dev-guide-sample-application-python-peewee.md)
+      - [Django](/develop/dev-guide-sample-application-python-django.md)
   - 连接到 TiDB
     - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md)
     - [连接到 TiDB](/develop/dev-guide-connect-to-tidb.md)
@@ -176,6 +186,7 @@
   - [监控框架概述](/tidb-monitoring-framework.md)
   - [监控 API](/tidb-monitoring-api.md)
   - [手动部署监控](/deploy-monitoring-services.md)
+  - [升级监控组件](/upgrade-monitoring-services.md)
   - [将 Grafana 监控数据导出成快照](/exporting-grafana-snapshots.md)
   - [TiDB 集群报警规则与处理方法](/alert-rules.md)
   - [TiFlash 报警规则与处理方法](/tiflash/tiflash-alert-rules.md)
@@ -257,6 +268,7 @@
         - [错误索引的解决方案](/wrong-index-solution.md)
         - [Distinct 优化](/agg-distinct-optimization.md)
         - [代价模型](/cost-model.md)
+        - [Runtime Filter](/runtime-filter.md)
       - [Prepare 语句执行计划缓存](/sql-prepared-plan-cache.md)
       - [非 Prepare 语句执行计划缓存](/sql-non-prepared-plan-cache.md)
     - 控制执行计划
@@ -764,6 +776,7 @@
       - [`LOCK TABLES` 和 `UNLOCK TABLES`](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md)
       - [`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md)
       - [`PREPARE`](/sql-statements/sql-statement-prepare.md)
+      - [`QUERY WATCH`](/sql-statements/sql-statement-query-watch.md)
       - [`RECOVER TABLE`](/sql-statements/sql-statement-recover-table.md)
       - [`RENAME INDEX`](/sql-statements/sql-statement-rename-index.md)
       - [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md)
@@ -921,6 +934,7 @@
         - [`PROCESSLIST`](/information-schema/information-schema-processlist.md)
         - [`REFERENTIAL_CONSTRAINTS`](/information-schema/information-schema-referential-constraints.md)
         - [`RESOURCE_GROUPS`](/information-schema/information-schema-resource-groups.md)
+        - [`RUNAWAY_WATCHES`](/information-schema/information-schema-runaway-watches.md)
         - [`SCHEMATA`](/information-schema/information-schema-schemata.md)
         - [`SEQUENCES`](/information-schema/information-schema-sequences.md)
         - [`SESSION_VARIABLES`](/information-schema/information-schema-session-variables.md)

diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md
@@ -80,6 +80,8 @@ BACKUP DATABASE * TO 's3://bucket-name/prefix' SEND_CREDENTIALS_TO_TIKV = FALSE;
     - `account-key`：访问密钥
     - `sas-token`：共享访问签名令牌
     - `access-tier`：上传对象的存储类别，例如 `Hot`、`Cool`、`Archive`，默认值为该存储账户的默认访问层。
+    - `encryption-scope`：服务端的[加密范围 (Encryption Scope)](https://learn.microsoft.com/zh-cn/azure/storage/blobs/encryption-scope-manage?tabs=powershell#upload-a-blob-with-an-encryption-scope)
+    - `encryption-key`：服务端使用的[加密密钥 (Encryption Key)](https://learn.microsoft.com/zh-cn/azure/storage/blobs/encryption-customer-provided-keys)，采用的加密算法为 AES256
 
 </div>
 </SimpleTab>
@@ -252,6 +254,10 @@ BACKUP DATABASE * TO 's3://bucket-name/prefix' SEND_CREDENTIALS_TO_TIKV = FALSE;
 
 TiDB 备份恢复功能支持对备份到 Amazon S3 的数据进行 S3 服务端加密 (SSE)。S3 服务端加密也支持使用用户自行创建的 AWS KMS 密钥，详细信息请参考 [BR S3 服务端加密](/encryption-at-rest.md#br-s3-服务端加密)。
 
+### Azure Blob Storage 存储服务端加密备份数据
+
+TiDB 备份恢复功能支持对备份到 Azure Blob Storage 的数据设置 Azure 服务端加密范围 (Encryption Scope) 或提供加密密钥 (Encryption Key)，为同一存储账户的不同备份数据建立安全边界。详细信息请参考 [BR Azure Blob Storage 服务端加密](/encryption-at-rest.md#br-azure-blob-storage-服务端加密)。
+
 ## 存储服务其他功能支持
 
 TiDB 备份恢复功能从 v6.3.0 支持 AWS S3 Object Lock 功能。你可以在 AWS 中开启 [S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) 功能来防止备份数据写入后被修改或者删除。
diff --git a/check-before-deployment.md b/check-before-deployment.md
@@ -125,6 +125,36 @@ sysctl -p
 > - 一起执行 `swapoff -a` 和 `swapon -a` 命令是为了刷新 swap，将 swap 里的数据转储回内存，并清空 swap 里的数据。不可省略 swappiness 设置而只执行 `swapoff -a`；否则，重启后 swap 会再次自动打开，使得操作失效。
 > - 执行 `sysctl -p` 命令是为了在不重启的情况下使配置生效。
 
+## 设置 TiDB 节点的临时空间（推荐）
+
+TiDB 的部分操作需要向服务器写入临时文件，因此需要确保运行 TiDB 的操作系统用户具有足够的权限对目标目录进行读写。如果 TiDB 实例不是以 `root` 权限启动，则需要检查目录权限并进行正确设置。
+
+- TiDB 临时工作区
+
+    哈希表构建、排序等内存消耗较大的操作可能会向磁盘写入临时数据，用来减少内存消耗，提升稳定性。写入的磁盘位置由配置项 [`tmp-storage-path`](/tidb-configuration-file.md#tmp-storage-path) 定义。在默认设置下，确保运行 TiDB 的用户对操作系统临时文件夹（通常为 `/tmp`）有读写权限。
+
+- Fast Online DDL 工作区
+
+    当变量 [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入) 被设置为 `ON`（v6.5.0 及以上版本中默认值为 `ON`）时，会激活 Fast Online DDL，这时部分 DDL 要对临时文件进行读写。临时文件位置由配置 [`temp-dir`](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入) 定义，需要确保运行 TiDB 的用户对操作系统中该目录有读写权限。以默认目录 `/tmp/tidb` 为例：
+
+    > **注意：**
+    >
+    > 如果业务中可能存在针对大对象的 DDL 操作，推荐为 [`temp-dir`](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入) 配置独立文件系统及更大的临时空间。
+
+    ```shell
+    sudo mkdir /tmp/tidb
+    ```
+
+    如果目录 `/tmp/tidb` 已经存在，需确保有写入权限。
+
+    ```shell
+    sudo chmod -R 777 /tmp/tidb
+    ```
+
+    > **注意：**
+    >
+    > 如果目录不存在，TiDB 在启动时会自动创建该目录。如果目录创建失败，或者 TiDB 对该目录没有读写权限，[Fast Online DDL](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入) 在运行时可能产生不可预知的问题。
+
 ## 检测及关闭目标部署机器的防火墙
 
 本段介绍如何关闭目标主机防火墙配置，因为在 TiDB 集群中，需要将节点间的访问端口打通才可以保证读写请求、数据心跳等信息的正常的传输。在普遍线上场景中，数据库到业务服务和数据库节点的网络联通都是在安全域内完成数据交互。如果没有特殊安全的要求，建议将目标节点的防火墙进行关闭。否则建议[按照端口使用规则](/hardware-and-software-requirements.md#网络要求)，将端口信息配置到防火墙服务的白名单中。

diff --git a/choose-index.md b/choose-index.md
@@ -145,6 +145,8 @@ mysql> SHOW WARNINGS;
 
 [多值索引](/sql-statements/sql-statement-create-index.md#多值索引)和普通索引有所不同，TiDB 目前只会使用 [IndexMerge](/explain-index-merge.md) 来访问多值索引。因此要想使用多值索引进行数据访问，请确保`tidb_enable_index_merge` 被设置为 `ON`。
 
+多值索引的使用限制请参考 [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md#特性与限制)。
+
 目前 TiDB 支持将 `json_member_of`、`json_contains` 和 `json_overlaps` 条件自动转换成 IndexMerge 来访问多值索引。既可以依赖优化器根据代价自动选择，也可通过 [`use_index_merge`](/optimizer-hints.md#use_index_merget1_name-idx1_name--idx2_name-) optimizer hint 或 [`use_index`](/optimizer-hints.md#use_indext1_name-idx1_name--idx2_name-) 指定选择多值索引，见下面例子：
 
 ```sql

diff --git a/dashboard/dashboard-faq.md b/dashboard/dashboard-faq.md
@@ -35,20 +35,20 @@ QPS 及 Latency 监控依赖于集群中已正常部署 Prometheus 监控实例
 
 1. 升级 TiUP、TiUP Cluster：
 
-   ```bash
-   tiup update --self
-   tiup update cluster --force
-   ```
+    ```bash
+    tiup update --self
+    tiup update cluster --force
+    ```
 
 2. 升级后，部署包含监控节点的新集群时，应当能正常显示监控。
 
 3. 升级后，对于现有集群，可通过再次启动集群的方法汇报监控地址（将 `CLUSTER_NAME` 替换为实际集群名称）：
 
-   ```bash
-   tiup cluster start CLUSTER_NAME
-   ```
+    ```bash
+    tiup cluster start CLUSTER_NAME
+    ```
 
-   即使集群已经启动，请仍然执行该命令。该命令不会影响集群上正常的业务，但会刷新并上报监控地址，从而能让监控在 TiDB Dashboard 中正常显示。
+    即使集群已经启动，请仍然执行该命令。该命令不会影响集群上正常的业务，但会刷新并上报监控地址，从而能让监控在 TiDB Dashboard 中正常显示。
 
 ### 慢查询页面显示 `invalid connection` 错误
 

diff --git a/dashboard/dashboard-ops-reverse-proxy.md b/dashboard/dashboard-ops-reverse-proxy.md
@@ -48,21 +48,21 @@ http://192.168.0.123:2379/dashboard/
 
 1. 以在 8033 端口反向代理 TiDB Dashboard 为例，在 HAProxy 配置文件中，新增如下配置：
 
-   ```haproxy
-   frontend tidb_dashboard_front
-     bind *:8033
-     use_backend tidb_dashboard_back if { path /dashboard } or { path_beg /dashboard/ }
+    ```haproxy
+    frontend tidb_dashboard_front
+      bind *:8033
+      use_backend tidb_dashboard_back if { path /dashboard } or { path_beg /dashboard/ }
 
-   backend tidb_dashboard_back
-     mode http
-     server tidb_dashboard 192.168.0.123:2379
-   ```
+    backend tidb_dashboard_back
+      mode http
+      server tidb_dashboard 192.168.0.123:2379
+    ```
 
-   其中 `192.168.0.123:2379` 需替换为[第 1 步：获取实际 TiDB Dashboard 地址](#第-1-步获取实际-tidb-dashboard-地址)中取得的 TiDB Dashboard 实际地址中的 IP 及端口部分。
+    其中 `192.168.0.123:2379` 需替换为[第 1 步：获取实际 TiDB Dashboard 地址](#第-1-步获取实际-tidb-dashboard-地址)中取得的 TiDB Dashboard 实际地址中的 IP 及端口部分。
 
-   > **警告：**
-   >
-   > 请务必保留 `use_backend` 指令中的 `if` 部分，确保只有该路径下的服务会被反向代理，否则将引入安全风险。参见[提高 TiDB Dashboard 安全性](/dashboard/dashboard-ops-security.md)。
+    > **警告：**
+    >
+    > 请务必保留 `use_backend` 指令中的 `if` 部分，确保只有该路径下的服务会被反向代理，否则将引入安全风险。参见[提高 TiDB Dashboard 安全性](/dashboard/dashboard-ops-security.md)。
 
 2. 重启 HAProxy，以使配置生效。
 
@@ -77,26 +77,26 @@ http://192.168.0.123:2379/dashboard/
 
 1. 以在 8033 端口反向代理 TiDB Dashboard 为例，在 NGINX 配置文件中，新增如下配置：
 
-   ```nginx
-   server {
-     listen 8033;
-     location /dashboard/ {
-       proxy_pass http://192.168.0.123:2379/dashboard/;
-     }
-   }
-   ```
+    ```nginx
+    server {
+      listen 8033;
+      location /dashboard/ {
+        proxy_pass http://192.168.0.123:2379/dashboard/;
+      }
+    }
+    ```
 
-   其中 `http://192.168.0.123:2379/dashboard/` 需替换为[第 1 步：获取实际 TiDB Dashboard 地址](#第-1-步获取实际-tidb-dashboard-地址)中取得的 TiDB Dashboard 实际地址。
+    其中 `http://192.168.0.123:2379/dashboard/` 需替换为[第 1 步：获取实际 TiDB Dashboard 地址](#第-1-步获取实际-tidb-dashboard-地址)中取得的 TiDB Dashboard 实际地址。
 
-   > **警告：**
-   >
-   > 请务必保留 `proxy_pass` 指令中的 `/dashboard/` 路径，确保只有该路径下的服务会被反向代理，否则将引入安全风险。参见[提高 TiDB Dashboard 安全性](/dashboard/dashboard-ops-security.md)。
+    > **警告：**
+    >
+    > 请务必保留 `proxy_pass` 指令中的 `/dashboard/` 路径，确保只有该路径下的服务会被反向代理，否则将引入安全风险。参见[提高 TiDB Dashboard 安全性](/dashboard/dashboard-ops-security.md)。
 
 2. 重新载入 NGINX 以使配置生效：
 
-   ```shell
-   sudo nginx -s reload
-   ```
+    ```shell
+    sudo nginx -s reload
+    ```
 
 3. 测试反向代理是否生效：访问 NGINX 所在机器的 8033 端口下 `/dashboard/` 地址，如 `http://example.com:8033/dashboard/`，即可访问 TiDB Dashboard。
 
@@ -130,49 +130,49 @@ server_configs:
 
 1. 以编辑模式打开该集群的配置文件（将 `CLUSTER_NAME` 替换为集群名称）
 
-   ```shell
-   tiup cluster edit-config CLUSTER_NAME
-   ```
+    ```shell
+    tiup cluster edit-config CLUSTER_NAME
+    ```
 
 2. 在 `server_configs` 的 `pd` 配置下修改或新增配置项，若没有 `server_configs` 请在最顶层新增：
 
-   ```yaml
-   server_configs:
-     pd:
-       dashboard.public-path-prefix: /foo
-   ```
-
-   修改完成后的配置文件类似于：
-
-   ```yaml
-   server_configs:
-     pd:
-       dashboard.public-path-prefix: /foo
-   global:
-     user: tidb
-     ...
-   ```
-
-   或
-
-   ```yaml
-   monitored:
-     ...
-   server_configs:
-     tidb: ...
-     tikv: ...
-     pd:
-       dashboard.public-path-prefix: /foo
-     ...
-   ```
+    ```yaml
+    server_configs:
+      pd:
+        dashboard.public-path-prefix: /foo
+    ```
+
+    修改完成后的配置文件类似于：
+
+    ```yaml
+    server_configs:
+      pd:
+        dashboard.public-path-prefix: /foo
+    global:
+      user: tidb
+      ...
+    ```
+
+    或
+
+    ```yaml
+    monitored:
+      ...
+    server_configs:
+      tidb: ...
+      tikv: ...
+      pd:
+        dashboard.public-path-prefix: /foo
+      ...
+    ```
 
 3. 滚动重启所有 PD 实例生效配置（将 `CLUSTER_NAME` 替换为集群名称）
 
-   ```shell
-   tiup cluster reload CLUSTER_NAME -R pd
-   ```
+    ```shell
+    tiup cluster reload CLUSTER_NAME -R pd
+    ```
 
-   详情请参阅 [TiUP 常见运维操作 - 修改配置参数](/maintain-tidb-using-tiup.md#修改配置参数)。
+    详情请参阅 [TiUP 常见运维操作 - 修改配置参数](/maintain-tidb-using-tiup.md#修改配置参数)。
 
 </details>
 

diff --git a/dashboard/dashboard-resource-manager.md b/dashboard/dashboard-resource-manager.md
@@ -57,7 +57,9 @@ summary: 介绍如何使用 TiDB Dashboard 的资源管控页面查看资源管
 
     - 如果时间窗口范围不满足 10 分钟至 24 小时的条件，会报错 `Error 1105 (HY000): the duration of calibration is too short, which could lead to inaccurate output. Please make the duration between 10m0s and 24h0m0s`。
 
-    - 如果时间窗口范围内的负载过低，会报错 `Error 1105 (HY000): The workload in selected time window is too low, with which TiDB is unable to reach a capacity estimation; please select another time window with higher workload, or calibrate resource by hardware instead`。
+    - [根据实际负载估算容量](/sql-statements/sql-statement-calibrate-resource.md#根据实际负载估算容量)功能的监控指标包括 `tikv_cpu_quota`、`tidb_server_maxprocs`、`resource_manager_resource_unit`、`process_cpu_usage`。如果 CPU quota 监控数据为空，会有对应监控项名称的报错，如 `Error 1105 (HY000): There is no CPU quota metrics, metrics 'tikv_cpu_quota' is empty`。
+
+    - 如果时间窗口范围内的负载过低或者 `resource_manager_resource_unit` 及 `process_cpu_usage` 监控数据缺失，会报错 `Error 1105 (HY000): The workload in selected time window is too low, with which TiDB is unable to reach a capacity estimation; please select another time window with higher workload, or calibrate resource by hardware instead`。此外，由于 TiKV 未在 macOS 上监控 CPU 使用率，所以不支持根据实际负载估算容量功能，也会报告此错误。
 
   可以通过[监控指标](#监控指标)中的 **CPU Usage** 选择合适的时间范围。
 

diff --git a/dashboard/dashboard-session-sso.md b/dashboard/dashboard-session-sso.md
@@ -214,13 +214,13 @@ TiDB Dashboard 支持基于 [OIDC](https://openid.net/connect/) 协议的单点
 
 5. 在**回调 URLs** 中添加如下内容：
 
-   ```
-   http://DASHBOARD_IP:PORT/dashboard/?sso_callback=1
-   ```
+    ```
+    http://DASHBOARD_IP:PORT/dashboard/?sso_callback=1
+    ```
 
-   在以上内容中，将 `DASHBOARD_IP:PORT` 替换为你在浏览器中实际访问 TiDB Dashboard 所使用的域名（或 IP）及端口。   
+    在以上内容中，将 `DASHBOARD_IP:PORT` 替换为你在浏览器中实际访问 TiDB Dashboard 所使用的域名（或 IP）及端口。
 
-   ![Settings](/media/dashboard/dashboard-session-sso-casdoor-settings-2.png)
+    ![Settings](/media/dashboard/dashboard-session-sso-casdoor-settings-2.png)
 
 6. 其他设置保留默认值，点击**保存 & 退出**。