Spring BootとMySQLの接続エラー対処法 | 根本原因を3段階で突き止める

Spring BootとMySQLの接続エラー対処法：3段階で根本原因を突き止める方法

Spring BootアプリケーションがMySQLに接続できないという問題は、開発中によく遭遇するトラブルです。「起動エラーログの読み取り→設定項目の見直し→トラブルケース別解決策」の3段階アプローチで体系的に対処することで、素早く原因を特定できます。本記事では、2023年10月時点での最新情報をもとに、具体的なエラーメッセージの解釈方法や設定手順を詳しく解説します。

起動エラーログの読み取り：根本原因を特定する手順

Spring Bootアプリケーションの起動ログには、接続エラーの種類や発生場所に関する重要なヒントが含まれています。まず、ログ出力レベルを確認し、具体的な例外メッセージを抽出することが不可欠です。

よく見られる接続エラー例

• java.sql.SQLNonTransientConnectionException: Could not create connection to database server.
• java.net.ConnectException: Connection refused
• javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)

これらのメッセージから、ネットワーク接続の問題、SSL/TLS設定の不一致、または認証エラーなどの可能性を検討できます。

ログ出力レベルの確認方法

Spring BootではデフォルトでINFOレベルでログが出力されますが、詳細な情報が必要な場合はapplication.propertiesに以下を追加します：

これにより、データベースプールやSQL実行の詳細なログが取得可能です。

スタックトレースからヒントを得る

スタックトレースを検証する際は、例外発生位置（Caused by:以降）に着目します。例として、以下のようなスタックトレースが表示される場合：

これはネットワーク接続の失敗を示しており、MySQLサーバー側の状態やファイアウォール設定を確認する必要があります。

application.properties/ymlの接続情報確認手順

Spring BootアプリケーションがMySQLに接続できない場合、application.propertiesまたはapplication.ymlの設定が誤っている可能性があります。

spring.datasource.urlの正しい形式

MySQL 8.0以降では、JDBC URL形式が以下のように変更されています：

• allowPublicKeyRetrieval=true：MySQL 8.0の認証方式に対応。
• useSSL=false：SSL接続を無効化（必要に応じて有効化）。

注意：MySQL 5.xユーザーは、?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8などのパラメータを追加して互換性を保つ必要があります。

ユーザー名とパスワードの再確認

MySQLで設定したユーザー名やパスワードが一致しているか、SHOW GRANTS FOR 'root'@'localhost';などで確認してください。

ドライバクラス設定の検証

以下を追加し、ドライバロードにエラーがないか確認します：

この設定がなければ、Spring Bootが自動でドライバを読み込めない場合があります。

MySQLサーバーの起動状態確認方法

MySQLサーバー側の異常やポート開放の問題により、接続エラーが発生します。手順に沿ってステータスを検証してください。

サービスステータスの確認コマンド

• Linux: sudo systemctl status mysql
• Windows: 「サービス」アプリケーションでMySQLの起動状態を確認。

MySQLが停止している場合は、sudo service mysql start（Linux）や「MySQL80」サービスを起動します。

ローカルでのmysqlクライアント接続テスト

コマンドラインから以下のように接続を試みてください：

パスワード入力後、接続が成功するか確認します。失敗した場合は、MySQLの設定やユーザー権限に問題があります。

リモートアクセス可能かの検証

リモート接続が必要な場合、MySQLのmy.cnf（Linux）またはmy.ini（Windows）で以下を確認します：

設定後、MySQLサービスを再起動し、ファイアウォールのポート3306を開けます。

SSL/TLS接続時の認証エラー処理

SSL/TLSに関するエラーは、JDBC URLのパラメータやJavaセキュリティ設定が不一致になることで発生します。

javax.net.ssl.SSLHandshakeExceptionの対応

この例外は、SSL/TLSプロトコルの不一致や認証失敗を示します。以下のようにJDBC URLにrequireSSL=trueやuseSSL=falseを追加し、状況に応じて調整してください：

Javaセキュリティプロファイルの確認

JavaのセキュリティプロファイルにMySQLサーバーの証明書が登録されていない場合、エラーが発生します。java.securityファイルにトラストストアパスを指定するか、以下のようなJDBC URLパラメータで対応できます：

注意：trustCertificateKeyStoreURLはJava 8u162以降で利用可能です。古いバージョンでは、デフォルトのトラストストア(cacerts)を指定するか、カスタムパスを使用してください。

ファイアウォール/ネットワーク設定の影響

MySQLポート（デフォルト3306）が開いていない、またはセキュリティグループの設定が不適切な場合、接続エラーが発生します。

MySQLポートの開放状況

• オンプレミス: ファイアウォールルールで3306/tcpを許可。
• クラウド環境（AWS）: Security GroupでMySQLポートを開き、ソースIPを指定。

VPC環境でのセキュリティグループ設定

VPC内での接続の場合は、Spring BootアプリケーションとMySQLサーバーが同じサブネットに配置されているか、ルートテーブルやNATゲートウェイが正しく設定されているか確認してください。

依存ライブラリ（mysql-connector-java）のバージョン管理

古いバージョンのmysql-connector-javaはSpring Boot 3.xと互換性がないため、最新版を採用することが重要です。

Spring Boot 3.x対応の推奨バージョン

Maven設定例：

コンフリクトするライブラリの確認

spring-boot-starter-data-jpaなど他の依存関係でバージョンが上書きされていないか、mvn dependency:treeコマンドで確認してください。

データベースユーザー権限の確認手順

MySQLユーザーに接続権限やデータベースアクセス権がない場合、Spring Bootアプリケーションはエラーを返します。

GRANTコマンドによるアクセス許可の再確認

以下のようにGRANTコマンドで権限を設定してください：

リモート接続許可の有無

リモートアクセスが必要な場合、以下のようにユーザー権限を設定します：

パスワード認証方式のチェック

MySQL 8.0以降はcaching_sha2_passwordがデフォルトですが、Spring Bootアプリケーションでは以下の設定が必要です：

トラブルケース別解決策と実行例

タイムアウトエラーの根本原因

• 原因: ネットワーク遅延やMySQLサーバーの応答遅れ。
• 対処法: JDBC URLにconnectTimeout=30000を追加し、タイムアウト時間を増やす。

ドライバ不一致時の対処

• エラーメッセージ例: java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver
• 解決策: mysql-connector-jの依存関係をプロジェクトに追加し、バージョンを確認。

接続プールの設定最適化

HikariCPを使用する場合、以下のように接続プールサイズやタイムアウト時間を調整できます：

まとめ

• エラーログの読み取りで、具体的な例外メッセージを抽出し、原因を特定。
• application.properties/yml設定やMySQLサーバーの起動状態を確認し、接続情報に誤りがないか検証。
• SSL/TLS設定やファイアウォール/ネットワーク設定を再チェックし、環境が整っているか確認。
• 依存ライブラリのバージョン管理とデータベースユーザー権限を厳密に設定。

具体的なエラーメッセージをコメント欄に投稿していただければ、個別に対応策をご提案いたします。