mysql2 gem インストールトラブルシューティング (macOS)

🚨 よくあるエラーと解決方法

macOSでmysql2 gemをインストールする際に発生する典型的なエラーとその解決方法をまとめました。

💡 発生しやすい環境

Ruby 3.0以上 + Rails 7/8
MySQL 8.0以上
macOS Big Sur以降（特にApple Silicon Mac）
最新のXcode + Command Line Tools

上記の組み合わせで特にエラーが発生しやすくなっています。

🔴 エラー1: 「mysql client is missing」

ERROR: Error installing mysql2:
ERROR: Failed to build gem native extension.
mysql client is missing

事前確認:

ターミナルで実行
# MySQLクライアントがインストールされているか確認
which mysql
# 何も表示されない場合は、MySQLがインストールされていません

# MySQLのバージョンを確認
mysql --version
# command not found と表示される場合は、インストールが必要です

解決方法:

ターミナルで実行
# 0. Homebrewがインストールされているか確認
which brew

🍺 Homebrewがまだインストールされていない方へ

which brew で何も表示されない場合は、先に Homebrew のセットアップガイドを参照してHomebrewをインストールしてください。特にApple Silicon Mac（M1/M2/M3）をお使いの方は、パスの設定が必要です。

ターミナルで実行（続き）
# 1. Homebrewを使ってMySQLクライアントをインストール
brew install mysql

# 2. MySQLのパスを確認
brew --prefix mysql

# 3. パスを指定してmysql2をインストール
gem install mysql2 -- --with-mysql-dir=$(brew --prefix mysql)

💡 Homebrewが毎回updateを実行して遅い場合

brew installのたびにupdateが走って時間がかかる場合は、以下の環境変数を設定してください：

~/.zshrcに追加
# Homebrewの自動アップデートを無効化
export HOMEBREW_NO_AUTO_UPDATE=1

設定後は source ~/.zshrc で反映させてください。必要な時だけ手動で brew update を実行することで、インストール時間を大幅に短縮できます。

🔴 エラー2: 「ld: library not found for -lssl」

ld: library not found for -lssl
clang: error: linker command failed with exit code 1

解決方法:

ターミナルで実行
# 1. OpenSSLをインストール
brew install openssl

# 2. パスを指定してインストール
gem install mysql2 -- \
  --with-ldflags="-L$(brew --prefix openssl)/lib" \
  --with-cppflags="-I$(brew --prefix openssl)/include"

🔴 エラー3: 「ld: library 'zstd' not found」

ld: library 'zstd' not found
clang: error: linker command failed with exit code 1

これは最新のMySQL 8.0以降で zstd（Zstandard圧縮ライブラリ）が必要になったために発生します。特に Ruby 3.x + Rails 7/8 の組み合わせで頻発します。

解決方法1（シンプル）:

ターミナルで実行
# 1. zstdライブラリをインストール
brew install zstd

# 2. LIBRARY_PATHに追加（これが重要！）
export LIBRARY_PATH=$LIBRARY_PATH:$(brew --prefix zstd)/lib/

# 3. bundle installを実行
bundle install

恒久的な解決のため、.zshrcに追加:

~/.zshrcに追加
# mysql2のためのライブラリパス
export LIBRARY_PATH=$LIBRARY_PATH:$(brew --prefix zstd)/lib/

解決方法2（詳細指定）:

上記で解決しない場合は、より詳細にパスを指定します：

ターミナルで実行
# MySQLを再インストール
brew reinstall mysql

# 必要なパスをすべて指定してmysql2をインストール
gem install mysql2 -- \
  --with-mysql-dir=$(brew --prefix mysql) \
  --with-ldflags="-L$(brew --prefix zstd)/lib -L$(brew --prefix openssl)/lib" \
  --with-cppflags="-I$(brew --prefix openssl)/include"

🔴 エラー4: Apple Silicon (M1/M2/M3) Mac特有の問題

ARM64アーキテクチャ特有の問題が発生する場合があります。

解決方法:

ターミナルで実行
# 1. 既存のMySQLをアンインストール
brew uninstall mysql

# 2. 必要な依存関係をすべてインストール
arch -arm64 brew install mysql zstd openssl

# 3. mysql2をインストール（すべてのパスを明示的に指定）
gem install mysql2 -- \
  --with-mysql-dir=$(brew --prefix mysql) \
  --with-mysql-config=$(brew --prefix mysql)/bin/mysql_config \
  --with-ldflags="-L$(brew --prefix zstd)/lib -L$(brew --prefix openssl)/lib" \
  --with-cppflags="-I$(brew --prefix openssl)/include"

🛠️ それでも解決しない場合

上記の個別の解決方法を試してもうまくいかない場合は、以下の手順を検討してください：

1. キャッシュのクリア

ターミナルで実行
# Bundlerのキャッシュをクリア
bundle config --delete build.mysql2
rm -rf ~/.bundle/cache

2. 環境を整理して再挑戦

ターミナルで実行
# 必要なライブラリがすべてインストールされているか確認
brew list | grep -E "(mysql|openssl|zstd)"

# 環境変数が正しく設定されているか確認
echo $LIBRARY_PATH

3. 講師やメンターに相談

30分以上試行錯誤している場合は、遠慮なく講師に質問しましょう！

質問する際は、以下の情報を共有すると解決が早くなります：

情報収集コマンド
# システム情報
sw_vers  # macOSのバージョン
ruby -v  # Rubyのバージョン
rails -v # Railsのバージョン

# エラーメッセージの全文をコピー
# bundle installの実行結果を保存
bundle install 2>&1 | tee bundle_error.log

💡 効率的な質問のコツ

エラーメッセージの全文を共有する
試した解決方法をリストアップする
実行環境（macOSバージョン、M1/M2/Intel Mac）を伝える
スクリーンショットがあると更に分かりやすい

🐳 第1章のDocker環境を使っている場合

第1章でDocker環境を構築した場合は、コンテナ内でbundle installを実行することでこれらのエラーを回避できます：

ターミナルで実行
# Dockerコンテナ内でbundle installを実行
docker compose exec web bundle install

💡 なぜDockerだとエラーが出ない？

Dockerコンテナ内には既に必要なライブラリがインストールされており、パスも正しく設定されているためです。第1章のDockerfileでdefault-mysql-client libmariadb-devがインストールされています。

📝 デバッグのヒント

事前確認コマンド集

ターミナルで実行
# 1. Homebrewの確認
which brew
brew --version
echo $(brew --prefix)  # Intel: /usr/local, Apple Silicon: /opt/homebrew

# 2. MySQLの確認
which mysql
mysql --version
brew list mysql 2>/dev/null || echo "MySQLはHomebrewでインストールされていません"

# 3. 必要なライブラリがすべてインストールされているか確認
for lib in mysql openssl zstd; do
  if brew list $lib &>/dev/null; then
    echo "✅ $lib is installed"
  else
    echo "❌ $lib is NOT installed"
  fi
done

# 4. 環境変数の確認
echo "LIBRARY_PATH: $LIBRARY_PATH"
echo "LDFLAGS: $LDFLAGS"
echo "CPPFLAGS: $CPPFLAGS"

mysql_configの確認

ターミナルで実行
# mysql_configが正しく動作するか確認
$(brew --prefix mysql)/bin/mysql_config --version
$(brew --prefix mysql)/bin/mysql_config --libs

💡 それでも解決しない場合

Rubyのバージョンを確認

ruby -v
# 古いバージョンの場合は rbenv や rvm で更新を検討

Xcodeコマンドラインツールを更新

xcode-select --install
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

特定バージョンのmysql2を使用

Gemfile
# 最新版で問題がある場合
gem 'mysql2', '0.5.3'  # 安定版を指定

📚 参考資料

⚠️ トラブルシューティングの時間目安

ローカル環境でのセットアップに30分以上かかっている場合：

特にLIBRARY_PATHの設定を確認（zstdエラーの主な原因）
講師やメンターに相談（環境構築で詰まるのはよくあることです！）
代替案として、Dockerコンテナ内でのbundle installを検討

# Dockerコンテナ内で実行（第1章の環境を使用）
docker compose exec web bundle install

環境構築は開発の第一歩です。遠慮なく質問して、スムーズに先へ進みましょう！

🚨 よくあるエラーと解決方法​

🔴 エラー1: 「mysql client is missing」​

🔴 エラー2: 「ld: library not found for -lssl」​

🔴 エラー3: 「ld: library 'zstd' not found」​

🔴 エラー4: Apple Silicon (M1/M2/M3) Mac特有の問題​

🛠️ それでも解決しない場合​

1. キャッシュのクリア​

2. 環境を整理して再挑戦​

3. 講師やメンターに相談​

🐳 第1章のDocker環境を使っている場合​

📝 デバッグのヒント​

事前確認コマンド集​

mysql_configの確認​

💡 それでも解決しない場合​

📚 参考資料​

🚨 よくあるエラーと解決方法

🔴 エラー1: 「mysql client is missing」

🔴 エラー2: 「ld: library not found for -lssl」

🔴 エラー3: 「ld: library 'zstd' not found」

🔴 エラー4: Apple Silicon (M1/M2/M3) Mac特有の問題

🛠️ それでも解決しない場合

1. キャッシュのクリア

2. 環境を整理して再挑戦

3. 講師やメンターに相談

🐳 第1章のDocker環境を使っている場合

📝 デバッグのヒント

事前確認コマンド集

mysql_configの確認

💡 それでも解決しない場合

📚 参考資料