Contents
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 refusedjavax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)
これらのメッセージから、ネットワーク接続の問題、SSL/TLS設定の不一致、または認証エラーなどの可能性を検討できます。
ログ出力レベルの確認方法
Spring BootではデフォルトでINFOレベルでログが出力されますが、詳細な情報が必要な場合はapplication.propertiesに以下を追加します：
|
1 2 3 |
logging.level.org.springframework.jdbc=DEBUG logging.level.com.zaxxer.hikari=DEBUG |
これにより、データベースプールやSQL実行の詳細なログが取得可能です。
スタックトレースからヒントを得る
スタックトレースを検証する際は、例外発生位置（Caused by:以降）に着目します。例として、以下のようなスタックトレースが表示される場合：
|
1 2 3 4 |
Caused by: com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure ... |
これはネットワーク接続の失敗を示しており、MySQLサーバー側の状態やファイアウォール設定を確認する必要があります。
application.properties/ymlの接続情報確認手順
Spring BootアプリケーションがMySQLに接続できない場合、application.propertiesまたはapplication.ymlの設定が誤っている可能性があります。
spring.datasource.urlの正しい形式
MySQL 8.0以降では、JDBC URL形式が以下のように変更されています：
|
1 2 |
spring.datasource.url=jdbc:mysql://localhost:3306/mydb?allowPublicKeyRetrieval=true&useSSL=false |
allowPublicKeyRetrieval=true：MySQL 8.0の認証方式に対応。useSSL=false：SSL接続を無効化（必要に応じて有効化）。
注意：MySQL 5.xユーザーは、
?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8などのパラメータを追加して互換性を保つ必要があります。
ユーザー名とパスワードの再確認
|
1 2 3 |
spring.datasource.username=root spring.datasource.password=your_password |
MySQLで設定したユーザー名やパスワードが一致しているか、SHOW GRANTS FOR 'root'@'localhost';などで確認してください。
ドライバクラス設定の検証
以下を追加し、ドライバロードにエラーがないか確認します：
|
1 2 |
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver |
この設定がなければ、Spring Bootが自動でドライバを読み込めない場合があります。
MySQLサーバーの起動状態確認方法
MySQLサーバー側の異常やポート開放の問題により、接続エラーが発生します。手順に沿ってステータスを検証してください。
サービスステータスの確認コマンド
- Linux:
sudo systemctl status mysql - Windows: 「サービス」アプリケーションでMySQLの起動状態を確認。
MySQLが停止している場合は、sudo service mysql start（Linux）や「MySQL80」サービスを起動します。
ローカルでのmysqlクライアント接続テスト
コマンドラインから以下のように接続を試みてください：
|
1 2 |
mysql -u root -p -h localhost |
パスワード入力後、接続が成功するか確認します。失敗した場合は、MySQLの設定やユーザー権限に問題があります。
リモートアクセス可能かの検証
リモート接続が必要な場合、MySQLのmy.cnf（Linux）またはmy.ini（Windows）で以下を確認します：
|
1 2 |
bind-address = 0.0.0.0 |
設定後、MySQLサービスを再起動し、ファイアウォールのポート3306を開けます。
SSL/TLS接続時の認証エラー処理
SSL/TLSに関するエラーは、JDBC URLのパラメータやJavaセキュリティ設定が不一致になることで発生します。
javax.net.ssl.SSLHandshakeExceptionの対応
この例外は、SSL/TLSプロトコルの不一致や認証失敗を示します。以下のようにJDBC URLにrequireSSL=trueやuseSSL=falseを追加し、状況に応じて調整してください：
| パラメータ | 設定値 | 内容 |
|---|---|---|
useSSL |
false |
SSL接続を無効化 |
requireSSL |
true |
接続時にSSLが必須 |
sslMode |
DISABLED |
すべてのSSLチェックを無効化 |
Javaセキュリティプロファイルの確認
JavaのセキュリティプロファイルにMySQLサーバーの証明書が登録されていない場合、エラーが発生します。java.securityファイルにトラストストアパスを指定するか、以下のようなJDBC URLパラメータで対応できます：
|
1 2 |
spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=true&trustCertificateKeyStoreURL=file:/path/to/cacerts |
注意：
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対応の推奨バージョン
| Spring Boot Version | 推奨MySQL Connector/J Version |
|---|---|
| 3.0以上 | 8.0.33以上 |
Maven設定例：
|
1 2 3 4 5 6 |
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-j</artifactId> <version>8.0.33</version> </dependency> |
コンフリクトするライブラリの確認
spring-boot-starter-data-jpaなど他の依存関係でバージョンが上書きされていないか、mvn dependency:treeコマンドで確認してください。
データベースユーザー権限の確認手順
MySQLユーザーに接続権限やデータベースアクセス権がない場合、Spring Bootアプリケーションはエラーを返します。
GRANTコマンドによるアクセス許可の再確認
以下のようにGRANTコマンドで権限を設定してください：
|
1 2 3 |
GRANT ALL PRIVILEGES ON mydb.* TO 'user'@'localhost' IDENTIFIED BY 'password'; FLUSH PRIVILEGES; |
リモート接続許可の有無
リモートアクセスが必要な場合、以下のようにユーザー権限を設定します：
|
1 2 3 |
GRANT ALL PRIVILEGES ON mydb.* TO 'user'@'%' IDENTIFIED BY 'password'; FLUSH PRIVILEGES; |
パスワード認証方式のチェック
MySQL 8.0以降はcaching_sha2_passwordがデフォルトですが、Spring Bootアプリケーションでは以下の設定が必要です：
|
1 2 |
spring.datasource.url=jdbc:mysql://localhost:3306/mydb?allowPublicKeyRetrieval=true&useSSL=false |
トラブルケース別解決策と実行例
タイムアウトエラーの根本原因
- 原因: ネットワーク遅延やMySQLサーバーの応答遅れ。
- 対処法: JDBC URLに
connectTimeout=30000を追加し、タイムアウト時間を増やす。
ドライバ不一致時の対処
- エラーメッセージ例:
java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver - 解決策:
mysql-connector-jの依存関係をプロジェクトに追加し、バージョンを確認。
接続プールの設定最適化
HikariCPを使用する場合、以下のように接続プールサイズやタイムアウト時間を調整できます：
|
1 2 3 |
spring.datasource.hikari.maximum-pool-size=10 spring.datasource.hikari.idle-timeout=30000 |
まとめ
- エラーログの読み取りで、具体的な例外メッセージを抽出し、原因を特定。
- application.properties/yml設定やMySQLサーバーの起動状態を確認し、接続情報に誤りがないか検証。
- SSL/TLS設定やファイアウォール/ネットワーク設定を再チェックし、環境が整っているか確認。
- 依存ライブラリのバージョン管理とデータベースユーザー権限を厳密に設定。
具体的なエラーメッセージをコメント欄に投稿していただければ、個別に対応策をご提案いたします。