背景
Devin環境でRailsアプリのセットアップを行っていた際、bundle install を実行したところ mysql2 gem のインストールが失敗し、原因特定と解決までに非常に時間がかかりました。
同じような環境で詰まっている方の参考になればと思い、原因と解決までの道のりをまとめます。
mysql2とは
mysql2 は Ruby (Rails) と MySQLデータベースを接続するためのgem です。
Railsの config/database.yml で adapter: mysql2 を指定している場合、MySQLに接続するために mysql2 gem が必須になります。
ただし、MySQLの公式Cライブラリ (libmysqlclient) に依存しており、インストール時にC拡張のビルドが必要 なため、環境によってはセットアップ時にエラーが発生しやすいです。
環境
- OS: Ubuntu (Devin環境)
- Ruby: 3.2.1
- Bundlerで
mysql2 0.5.6をインストールしようとした
発生したエラー
bundle install 実行時に以下のエラーが発生。
An error occurred while installing mysql2 (0.5.6), and Bundler cannot continue.
詳細なログでは mkmf.rb 内で NoMethodError が発生していました。
mkmf.rb:1083:in `block in find_library': undefined method `split' for nil:NilClass (NoMethodError)
試したこと
opensslの設定
最初は、openssl関連のエラーかと思い、Homebrewでインストールした openssl@3 のパスを環境変数に設定しました。
export LDFLAGS="-L/home/linuxbrew/.linuxbrew/opt/openssl@3/lib"
export CPPFLAGS="-I/home/linuxbrew/.linuxbrew/opt/openssl@3/include"
export PKG_CONFIG_PATH="/home/linuxbrew/.linuxbrew/opt/openssl@3/lib/pkgconfig"
bundle config build.mysql2 --with-ldflags="${LDFLAGS}" --with-cppflags="${CPPFLAGS}" --with-opt-dir="/home/linuxbrew/.linuxbrew/opt/openssl@3"
しかし、エラーは解消せず。
MySQL本体 (brew install mysql) のインストール
MySQL本体が必要かと思い、HomebrewでMySQLをインストール。
brew install mysql
しかし、mysql2 gem のビルド失敗には影響しませんでした。
原因
最終的な原因は、MySQLの開発用パッケージ (libmysqlclient-dev) がインストールされていないこと でした。
mysql2 gem をインストールするには、MySQLが提供しているC言語のライブラリ（libmysqlclient）と、その設計図であるヘッダファイル（mysql.h）が必要です。
※ プログラムがビルド時に必要とする設計図ファイル
Devin環境（Ubuntu系）では、このライブラリとヘッダは aptパッケージ (libmysqlclient-dev) として提供されており、これをインストールしないと mysql2 gem を正しくビルドできません。
HomebrewでMySQL本体をインストールしていても、ビルド時には参照されない ため、インストールに失敗していました。
解決方法
以下のコマンドで必要なパッケージをインストールし、bundle install したところ正常にインストールが完了しました。
sudo apt update
sudo apt install -y libmysqlclient-dev build-essential
bundle install
これにより MySQL公式Cライブラリとビルドツールがインストール され、mysql2 gem が正常にビルド・インストールされました。
まとめ
| 試したこと | 効果 | 理由 |
|---|---|---|
| opensslのパス設定 | ❌ | opensslはmysql2 gemの必須依存ではなかった |
| brew install mysql | ❌ | Devin(Ubuntu)環境ではHomebrewのMySQLは無関係 |
| libmysqlclient-devのインストール | ✅ | mysql2 gemのC拡張ビルドに必須 |
最後に
今回のトラブルシュートを通じて、mysql2 gem のインストールにはMySQLの開発パッケージが必須 であることを再確認しました。
環境構築で詰まっている方は、まず libmysqlclient-dev の存在 を確認してみてください。
私自身、ここで多くの時間を使ってしまったので、この記事が同じ悩みを持つ方の助けになれば幸いです。