DB接続失敗やSQLエラーの表示と対策を完全解説！初心者でもわかるSpringのエラーハンドリング

新人と先輩の会話形式で理解しよう

新人

「SpringでDBに接続しようとしたら、エラーになってしまいました…。どうすればいいんですか？」

先輩

「それは、DB接続の設定ミスやデータベース側の問題が原因かもしれないね。まずは、DB接続の仕組みから理解してみようか。」

新人

「はい！SpringのDB接続の仕組みについて教えてください！」

先輩

「じゃあ、まずはSpringでのDB接続の基本的な仕組みと、接続失敗の原因を一つずつ見ていこう。」

1. DB接続とは？

DB接続とは、アプリケーションとデータベースをつなぐための設定や処理のことを指します。Springアプリケーションでは、DBと連携してデータの保存や取得を行うことが多く、そのためには正しくDBに接続できている必要があります。

一般的には、Spring Bootのapplication.propertiesやapplication.ymlに、接続先の情報を設定することで、データベースとの接続を自動的に行ってくれます。

以下は、DB接続設定の例です。今回はGradle＋Pleiadesの前提で解説します。


spring.datasource.url=jdbc:mysql://localhost:3306/sampledb
spring.datasource.username=root
spring.datasource.password=password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

このように接続情報を設定することで、Springはアプリケーション起動時にDBへの接続を自動で試みます。しかし、接続設定が誤っていたり、DBサーバーが起動していなかったりすると、Spring DB接続失敗としてエラーが発生します。

では、具体的にどのような原因で接続に失敗するのか、次のセクションで詳しく見ていきましょう。

2. SpringでDB接続に失敗する主な原因

SpringでDB接続エラーが発生する場面はよくあります。以下は代表的な原因と対策です。初心者が特につまずきやすいポイントなので、丁寧に確認していきましょう。

① 接続URLの誤り

URLに誤りがあると、SQLエラーとして「Communications link failure」や「Unknown database」などのエラーメッセージが表示されます。

例えば、ポート番号が違ったり、存在しないDB名を指定しているケースです。


spring.datasource.url=jdbc:mysql://localhost:3307/sampledb

このようにポート番号3306ではなく3307になっていると、接続できません。

② ユーザー名やパスワードのミス

ログイン情報が正しくない場合、次のようなエラーメッセージが表示されることがあります。


Access denied for user 'root'@'localhost'

このエラーが出た場合は、ユーザー名・パスワードをもう一度確認してみましょう。

③ JDBCドライバが不足している

JDBCドライバが依存関係に含まれていないと、以下のようなエラーが出ることがあります。


Cannot load driver class: com.mysql.cj.jdbc.Driver

Pleiadesの「依存関係の追加」機能からmysql-connector-jを追加しましょう。また、Gradleの場合は以下のようにbuild.gradleへ追記してもOKです。


dependencies {
    implementation 'mysql:mysql-connector-java:8.0.33'
}

④ DBサーバーが起動していない

意外と見落としがちなのが、DBサーバーそのものが停止しているパターンです。

MySQLなどをローカルで使用している場合は、XAMPPやサービスでMySQLが起動中であることを確認してください。

⑤ DBが自動起動に対応していない

Spring Bootは初期状態で「DBが存在しなければ作成する」という設定ではありません。DBの作成を自動で行いたい場合は、spring.jpa.hibernate.ddl-autoなどの設定を見直す必要があります。


spring.jpa.hibernate.ddl-auto=update

ただし、本番環境でこの設定を使うのは注意が必要です。

これらの原因と対策を把握しておけば、Spring DB接続失敗に直面したときでも落ち着いて対応できます。次回は、SQLエラーやエラーメッセージの表示方法についてさらに深掘りしていきます。

3. SpringでSQLエラーが発生する場面と例

新人

「DB接続はうまくいったんですけど、今度はSQL文のエラーが出ました…。よくわからないメッセージがたくさん表示されて困ってます。」

先輩

「それはSQL構文ミスや、テーブル名の指定ミスの可能性があるね。Springでは、SQLの実行時にもいろいろな例外が発生するから、原因をしっかり見極めることが大切だよ。」

Spring SQLエラーは、SQL文のミスやデータベース側の問題によってよく発生します。特に初心者が書いたSQL文では、次のような原因が多いです。

① SQLの構文ミス

SQL文の文法が間違っている場合、MySQLやH2などのDB側からエラーが返されます。Springではこの例外をorg.springframework.dao.DataAccessExceptionなどでラップして扱います。

以下は、構文ミスの例です。


String sql = "SELEC * FROM users"; // 「SELECT」が「SELEC」になっている
jdbcTemplate.queryForList(sql);

このようなミスをすると、次のようなSQLエラーが発生します。


Caused by: java.sql.SQLSyntaxErrorException: You have an error in your SQL syntax

② 存在しないテーブルやカラムの参照

指定したテーブル名やカラム名が存在しない場合にも、SQLエラーが発生します。例えば、membersというテーブルを指定したつもりが、実際にはusersというテーブルしか存在しない場合です。


String sql = "SELECT * FROM members";
jdbcTemplate.queryForList(sql);

このような場合、以下のようなエラーメッセージになります。


java.sql.SQLSyntaxErrorException: Table 'sampledb.members' doesn't exist

このエラーを見て、membersというテーブルがDBにないことに気づければ、すぐに修正できます。

③ SQL実行に必要なパラメータの不足

PreparedStatementやNamedParameterJdbcTemplateを使用している場合、必要なパラメータを指定し忘れると例外になります。


String sql = "SELECT * FROM users WHERE id = :id";
MapSqlParameterSource params = new MapSqlParameterSource(); // id未指定
namedParameterJdbcTemplate.queryForList(sql, params);

このようなケースでは、パラメータが足りないという例外になります。


java.lang.IllegalArgumentException: Parameter 'id' is not present

このようなパターンも初心者がよく引っかかるポイントです。

4. SQLエラー時のメッセージの確認方法

新人

「エラーは出てるんですが、ログが長すぎてどこを見ればいいのか分かりません…。」

先輩

「それなら、まずはスタックトレースの中で「Caused by」や「Exception」の行に注目してみよう。SQLエラーの詳細がその付近に書かれていることが多いよ。」

Springアプリケーションでは、エラーが発生すると詳細なログがPleiadesの「コンソール」画面に表示されます。この中で重要なのが、Caused byやExceptionと記載された行です。

① スタックトレースから原因を読み取る

例えば、以下のようなスタックトレースが出力されたとします。


org.springframework.dao.DataAccessResourceFailureException: Failed to execute SQL script
...
Caused by: java.sql.SQLSyntaxErrorException: Table 'sampledb.userss' doesn't exist

この場合、注目すべきは「Caused by」の行です。userssというスペルミスにより、DB例外が発生していることがわかります。

② Pleiadesのログ設定を活用する

Pleiadesでは、標準でエラーログが表示されますが、設定によって出力レベルを変更できます。application.propertiesに次の設定を加えると、SQLログがより詳細に確認できます。


logging.level.org.springframework.jdbc.core.JdbcTemplate=DEBUG
logging.level.org.springframework.jdbc.datasource=DEBUG

これにより、実行されるSQL文やパラメータの中身がログに表示されるようになります。

③ SQLエラーとDB例外の関係

SQLエラーは通常、DBが返すエラーですが、Springではそれらを独自の例外に変換して扱います。代表的な例外は以下のとおりです。

DataAccessException（全般的なデータアクセス例外）
BadSqlGrammarException（構文エラー）
EmptyResultDataAccessException（結果が空）

それぞれの例外には、エラーメッセージの表示やログ出力に工夫を加えることで、デバッグがしやすくなります。エラー画面に直接表示したい場合は、@ControllerAdviceなどを使って独自のエラーハンドリングを構築することも可能です。

SpringでSQLエラーが発生したときは、まずログをしっかり読み、メッセージの意味を理解することが重要です。初心者でもポイントを押さえれば、原因を特定して素早く解決できるようになります。

5. 独自エラーページでDBエラーを扱う方法

新人

「Springで発生したSQLエラーを、そのままブラウザに表示させるのはちょっと不安です。独自のエラーページって作れますか？」

先輩

「もちろん作れるよ！独自エラー画面を作れば、ユーザーにとっても見やすくなるし、セキュリティ面でも安心だね。Thymeleafで簡単に実装できるよ。」

Spring DBエラー画面を独自に表示したい場合、error.htmlを作成するだけで、Spring Bootが自動的にそのテンプレートを表示してくれます。

① templates/error.htmlの作成

まずは、src/main/resources/templatesにerror.htmlというファイルを作成します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>エラー発生</title>
</head>
<body>
<h1>システムエラーが発生しました</h1>
<p th:text="${status}"></p>
<p th:text="${error}"></p>
<p th:text="${message}"></p>
<p th:text="${timestamp}"></p>
<p th:text="${path}"></p>
</body>
</html>

これにより、DB接続エラーやSQLエラーが発生した際に、独自エラーページの作り方としてブラウザ上に優しいメッセージを表示できます。

② より細かく制御したい場合：@ControllerAdvice

より詳細にエラーごとにページを分けたい場合は、@ControllerAdviceを使います。


@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(DataAccessException.class)
    public String handleDatabaseError(Model model, Exception ex) {
        model.addAttribute("message", "データベース処理中にエラーが発生しました。");
        model.addAttribute("error", ex.getMessage());
        return "db-error"; // db-error.html を表示
    }
}

そして、db-error.htmlをtemplates配下に作成します。

6. DB接続失敗やSQLエラーの再発防止策

新人

「なるほど、エラー画面も表示できました！でも、そもそもエラーが起きないようにするにはどうすればいいですか？」

先輩

「いい質問だね。開発だけでなく運用も意識することが、再発防止につながるよ。具体的にはこんな対策があるよ。」

① 環境変数で接続情報を管理する

application.propertiesに接続情報を直接書くと、誤ってコミットしてしまう恐れがあります。環境変数や.envファイルを使って分離しましょう。


spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASS}

② DBの死活監視を導入する

アプリ起動時だけでなく、運用中にもDBが落ちていないかを監視するツールを導入しましょう。監視対象として、ポート・接続応答・CPU負荷などを定期確認すると良いです。

③ 再試行（リトライ）処理を組み込む

一時的な通信エラーなどに備えて、SQLエラー対策として再試行処理（リトライ）を導入するのも有効です。Spring Retryを使えば、特定の例外に対して自動で再実行が可能になります。


@Retryable(value = { SQLException.class }, maxAttempts = 3)
public void accessDb() {
    // DBアクセス処理
}

7. DB接続やSQLエラー対応のポイントを整理

新人

「今日の内容、めちゃくちゃ勉強になりました！SQLエラーの見方や、Spring DBエラー画面の作り方もよく分かりました！」

先輩

「よかった。DBまわりのエラーって慣れないと焦っちゃうけど、ポイントを押さえれば怖くないよ。」

今回の記事では、Springで発生するDB接続失敗やSQLエラーについて、具体例を交えながら詳しく解説しました。最後に対応ポイントをおさらいしておきましょう。

接続URL・ユーザー名・パスワード・JDBCドライバを必ず確認する
SQLエラーは文法・テーブル名・パラメータ不足などが原因になりやすい
エラーメッセージはCaused byやExceptionの行を中心に読む
error.htmlや@ControllerAdviceで独自のエラー画面を用意する
環境変数やリトライ処理など、再発防止にも意識を向ける

Spring DBエラーは、正しく対応すれば初心者でも十分に扱えます。ぜひ本記事を参考に、実務でも自信を持って対応できるようになってください。