背景

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 の存在 を確認してみてください。
私自身、ここで多くの時間を使ってしまったので、この記事が同じ悩みを持つ方の助けになれば幸いです。