From 45989f0f6cff2a7fb30b3abf0da229ddcfef3728 Mon Sep 17 00:00:00 2001
From: crazycs520 <crazycs520@gmail.com>
Date: Mon, 25 Feb 2019 19:31:57 +0800
Subject: [PATCH] op-guide: add upgrade faq

---
 README.md               |   1 +
 op-guide/upgrade-FAQ.md | 118 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 op-guide/upgrade-FAQ.md

diff --git a/README.md b/README.md
index 7afe1e8499ef..3db8617c9c84 100755
--- a/README.md
+++ b/README.md
@@ -108,6 +108,7 @@
     - [升级组件版本](op-guide/ansible-deployment-rolling-update.md#升级组件版本)
     - [TiDB 2.0 升级操作指南](op-guide/tidb-v2.0-upgrade-guide.md)
     - [TiDB 2.1 升级操作指南](op-guide/tidb-v2.1-upgrade-guide.md)
+    - [升级后常见 FAQ](/op-guide/upgrade-FAQ.md)
   - [性能调优](op-guide/tune-tikv.md)
   + 备份与迁移
     - [备份与恢复](op-guide/backup-restore.md)
diff --git a/op-guide/upgrade-FAQ.md b/op-guide/upgrade-FAQ.md
new file mode 100644
index 000000000000..54d25cf72827
--- /dev/null
+++ b/op-guide/upgrade-FAQ.md
@@ -0,0 +1,118 @@
+---
+title: 升级后常见 FAQ
+category: deployment
+---
+
+# 升级后常见 FAQ
+
+本文列出了一些升级后的可能会遇到的问题。
+
+1. 字符集（charset）问题1: unsupported modify column charset utf8mb4 not match origin utf8
+    TiDB 在 v2.1.0 以及之前（包括v2.0 所有版本）默认字符集是 utf8，从 v2.1.1 开始，默认字符集变更为 utf8mb4。如果在 v2.1.0 之前建表时显式指定了 table 的 charset 为 utf8，那后升级到 v2.1.1 之后，执行 DDL 变更可能会失败。示例如下：
+      v2.1.0 and before v2.1.0
+
+    ```SQL
+    tidb > create table t(a varchar(10)) charset=utf8;
+    Query OK, 0 rows affected
+    Time: 0.106s
+    tidb > show create table t
+    +-------+-------------------------------------------------------+
+    | Table | Create Table                                          |
+    +-------+-------------------------------------------------------+
+    | t     | CREATE TABLE `t` (                                    |
+    |       |   `a` varchar(10) DEFAULT NULL                        |
+    |       | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin |
+    +-------+-------------------------------------------------------+
+    1 row in set
+    Time: 0.006s
+    ```
+    after v2.1.0, before v2.1.3
+    ```SQL
+    tidb > use test
+    You are now connected to database "test" as user "root"
+    Time: 0.000s
+    tidb > alter table t change column a a varchar(20);
+    (1105, u'unsupported modify column charset utf8mb4 not match origin utf8')
+    ```
+
+    解决方案：显式指定 column charset，保持和原来的 charset 一致即可。
+
+    ```sql
+    alter table t change column a a varchar(22) character set utf8;
+    ```
+
+    v2.1.3 之前不支持修改column 的charset , 所以需要指定column charset 保持和原来一致。v2.1.3 之前，`show create table` 不会显示 column 的 charset，即使 column 的 charset 和 table 的 charset 不一样。只能通过 http  api 拿table 的元信息查看 column 的 schema。然后根据 column 名字和 Charset 关键字搜索即可找到
+
+    ```shell
+    ▶ curl "http://$IP:10080/schema/test/t"
+    {
+        "ShardRowIDBits": 0,
+        "auto_inc_id": 0,
+        "charset": "utf8",
+        "collate": "",
+        "cols": [
+            {
+                ...
+                "id": 1,
+                "name": {
+                    "L": "a",
+                    "O": "a"
+                },
+                "offset": 0,
+                "origin_default": null,
+                "state": 5,
+                "type": {
+                    "Charset": "utf8",
+                    "Collate": "utf8_bin",
+                    "Decimal": 0,
+                    "Elems": null,
+                    "Flag": 0,
+                    "Flen": 10,
+                    "Tp": 15
+                }
+            }
+        ],
+        ...
+    }
+    ```
+
+2. 字符集（charset）问题2 : unsupported modify charset from utf8mb4 to utf8
+
+   v2.1.1
+
+   ```sql
+   tidb > create table t(a varchar(10)) charset=utf8;
+   Query OK, 0 rows affected
+   Time: 0.109s
+   ```
+
+   v2.1.3
+
+   ```sql
+   tidb > show create table t
+   +-------+--------------------------------------------------------------------+
+   | Table | Create Table                                                       |
+   +-------+--------------------------------------------------------------------+
+   | t     | CREATE TABLE `t` (                                                 |
+   |       |   `a` varchar(10) CHARSET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL |
+   |       | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin              |
+   +-------+--------------------------------------------------------------------+
+   1 row in set
+   Time: 0.007s
+   tidb > alter table t change column a a varchar(20);
+   (1105, u'unsupported modify charset from utf8mb4 to utf8')
+   ```
+
+   因为v2.1.3 之后支持修改column 和  table 的 charset 了，所以这里推荐修改table 的charset 为 utf8mb4。
+
+   ```
+   alter table t convert to character set utf8mb4;
+   ```
+
+   也可以像问题1一样指定 charset。
+
+   ```sql
+   alter table t change column a a varchar(20) character set utf8mb4;
+   ```
+
+   
\ No newline at end of file