MySQL 8.3環境でmysql2 gemをインストールする方法

## はじめに
MySQL 8.3の環境でmysql2 gemをインストールするのにちょっと苦労したので、対処法を書いておきます。

### 実行環境

本記事は以下の環境で検証しました。

- MySQL 8.3.0 (Homebrewでインストール)
- macOS 14.4.1
- MacBook Air M3
- Ruby 3.3.0

### 注意事項
この記事を書いている時点ではmysql2の最新バージョンは0.5.6です。
よって、mysql2 0.5.6を使う前提で記事を書きますが、さらに新しいバージョンがリリースされたときは対処法が異なる可能性があります。

https://github.com/brianmario/mysql2/releases

### 念のため用語の整理
本記事ではMySQLとmysql2というよく似た用語が出てきます。
プログラミング初心者の方はこれらをしっかり区別しながら読み進めてください。

- **MySQL** = RDBMS（DBサーバー）。執筆時点の最新バージョンは8.3.0（2024/1/16リリース）
- **mysql2** = MySQLをRubyで操作するためのgem。執筆時点の最新バージョンは0.5.6（2024/2/16リリース）

## TL;DR（長いので最初に結論）
対処法をざっくりまとめると以下の通りです。

- mysql2 0.5.5を使っている場合は`bundle update mysql2`で0.5.6以上にする
- それでもエラーになる（mysql2 0.5.6にアップデートできない）場合は以下のコマンドでmysql2 0.5.6（もしくはそれよりも新しい最新バージョン）を単体でインストールする

```
gem install mysql2 -v 0.5.6 -- --with-ldflags=-L$(brew --prefix zstd)/lib
```

- インストールに成功したら再度`bundle update mysql2`を実行する

ここから下では詳細な対処法を説明します。

## mysql2 0.5.5を使っていると発生するエラー

mysql2 gemを使っているRailsプロジェクトで`bundle install`を実行すると以下のようなエラーが出ました。

```
Fetching mysql2-0.5.5.gem
Building native extensions. This could take a while...
ERROR:  Error installing mysql2:
	ERROR: Failed to build gem native extension.

    current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.5/ext/mysql2
/Users/jnito/.rbenv/versions/3.3.0/bin/ruby extconf.rb
checking for rb_absint_size()... yes
checking for rb_absint_singlebit_p()... yes
checking for rb_gc_mark_movable()... yes
checking for rb_wait_for_single_fd()... yes
checking for rb_enc_interned_str() in ruby.h... yes
-----
Using --with-openssl-dir=/opt/homebrew/opt/openssl@3
-----
-----
Using mysql_config at /opt/homebrew/bin/mysql_config
-----
checking for mysql.h... yes
checking for errmsg.h... yes
checking for SSL_MODE_DISABLED in mysql.h... yes
checking for SSL_MODE_PREFERRED in mysql.h... yes
checking for SSL_MODE_REQUIRED in mysql.h... yes
checking for SSL_MODE_VERIFY_CA in mysql.h... yes
checking for SSL_MODE_VERIFY_IDENTITY in mysql.h... yes
checking for MYSQL.net.vio in mysql.h... yes
checking for MYSQL.net.pvio in mysql.h... no
checking for MYSQL_DEFAULT_AUTH in mysql.h... yes
checking for MYSQL_ENABLE_CLEARTEXT_PLUGIN in mysql.h... yes
checking for SERVER_QUERY_NO_GOOD_INDEX_USED in mysql.h... yes
checking for SERVER_QUERY_NO_INDEX_USED in mysql.h... yes
checking for SERVER_QUERY_WAS_SLOW in mysql.h... yes
checking for MYSQL_OPTION_MULTI_STATEMENTS_ON in mysql.h... yes
checking for MYSQL_OPTION_MULTI_STATEMENTS_OFF in mysql.h... yes
checking for my_bool in mysql.h... no
-----
Don't know how to set rpath on your system, if MySQL libraries are not in path mysql2 may not load
-----
-----
Setting libpath to /opt/homebrew/Cellar/mysql/8.3.0_1/lib
-----
creating Makefile

current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.5/ext/mysql2
make DESTDIR\= sitearchdir\=./.gem.20240418-36184-4r35cx sitelibdir\=./.gem.20240418-36184-4r35cx clean

current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.5/ext/mysql2
make DESTDIR\= sitearchdir\=./.gem.20240418-36184-4r35cx sitelibdir\=./.gem.20240418-36184-4r35cx
compiling client.c
In file included from client.c:15:
./mysql_enc_name_to_ruby.h:43:1: warning: a function definition without a prototype is deprecated in all versions of C and is not supported in C2x [-Wdeprecated-non-prototype]
mysql2_mysql_enc_name_to_rb_hash (str, len)
^
./mysql_enc_name_to_ruby.h:86:1: warning: a function definition without a prototype is deprecated in all versions of C and is not supported in C2x [-Wdeprecated-non-prototype]
mysql2_mysql_enc_name_to_rb (str, len)
^
client.c:1438:3: error: call to undeclared function 'mysql_ssl_set'; ISO C99 and later do not support implicit function declarations [-Wimplicit-function-declaration]
  mysql_ssl_set(wrapper->client,
  ^
client.c:1438:3: note: did you mean 'mysql_close'?
/opt/homebrew/Cellar/mysql/8.3.0_1/include/mysql/mysql.h:797:14: note: 'mysql_close' declared here
void STDCALL mysql_close(MYSQL *sock);
             ^
2 warnings and 1 error generated.
make: *** [client.o] Error 1

make failed, exit code 2

Gem files will remain installed in /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.5 for inspection.
Results logged to /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/extensions/arm64-darwin-23/3.3.0/mysql2-0.5.5/gem_make.out
```

エラーの原因は以下の部分のようです。

```
client.c:1438:3: error: call to undeclared function 'mysql_ssl_set'; ISO C99 and later do not support implicit function declarations [-Wimplicit-function-declaration]
  mysql_ssl_set(wrapper->client,
  ^
```

上のエラーメッセージに出ている`mysql_ssl_set`という関数はMySQL 8.3で削除されたようです。

> mysql_ssl_set was deprecated on 8.2 and removed on 8.3.
> https://github.com/brianmario/mysql2/issues/1346

ただし、この問題はmysql2 0.5.6で解決されています。

> Support for libmysqlclient 8.3
> https://github.com/brianmario/mysql2/releases/tag/0.5.6

## mysql2 0.5.6で発生するエラー
そこで、mysql2 gemのバージョンを上げてみます。

```
bundle update mysql2
```

すると今後は別のエラーが出ました。

```
Fetching mysql2-0.5.6.gem
Building native extensions. This could take a while...
ERROR:  Error installing mysql2:
	ERROR: Failed to build gem native extension.

    current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.6/ext/mysql2
/Users/jnito/.rbenv/versions/3.3.0/bin/ruby extconf.rb
checking for rb_absint_size()... yes
checking for rb_absint_singlebit_p()... yes
checking for rb_gc_mark_movable()... yes
checking for rb_wait_for_single_fd()... yes
checking for rb_enc_interned_str() in ruby.h... yes
-----
Using --with-openssl-dir=/opt/homebrew/opt/openssl@3
-----
-----
Using mysql_config at /opt/homebrew/bin/mysql_config
-----
checking for mysql.h... yes
checking for errmsg.h... yes
checking for SSL_MODE_DISABLED in mysql.h... yes
checking for SSL_MODE_PREFERRED in mysql.h... yes
checking for SSL_MODE_REQUIRED in mysql.h... yes
checking for SSL_MODE_VERIFY_CA in mysql.h... yes
checking for SSL_MODE_VERIFY_IDENTITY in mysql.h... yes
checking for MYSQL.net.vio in mysql.h... yes
checking for MYSQL.net.pvio in mysql.h... no
checking for MYSQL_DEFAULT_AUTH in mysql.h... yes
checking for MYSQL_ENABLE_CLEARTEXT_PLUGIN in mysql.h... yes
checking for SERVER_QUERY_NO_GOOD_INDEX_USED in mysql.h... yes
checking for SERVER_QUERY_NO_INDEX_USED in mysql.h... yes
checking for SERVER_QUERY_WAS_SLOW in mysql.h... yes
checking for MYSQL_OPTION_MULTI_STATEMENTS_ON in mysql.h... yes
checking for MYSQL_OPTION_MULTI_STATEMENTS_OFF in mysql.h... yes
checking for my_bool in mysql.h... no
checking for mysql_ssl_set() in mysql.h... no
-----
Don't know how to set rpath on your system, if MySQL libraries are not in path mysql2 may not load
-----
-----
Setting libpath to /opt/homebrew/Cellar/mysql/8.3.0_1/lib
-----
creating Makefile

current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.6/ext/mysql2
make DESTDIR\= sitearchdir\=./.gem.20240418-36441-xndr2u sitelibdir\=./.gem.20240418-36441-xndr2u clean

current directory: /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.6/ext/mysql2
make DESTDIR\= sitearchdir\=./.gem.20240418-36441-xndr2u sitelibdir\=./.gem.20240418-36441-xndr2u
compiling client.c
In file included from client.c:15:
./mysql_enc_name_to_ruby.h:43:1: warning: a function definition without a prototype is deprecated in all versions of C and is not supported in C2x [-Wdeprecated-non-prototype]
mysql2_mysql_enc_name_to_rb_hash (str, len)
^
./mysql_enc_name_to_ruby.h:86:1: warning: a function definition without a prototype is deprecated in all versions of C and is not supported in C2x [-Wdeprecated-non-prototype]
mysql2_mysql_enc_name_to_rb (str, len)
^
2 warnings generated.
compiling infile.c
compiling mysql2_ext.c
compiling result.c
result.c:304:35: warning: implicit conversion loses integer precision: 'unsigned long' to 'int' [-Wshorten-64-to-32]
        precision = field->length - (field->decimals > 0 ? 2 : 1);
                  ~ ~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
compiling statement.c
linking shared-object mysql2/mysql2.bundle
ld: library 'zstd' not found
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [mysql2.bundle] Error 1

make failed, exit code 2

Gem files will remain installed in /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/gems/mysql2-0.5.6 for inspection.
Results logged to /Users/jnito/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0/extensions/arm64-darwin-23/3.3.0/mysql2-0.5.6/gem_make.out
```

どうやらzstdというライブラリが見つからないようです。

```
ld: library 'zstd' not found
clang: error: linker command failed with exit code 1 (use -v to see invocation)
```

まず、zstdがインストールされているかどうか確認しましょう。

```
$ which zstd
/opt/homebrew/bin/zstd
```

もしzstdが見つからなければインストールしてください。

```
brew install zstd
```

そして、以下のコマンドでmysql2 0.5.6をインストールします（[参考](https://github.com/brianmario/mysql2/issues/1345)）。

```
gem install mysql2 -v 0.5.6 -- --with-ldflags=-L$(brew --prefix zstd)/lib
```

インストールが成功したことを確認します。

```
Building native extensions with: '--with-ldflags=-L/opt/homebrew/opt/zstd/lib'
This could take a while...
Successfully installed mysql2-0.5.6
1 gem installed
```

それから、Railsプロジェクトのmysql2をアップデートしてください。

```
bundle update mysql2
```

これで問題なくmysql2 gemが使えるようになるはずです。

## 参考文献
https://github.com/brianmario/mysql2/issues/1346

https://github.com/brianmario/mysql2/issues/1345

## おまけ：8.0にダウングレードしたMySQLを8.3に戻す
mysql2 0.5.6がリリースされる前はMySQL 8.3から8.0にダウングレードしろ、という解決策が提示されていました。

https://github.com/brianmario/mysql2/issues/1346#issuecomment-1918770943

わざわざ古いバージョンを使用するのはあまり好ましくない対処法なので、もしダウングレードしていた場合はMySQL 8.3（もしくはそれよりも新しい最新バージョン）に上げ直しましょう。

手順は以下の通りです。

- `brew uninstall mysql@8.0` でMySQL 8.0をアンインストール
- `~/.zshrc`を開いて以下の行があれば削除

```
export PATH="/opt/homebrew/opt/mysql@8.0/bin:$PATH"
```

- ターミナルを再起動
- `brew install mysql`で最新のMySQLをインストール
- `brew services start mysql`でMySQLを起動（もしくは`brew services restart mysql`で再起動）
- MySQL Serverのバージョンが8.3であることを確認

```
$ mysqld --version
/opt/homebrew/Cellar/mysql/8.3.0_1/bin/mysqld  Ver 8.3.0 for macos14.2 on arm64 (Homebrew)
```

- MySQL Clientのバージョンも8.3であることを確認

```
$ mysql --version
mysql  Ver 8.3.0 for macos14.2 on arm64 (Homebrew)
```

- `mysql -u root`でサーバに接続できることを確認

ここまで確認したら、本記事の「mysql2 0.5.6で発生するエラー」で説明している対処法を実施してください。