From f3e46e53f5118cf46db8ab24abad53f06b06cd19 Mon Sep 17 00:00:00 2001
From: Chengpeng Yan <41809508+Reminiscent@users.noreply.github.com>
Date: Tue, 17 Aug 2021 14:33:59 +0800
Subject: [PATCH] spm: add upgrade checklist for SPM (#6866)

---
 sql-plan-management.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/sql-plan-management.md b/sql-plan-management.md
index c36e101a3bf4..018a704954b3 100644
--- a/sql-plan-management.md
+++ b/sql-plan-management.md
@@ -319,3 +319,42 @@ create global binding for select * from t where a < 100 and b < 100 using select
     | max_execution_time | 查询过程最多消耗多少时间 |
 
 + `read_from_storage` 是一个非常特别的 hint，因为它指定了读表时选择从 TiKV 读还是从 TiFlash 读。由于 TiDB 提供隔离读的功能，当隔离条件变化时，这个 hint 对演进出来的执行计划影响很大，所以当最初创建的绑定中存在这个 hint，TiDB 会无视其所有演进的绑定。
+
+## 升级检查 (Upgrade Checklist)
+
+执行计划管理功能（SPM）在版本升级过程中可能会出现一些兼容性问题导致升级失败，你需要在版本升级前做一些检查，确保版本顺利升级。
+
+* 当你尝试从 v5.2 以前的版本（即 v4.0、v5.0、v5.1）升级到当前版本，需要注意在升级前检查自动演进的开关 `tidb_evolve_plan_baselines` 是否已经关闭。如果尚未关闭，则需要将其关闭后再进行升级。具体操作如下所示：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    -- 在待升级的版本上检查自动演进的开关 `tidb_evolve_plan_baselines` 是否关闭。
+  
+    select @@global.tidb_evolve_plan_baselines;
+  
+    -- 如果演进的开关 `tidb_evolve_plan_baselines` 尚未关闭，则需要将其关闭。
+  
+    set global tidb_evolve_plan_baselines = off;
+    ```
+
+* 当你尝试从 v4.0 版本升级到当前版本，需要注意在升级前检查所有可用绑定对应的查询语句在新版本中是否存在语法错误。如果存在语法错误，则需要删除对应的绑定。
+
+    具体操作如下所示：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    -- 在待升级的版本上检查现有可用绑定对应的查询语句。
+  
+    select bind_sql from mysql.bind_info where source != 'builtin' and status = 'using';
+  
+    -- 将上一条查询得到的结果，在新版本的测试环境中进行验证。
+  
+    bind_sql_0;
+    bind_sql_1;
+    ...
+  
+    -- 如果报错信息是语法错误（ERROR 1064 (42000): You have an error in your SQL syntax），则需要删除对应的绑定。
+    -- 如果是其他错误，如未找到表，则表示语法兼容，不需要进行额外的处理。
+    ```