prepared plan cache: Enable by default (#4714)

* prepared plan cache: Enable by default * Update dashboard-faq.md * Update dashboard-faq.md * improve language * Update dashboard-faq.md * Update sql-prepare-plan-cache.md * Apply suggestions from code review Co-authored-by: Keke Yi <[email protected]> * Apply suggestions from code review Co-authored-by: Zhang Jian <[email protected]> Co-authored-by: Keke Yi <[email protected]> Co-authored-by: Zhang Jian <[email protected]>
pingcap · Oct 22, 2020 · bf67af2 · bf67af2
1 parent 960b30c
commit bf67af2
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 17 deletions.
diff --git a/dashboard/dashboard-faq.md b/dashboard/dashboard-faq.md
@@ -48,8 +48,8 @@ QPS 及 Latency 监控依赖于集群中已正常部署 Prometheus 监控实例
    tiup cluster start CLUSTER_NAME
    ```
 
-   即使集群已经启动，请仍然执行该命令。该命令不会影响集群上正常的业务，但会刷新并上报监控地址，从而能让监控在 TiDB Dashbaord 中正常显示。
+   即使集群已经启动，请仍然执行该命令。该命令不会影响集群上正常的业务，但会刷新并上报监控地址，从而能让监控在 TiDB Dashboard 中正常显示。
 
 ### 概况页面中 Top SQL 语句、最近慢查询显示 `invalid connection` 错误
 
-可能的原因是你开启了 TiDB 的 `prepared-plan-cache` 功能。作为实验性功能，`prepared-plan-cache` 在某些版本的 TiDB 中存在一些缺陷，开启后可能会导致 TiDB Dashboard（及其他应用）出现该问题。请依据[文档](/tidb-configuration-file.md#prepared-plan-cache)关闭 `prepared-plan-cache` 功能。
+此错误可能与 TiDB 的 `prepared-plan-cache` 功能有关。可以通过修改 [TiDB 配置文件](/tidb-configuration-file.md#prepared-plan-cache)来关闭 `prepared-plan-cache` 功能。
diff --git a/optimizer-hints.md b/optimizer-hints.md
@@ -308,7 +308,7 @@ SELECT /*+ READ_CONSISTENT_REPLICA() */ * FROM t;
 
 `IGNORE_PLAN_CACHE()` 提示优化器在处理当前 `prepare` 语句时不使用 plan cache。
 
-该 Hint 用于在 [prepare-plan-cache](/tidb-configuration-file.md#prepared-plan-cache) 开启的场景下临时对某类查询禁用 plan cache。
+该 Hint 用于临时对某类查询禁用 plan cache。
 
 以下示例强制该 `prepare` 语句不使用 plan cache：
 

diff --git a/sql-prepare-plan-cache.md b/sql-prepare-plan-cache.md
@@ -5,14 +5,12 @@ aliases: ['/docs-cn/dev/sql-prepare-plan-cache/']
 
 # 执行计划缓存
 
-TiDB 支持对 `Prepare` / `Execute` 请求的执行计划缓存。
+在当前的 TiDB 开发版本中，默认会缓存预处理语句（Prepared Statements）的执行计划。其中包括以下两种形式的预处理语句：
 
-`Prepare` / `Execute` 请求有两种形式：
+- 使用 `COM_STMT_PREPARE` 和 `COM_STMT_EXECUTE` 的协议功能；
+- 执行 `Prepare` / `Execute` SQL 语句查询；
 
-- 在 binary 通信协议下，用 `COM_STMT_PREPARE` 和 `COM_STMT_EXECUTE` 命令执行一般的参数化 SQL 查询；
-- 在文本通信协议下，用 `COM_QUERY` 命令执行 `Prepare` / `Execute` SQL 查询；
-
-优化器对这两种请求形式的处理是一致的：`Prepare` 时将参数化的 SQL 查询解析成 AST（抽象语法树），每次 `Execute` 时根据保存的 AST 和具体的参数值生成执行计划。
+TiDB 优化器对这两类查询的处理是一样的：`Prepare` 时将参数化的 SQL 查询解析成 AST（抽象语法树），每次 `Execute` 时根据保存的 AST 和具体的参数值生成执行计划。
 
 当开启执行计划缓存后，每条 `Prepare` 语句的第一次 `Execute` 会检查当前查询是否可以使用执行计划缓存，如果可以则将生成的执行计划放进一个由 LRU 链表构成的缓存中；在后续的 `Execute` 中，会先从缓存中获取执行计划，并检查是否可用，如果获取和检查成功则跳过生成执行计划这一步，否则重新生成执行计划并放入缓存中。
 
@@ -46,7 +44,7 @@ key 中任何一项变动（如切换数据库，重命名 `Prepare` 语句，
 - 考虑到不同 `Execute` 的参数会不同，执行计划缓存为了保证适配性会禁止一些和具体参数值密切相关的激进查询优化手段，导致对特定的一些参数值，查询计划可能不是最优。比如查询的过滤条件为 `where a > ? and a < ?`，第一次 `Execute` 时参数分别为 2 和 1，考虑到这两个参数下次执行时可能会是 1 和 2，优化器不会生成对当前参数最优的 `TableDual` 执行计划。
 - 如果不考虑缓存失效和淘汰，一份执行计划缓存会对应各种不同的参数取值，理论上也会导致某些取值下执行计划非最优。比如查询过滤条件为 `where a < ?`，假如第一次执行 `Execute` 时用的参数值为 1，此时优化器生成最优的 `IndexScan` 执行计划放入缓存，在后续执行 `Exeucte` 时参数变为 10000，此时 `TableScan` 可能才是更优执行计划，但由于执行计划缓存，执行时还是会使用先前生成的 `IndexScan`。因此执行计划缓存更适用于查询较为简单（查询编译耗时占比较高）且执行计划较为固定的业务场景。
 
-目前执行计划缓存功能默认关闭，可以通过打开配置文件中 [`prepare-plan-cache` 项](/tidb-configuration-file.md#prepared-plan-cache) 启用这项功能。
+执行计划缓存的最大语句条数默认为 100，可以通过修改 TiDB 配置文件中的 [`prepare-plan-cache`](/tidb-configuration-file.md#prepared-plan-cache) 项来配置此功能。
 
 > **注意：**
 >

diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md
@@ -287,7 +287,7 @@ TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/
 
 + Prepare cache LRU 使用的最大内存限制。当 Prepare cache LRU 的内存使用超过 `performance.max-memory * (1 - prepared-plan-cache.memory-guard-ratio)` 时，会剔除 LRU 中的元素。
 + 默认值：0
-+ 这个配置只有在 `prepared-plan-cache.enabled` 为 `true` 的情况才会生效。当 LRU 的 size 大于 `prepared-plan-cache.capacity` 时，也会剔除 LRU 中的元素。
++ 这个配置在 `prepared-plan-cache.enabled` 为 `true`（默认值）的情况才会生效。当 LRU 的 size 大于 `prepared-plan-cache.capacity` 时，也会剔除 LRU 中的元素。
 
 ### `txn-total-size-limit`
 
@@ -368,16 +368,12 @@ TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/
 
 ## prepared-plan-cache
 
-prepare 语句的 Plan cache 设置。
-
-> **警告：**
->
-> 当前该功能为实验特性，不建议在生产环境中使用。
+prepare 语句的 plan cache 设置。
 
 ### `enabled`
 
 + 开启 prepare 语句的 plan cache。
-+ 默认值：false
++ 默认值：true
 
 ### `capacity`