Nova Kwok's Awesome Blog

在 TiDB 上跑 Atlassian Jira

TiDB 是一个兼容 MySQL 协议的分布式数据库,基于其分布式数据库的特征,我们可以部署出很多有有意思拓扑架构,比如在我和一些同学的家中(上海浦东,上海浦西,杭州,重庆,成都)就有一个跑在树莓派上的 TiDB 集群供内部 Metabase 使用,再比如前一阵子我们 v5.0 发布会的时候我也参与设计+搭建了一个跨 PingCAP 办公室网络的跑在树莓派上的"大集群",供大家签到使用。

以上 Overlay 网络均由 Wireguard 实现

Jira 的母公司 Atlassian 可能对于普通用户来说没啥概念,在他们收购了 Trello (那就不得不有概念了) 了之后,似乎成为了 kanban 类节目的行业老大,Jira 就是一个企业常用的 Issue 管理平台,凭借着超高的内存占用,昂贵的售价和 Java 的风格独领风骚。(但是好用是真的,只需要创建 Issue ,Assign 给对应人,就可以持续追踪整个事情的进度了),只要他别像下图这样操作就好(啥都不记录,然后 6s 内就从 Development 到 Resolved):


TiDB 既然是一个兼容 MySQL 协议的数据库,自然我们希望把 Jira 也直接跑在上面,防止单机数据库宕机或磁盘损坏导致的潜在的不可用的问题。参考「在 Docker 中部署 Jira 和 Confluence 並連接到 Amazon RDS」一文,很自然的我们就会想到启动一个 Jira 的实例,并开始连接 TiDB,其中 Jira 的 docker-compose.yml 文件内容如下:

version: '3.3'
services:
    jira-software:
        image: atlassian/jira-software:8.16.0
        volumes:
            - ./jira_data:/var/atlassian/application-data/jira
            - ./jira_lib/mysql-connector-java-5.1.49-bin.jar:/opt/atlassian/jira/lib/mysql-connector-java-5.1.49-bin.jar
            - ./jira_lib/mysql-connector-java-5.1.49.jar:/opt/atlassian/jira/lib/mysql-connector-java-5.1.49.jar
            - ./jira_lib/mysql-connector-java-8.0.23.jar:/opt/atlassian/jira/lib/mysql-connector-java-8.0.23.jar
        ports:
            - '8080:8080'

这里 TiDB 出于简单考虑,我们直接使用 tiup playground:

tiup playground v5.0.1 --host "0.0.0.0" --tiflash 0

创建数据库:

CREATE DATABASE jiradb CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

然后配置数据库,就可以…

换个 MySQL 8.0 试试?

咦?

通过阅读 Jira 的文档我们知道,如果使用 MySQL 数据库,需要设置一下 my.ini ,根据文档 Connecting Jira to MySQL 8.0 可以了解到,需要设置以下内容:

default-storage-engine=INNODB
character_set_server=utf8mb4
innodb_default_row_format=DYNAMIC
innodb_log_file_size=2G

所以如果你用我整理好的 Jira 可用的 MySQL 配置(在 https://github.com/n0vad3v/dockerfiles/tree/master/simple-mysql/jira 中)启动 MySQL 的话,可以通过:

SHOW VARIABLES LIKE 'character_set_server';
SELECT @@innodb_default_row_format;
SELECT @@innodb_file_format;
SELECT @@innodb_large_prefix;

发现在 MySQL 下这些参数的表现如下:

mysql> SHOW VARIABLES LIKE 'character_set_server';
+----------------------+---------+
| Variable_name        | Value   |
+----------------------+---------+
| character_set_server | utf8mb4 |
+----------------------+---------+
1 row in set (0.01 sec)mysql> SELECT @@innodb_default_row_format;
+-----------------------------+
| @@innodb_default_row_format |
+-----------------------------+
| dynamic                     |
+-----------------------------+
1 row in set (0.00 sec)mysql> SELECT @@innodb_file_format;
+----------------------+
| @@innodb_file_format |
+----------------------+
| Barracuda            |
+----------------------+
1 row in set (0.00 sec)mysql> SELECT @@innodb_large_prefix;
+-----------------------+
| @@innodb_large_prefix |
+-----------------------+
|                     1 |
+-----------------------+
1 row in set (0.00 sec)

而如果在 TiDB 下执行的话,是如下结果:

mysql> SHOW VARIABLES LIKE 'character_set_server';
+----------------------+---------+
| Variable_name        | Value   |
+----------------------+---------+
| character_set_server | utf8mb4 |
+----------------------+---------+
1 row in set (0.51 sec)mysql> SELECT @@innodb_default_row_format;
ERROR 1193 (HY000): Unknown system variable 'innodb_default_row_format'
mysql> SELECT @@innodb_file_format;
+----------------------+
| @@innodb_file_format |
+----------------------+
| Antelope             |
+----------------------+
1 row in set (0.00 sec)mysql> SELECT @@innodb_large_prefix;
+-----------------------+
| @@innodb_large_prefix |
+-----------------------+
|                     0 |
+-----------------------+
1 row in set (0.00 sec)

可以看到有些系统变量不太一致,这个时候第一反应就是:

mysql> set @@global.innodb_default_row_format = "dynamic";
ERROR 1193 (HY000): Unknown system variable 'innodb_default_row_format'
mysql> set @@global.innodb_file_format = "barracuda";
Query OK, 0 rows affected (0.03 sec)

mysql> set @@global.innodb_large_prefix = 1;
Query OK, 0 rows affected (0.00 sec)

然后重新连接确认:

mysql> SHOW VARIABLES LIKE 'character_set_server';
+----------------------+---------+
| Variable_name        | Value   |
+----------------------+---------+
| character_set_server | utf8mb4 |
+----------------------+---------+
1 row in set (0.62 sec)

mysql> SELECT @@innodb_default_row_format;
ERROR 1193 (HY000): Unknown system variable 'innodb_default_row_format'
mysql> SELECT @@innodb_file_format;
+----------------------+
| @@innodb_file_format |
+----------------------+
| barracuda            |
+----------------------+
1 row in set (0.01 sec)

mysql> SELECT @@innodb_large_prefix;
+-----------------------+
| @@innodb_large_prefix |
+-----------------------+
|                     1 |
+-----------------------+
1 row in set (0.00 sec)

看上去除了 innodb_default_row_format 以外其他的都和 MySQL 的一致了,我们再来试试看:

所以猜测可能就是 innodb_default_row_format 的不一致导致了上述问题。

Jira DB Check

由于报错信息只显示一个「This MySQL instance is not properly configured.」,而且容器日志中没有任何相关的 ERROR 日志,反正只要有任何不对 Jira 就说「not properly configured」…

既然上述猜测没法石锤,作为 Jira 的订阅用户,可以通过阅读源码的方式来判断到底 Jira 在启动的时候检查了什么。

通过 rg 可以快速找到,在 jira-project/jira-components/jira-core/src/main/resources/com/atlassian/jira/web/action/JiraWebActionSupport.properties 文件的中,这个报错信息是被定义在一个变量中了(而且一个等号两边有空格一个没有,非常迷惑)

13299:setupdb.error.mysqlVersion57.wrong.default.configuration=This MySQL instance is not properly configured. Please follow <a target="_blank" href="{0}">the documentation for MySQL 5.7 setup</a>.
13301:setupdb.error.mysqlVersion8.wrong.default.configuration = This MySQL instance is not properly configured. Please follow <a target="_blank" href="{0}">the documentation for MySQL 8 setup</a>.

继续 rg "setupdb.error.mysqlVersion57.wrong.default.configuration" ,可以发现,在 jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/web/action/setup/SetupDatabase.java 中有使用,查看相关代码可以发现:

try (Connection conn = databaseConfiguration.getDatasource().getConnection(bootstrapManager)){
    isDatabaseEmpty = databaseConfiguration.isDatabaseEmpty(bootstrapManager);
    if ("mysql57".equals(databaseConfiguration.getDatabaseType())) {
        isMySQL57VersionCorrect = new MySQL57OrLaterVersionPredicate().test(conn);
        isMySQL57ConfigurationCorrect = new MySQL57DefaultRowFormatChecker().test(conn);
    } else if ("mysql8".equals(databaseConfiguration.getDatabaseType())) {
        isMySQL8VersionCorrect = new MySQL8VersionPredicate().test(conn);
        isMySQL8ConfigurationCorrect = new MySQL8ConfigurationChecker().test(conn);
    }
} catch (BootstrapException | SQLException e) {
    ...
}

所以对于 MySQL 5.7 来说,就是:

而对于 MySQL 8.0 来说,是:

分别找到对应函数的定义,可以发现,在 jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/config/database/MySQL57OrLaterVersionPredicate.java 中,会检查 MySQL 5.7 模式下是否是真的 MySQL 5.7:

if ( major < 5 || (major == 5 && minor < 7) || major > 5) {
    return false;
} else {
    return true;
}
} catch (SQLException ex) {
    return false;
}

且在 jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/config/database/MySQL57DefaultRowFormatChecker.java 中可以看到:

try {
    return "DYNAMIC".equalsIgnoreCase(res.loadGlobalVariableFromServer("innodb_default_row_format")) &&
            "utf8mb4".equalsIgnoreCase(res.loadGlobalVariableFromServer("character_set_server")) &&
            "Barracuda".equalsIgnoreCase(res.loadGlobalVariableFromServer("innodb_file_format")) &&
            "on".equalsIgnoreCase(res.loadGlobalVariableFromServer("innodb_large_prefix"));
} catch (SQLException ex) {
    return false;
}

而对于 MySQL 8.0 模式下,我们可以在 jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/config/database/MySQL8ConfigurationChecker.java 文件中找到:

try {
    MySQLGlobalVariableResolver res = new MySQLGlobalVariableResolver(connection);
    return "DYNAMIC".equalsIgnoreCase(res.loadGlobalVariableFromServer("innodb_default_row_format")) &&
            "utf8mb4".equalsIgnoreCase(res.loadGlobalVariableFromServer("character_set_server"));
} catch (SQLException ex) {
    return false;
}

通过以上代码可以判定, Jira 在初始化数据库的时候会对数据库有以下检查:

这样看来可以解释上面遇到的以下问题:

  1. 在 MySQL 8.0 模式下报 MySQL 8 was selected but underlying database reports a different version. 的问题,因为 TiDB 对外展示的版本是 Server version: 5.7.25-TiDB-v5.0.1 TiDB Server (Apache License 2.0) Community Edition, MySQL 5.7 compatible ,显示的是 5.7
  2. 在 MySQL 5.7 模式下报 This MySQL instance is not properly configured. 因为 TiDB 没有 innodb_default_row_format 这个变量

Hack TiDB

通过上文源码的分析我们可以发现 Jira 在使用 MySQL 8.0 的时候对数据库的检查更少(此外,这里还有一个未展开的问题,Jira 会使用到名为 LEAD 的字段,使用 MySQL 5.7 模式会报错),所以我们决定使用 MySQL 8.0 模式来初始化 Jira。

Version

第一个问题就是 TiDB 的 Version ,我们希望 Jira 认为他是一个真正的 MySQL 8.0 ,所以需要让 TiDB “伪装"一下,通过查阅我们文档站 https://docs.pingcap.com/tidb/stable/tidb-configuration-file#server-version,可以发现有一个 server-version 的变量可以让 TiDB 的 Version 显示为一个不同的值,所以创建一个叫 8.0.toml 的文件,内容写一行:

server-version = "8.0.0-How-Ever-This-Is-TiDB-v5.0.1"

然后通过以下命令启动:

tiup playground v5.0.1 --host "0.0.0.0" --tiflash 0  --db.config ./8.0.toml

可以发现 TiDB 已经显示出了我们需要的版本:

~ # mysql -u root -h localhost -P4000
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1367
Server version: 8.0.0-How-Ever-This-Is-TiDB-v5.0.1 TiDB Server (Apache License 2.0) Community Edition, MySQL 5.7 compatible

innodb_default_row_format

接下来就是 innodb_default_row_format 这个变量的问题了,通过上文我们也发现,使用 set @@global.innodb_default_row_format = "dynamic"; 是无效的,会返回:

ERROR 1193 (HY000): Unknown system variable 'innodb_default_row_format'

所以可以判断出 TiDB 没有对应的系统变量,既然没有变量,那我们就 Mock 一个上去,在 https://github.com/pingcap/tidb/blob/master/sessionctx/variable/sysvar.go#L503 中我们可以发现 TiDB 的系统变量的定义的位置:

var defaultSysVars = []*SysVar{
	{Scope: ScopeGlobal, Name: MaxConnections, Value: "151", Type: TypeUnsigned, MinValue: 1, MaxValue: 100000, AutoConvertOutOfRange: true},
  ...
}

同时还能发现对应的注释:

// ScopeNone means the system variable can not be changed dynamically.
ScopeNone ScopeFlag = 0
// ScopeGlobal means the system variable can be changed globally.
ScopeGlobal ScopeFlag = 1 << 0
// ScopeSession means the system variable can only be changed in current session.
ScopeSession ScopeFlag = 1 << 1

考虑到之前是使用的 v5.0.1 版本的 TiDB,所以就是:

git clone https://github.com/pingcap/tidb
git checkout v5.0.1

由于我不怎么会写代码,所以只能照葫芦画瓢在 var defaultSysVars = []*SysVar{ 底下糊上一行:

{Scope: ScopeNone, Name: "innodb_default_row_format", Value: "dynamic"},

加完这一行后 make,然后把 bin/tidb-server 替换到 /root/.tiup/components/tidb/v5.0.1/tidb-server 这个文件中,然后重新启动数据库。

然后就可以正常安装使用啦~

以上。

Reference

  1. Connecting Jira to MySQL 8.0
  2. TiDB Configuration File

#Chinese #TiDB