For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/DBアクセス・トランザクション入門.md.

Spring Boot DB アクセス・トランザクション入門

講義の区切り

基本編の目安は 120 分です。終了条件は「CRUD と登録失敗時のロールバックを確認」です。 発展内容は、座学のプロキシ境界です。削除途中の失敗とロールバックは DB を含む統合テスト入門 で検証します。 準備と前後の章は 学習ガイド で確認できます。

概要

MyBatis でデータの登録・取得・更新・削除を実装し、複数の SQL をまとめて成功または取り消しにする方法を学びます。 途中で失敗しても一部のデータだけが残らないように、業務処理の単位でトランザクションを設定します。

対象読者

  • Controller / Service を使った API を作成できる方
  • SQL を実行する場所と、業務処理を実装する場所を整理したい方
  • @Transactional の効果を DB の状態で確認したい方

事前準備と到達目標

Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。 SQL の SELECT / INSERT / UPDATE / DELETE と、Java の例外の基本を前提にします。 プロジェクト作成・デプロイ入門 を先に進めてください。

Spring Initializr で Maven / Java / Jar / YAML を選び、新しいプロジェクトを作成します。 パッケージ名は dev.mikoto2000.springboot.database にします。 Spring Web、Validation、JDBC API、H2 Database を追加し、MyBatis の依存関係を後から追加します。 この教材では Lombok と Spring Security は使いません。

生成直後のビルドで Non-resolvable parent POM が出た場合は、pom.xml の <parent> にある Spring Boot のバージョンを確認します。 末尾に .RELEASE が付き、そのバージョンが Maven Central に見つからない場合は、4.0.9.RELEASE を 4.0.9 にするように、公開されている版の表記に合わせます。

完了時には、CRUD の SQL を Mapper に配置し、Service にトランザクション境界を定義できることを目指します。 成功時と失敗時の違いを、HTTP 応答と DB の両方で説明できるようにしましょう。

この資料の構成

この資料は 2 部構成です。

  1. 触って学ぶ DB アクセス・トランザクション: 注文 API を作り、CRUD と途中失敗を体験するハンズオン。
  2. 座学で学ぶ DB アクセス・トランザクション: 各層の責務、SQL の扱い、トランザクションの仕組みを整理する座学。
触って学ぶ(ハンズオン)座学で学ぶ(理論)
Mapper と CRUD API の作成Controller / Service / Mapper の責務
パラメーター付き SQLバインド変数と更新件数
注文と明細の保存トランザクションと整合性
途中失敗とロールバックロールバック条件と例外の扱い
@Transactional の追加Spring のプロキシとトランザクション境界

触って学ぶ DB アクセス・トランザクション

題材とする注文 API

注文のヘッダーと明細を別のテーブルに保存します。 最初はヘッダーだけで CRUD を実装し、その後、ヘッダーと明細をまとめて登録する処理を追加します。

操作エンドポイント成功時
注文を登録POST /orders201 と登録した注文
注文を取得GET /orders/{id}200 と注文、存在しなければ 404
注文名を変更PUT /orders/{id}204、存在しなければ 404
注文を削除DELETE /orders/{id}204、存在しなければ 404
注文と明細を登録POST /orders/with-item201 と登録した注文

with-item は複数更新を比較する演習用のエンドポイントです。 最終段階の削除では、明細も先に削除します。

依存関係と DB の設定

pom.xml の dependencies に次を追加します。 Initializr で MyBatis Framework を選んだ場合は、同じ依存関係を重複させずにバージョンを確認してください。 spring-boot-h2console は Initializr で H2 Database を選ぶと自動で追加されるため、すでに含まれているはずです。含まれていない場合だけ追加してください。

MyBatis の依存関係
<dependency>
  <groupId>org.mybatis.spring.boot</groupId>
  <artifactId>mybatis-spring-boot-starter</artifactId>
  <version>4.0.0</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-h2console</artifactId>
</dependency>

MyBatis Starter 4.0 系は Spring Boot 4.0 以降に対応しています。 MyBatis Starter の対応表 を参照できます。

src/main/resources/application.yaml を次の内容にします。

application.yaml
spring:
  datasource:
    url: jdbc:h2:mem:orders;DB_CLOSE_DELAY=-1
    username: sa
    password:
  sql:
    init:
      mode: always
  h2:
    console:
      enabled: true

H2 コンソールはローカル演習で DB の状態を確認するために使います。 この DB はメモリー上にあるため、アプリを停止するとデータが失われます。 DB_CLOSE_DELAY=-1 は、最後の接続を閉じても同じ JVM の稼働中は DB を保持する設定です。

src/main/resources/schema.sql を作成します。

schema.sql
CREATE TABLE purchase_order (
  id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  customer_name VARCHAR(100) NOT NULL
);

CREATE TABLE order_item (
  id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  order_id BIGINT NOT NULL,
  product_name VARCHAR(100) NOT NULL,
  quantity INTEGER NOT NULL CHECK (quantity > 0),
  FOREIGN KEY (order_id) REFERENCES purchase_order(id)
);

明細の数量には DB の CHECK 制約を付けます。 後の演習では、この制約に違反して 2 件目の SQL を失敗させます。 今回は SQL 初期化を使います。変更履歴を管理する方法は DB マイグレーション入門 を参照してください。 このプロジェクトに Flyway は追加しません。

DTO と DB の行を表すクラス

以下の Java ファイルは src/main/java/dev/mikoto2000/springboot/database の下に配置します。 Initializr が生成した @SpringBootApplication のクラスも、このパッケージに置きます。

Order.java
package dev.mikoto2000.springboot.database;

public class Order {
  private Long id;
  private String customerName;

  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }
  public String getCustomerName() { return customerName; }
  public void setCustomerName(String customerName) {
    this.customerName = customerName;
  }
}
OrderRequest.java
package dev.mikoto2000.springboot.database;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record OrderRequest(
    @NotBlank @Size(max = 100) String customerName) {}
OrderWithItemRequest.java
package dev.mikoto2000.springboot.database;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

public record OrderWithItemRequest(
    @NotBlank @Size(max = 100) String customerName,
    @NotBlank @Size(max = 100) String productName,
    @NotNull Integer quantity) {}

Order は Mapper が取得した行と、自動採番された ID を受け取ります。 リクエストは record にして、受け取る項目を明示しています。 数量に @Positive を付けていないのは、DB で失敗するケースを体験するためです。 通常の API では、入力の正数チェックも付けます。

Mapper の作成

MyBatis は、インターフェースのメソッド呼び出しを SQL 実行に変換するライブラリーです。@Mapper を付けたインターフェースは、MyBatis が実装を自動生成して Spring の Bean として登録します。実装クラスを書かなくても、Service に OrderMapper を注入して呼び出せます。メソッドと SQL の対応は、次のようにアノテーションで書きます。

OrderMapper.java
package dev.mikoto2000.springboot.database;

import org.apache.ibatis.annotations.Delete;
import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Options;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;

@Mapper
public interface OrderMapper {
  @Insert("INSERT INTO purchase_order(customer_name) VALUES(#{customerName})")
  @Options(useGeneratedKeys = true, keyProperty = "id")
  int insert(Order order);

  @Select("SELECT id, customer_name AS customerName FROM purchase_order WHERE id = #{id}")
  Order findById(@Param("id") long id);

  @Update("UPDATE purchase_order SET customer_name = #{name} WHERE id = #{id}")
  int updateName(@Param("id") long id, @Param("name") String name);

  @Delete("DELETE FROM purchase_order WHERE id = #{id}")
  int delete(@Param("id") long id);

  @Insert("""
      INSERT INTO order_item(order_id, product_name, quantity)
      VALUES(#{orderId}, #{productName}, #{quantity})
      """)
  int insertItem(@Param("orderId") long orderId,
      @Param("productName") String productName,
      @Param("quantity") int quantity);

  @Delete("DELETE FROM order_item WHERE order_id = #{orderId}")
  int deleteItems(@Param("orderId") long orderId);
}

#{...} は値を SQL パラメーターとして渡す記法です。 @Param で、複数の引数と SQL 内の名前を対応付けています。 insert の戻り値は更新件数です。生成された ID は Order.id に設定されます。

Service の作成

まず、トランザクションを付けない状態で作成します。

OrderService.java
package dev.mikoto2000.springboot.database;

import org.springframework.stereotype.Service;

@Service
public class OrderService {
  private final OrderMapper mapper;

  public OrderService(OrderMapper mapper) {
    this.mapper = mapper;
  }

  public Order create(OrderRequest request) {
    Order order = new Order();
    order.setCustomerName(request.customerName());
    mapper.insert(order);
    return order;
  }

  public Order find(long id) {
    return mapper.findById(id);
  }

  public boolean update(long id, OrderRequest request) {
    return mapper.updateName(id, request.customerName()) == 1;
  }

  public boolean delete(long id) {
    mapper.deleteItems(id);
    return mapper.delete(id) == 1;
  }

  public Order createWithItem(OrderWithItemRequest request) {
    Order order = new Order();
    order.setCustomerName(request.customerName());
    mapper.insert(order);
    mapper.insertItem(order.getId(), request.productName(), request.quantity());
    return order;
  }
}

Controller の作成

OrderController.java
package dev.mikoto2000.springboot.database;

import java.net.URI;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/orders")
public class OrderController {
  private final OrderService service;

  public OrderController(OrderService service) {
    this.service = service;
  }

  @PostMapping
  public ResponseEntity<Order> create(@Valid @RequestBody OrderRequest request) {
    Order order = service.create(request);
    return ResponseEntity.created(URI.create("/orders/" + order.getId())).body(order);
  }

  @GetMapping("/{id}")
  public ResponseEntity<Order> find(@PathVariable("id") long id) {
    Order order = service.find(id);
    return order == null ? ResponseEntity.notFound().build() : ResponseEntity.ok(order);
  }

  @PutMapping("/{id}")
  public ResponseEntity<Void> update(@PathVariable("id") long id,
      @Valid @RequestBody OrderRequest request) {
    return service.update(id, request)
        ? ResponseEntity.noContent().build() : ResponseEntity.notFound().build();
  }

  @DeleteMapping("/{id}")
  public ResponseEntity<Void> delete(@PathVariable("id") long id) {
    return service.delete(id)
        ? ResponseEntity.noContent().build() : ResponseEntity.notFound().build();
  }

  @PostMapping("/with-item")
  public ResponseEntity<Order> createWithItem(
      @Valid @RequestBody OrderWithItemRequest request) {
    Order order = service.createWithItem(request);
    return ResponseEntity.created(URI.create("/orders/" + order.getId())).body(order);
  }
}

CRUD の動作確認

pom.xml のあるディレクトリで起動します。

./mvnw spring-boot:run

別のターミナルで次を実行します。コマンドは Bash 用です。 PowerShell では .\mvnw.cmd と curl.exe を使い、JSON はファイルに保存して --data-binary @request.json で送れます。

curl -i -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -d '{"customerName":"Alice"}'
curl -i http://localhost:8080/orders/1
curl -i -X PUT http://localhost:8080/orders/1 -H 'Content-Type: application/json' -d '{"customerName":"Bob"}'
curl -i http://localhost:8080/orders/1
curl -i -X DELETE http://localhost:8080/orders/1
curl -i http://localhost:8080/orders/1

初回起動で、順に 201・200・204・200・204・404 を確認します。 登録時の Location ヘッダーと返却された ID を確認し、ID が 1 以外なら後続の URL を読み替えてください。 更新後の取得では customerName が Bob になります。

途中失敗で注文だけが残ることを確認

数量 0 の明細を送ります。

curl -i -X POST http://localhost:8080/orders/with-item -H 'Content-Type: application/json' -d '{"customerName":"BeforeTransaction","productName":"Book","quantity":0}'

応答は 500 になります。エラー本文の形式は、この教材ではまだ指定していません。 ログには明細の CHECK 制約違反が記録されます。

ブラウザーで http://localhost:8080/h2-console を開きます。 JDBC URL は jdbc:h2:mem:orders、ユーザー名は sa、パスワードは空欄にします。 次の SQL を実行してください。

SELECT * FROM purchase_order WHERE customer_name = 'BeforeTransaction';
SELECT * FROM order_item;

ヘッダーは 1 件、明細は 0 件になります。 Spring のトランザクション外で実行した MyBatis の更新は、呼び出しごとにコミットされます。 明細が失敗しても、先に保存した注文は取り消されません。

トランザクションを追加

アプリを停止し、OrderService.java に次の import を追加します。

トランザクションの import
import org.springframework.transaction.annotation.Transactional;

createWithItem と delete にそれぞれ @Transactional を付けます。 メソッドの本文は変更しません。

トランザクション付きメソッド
@Transactional
public Order createWithItem(OrderWithItemRequest request) {
  Order order = new Order();
  order.setCustomerName(request.customerName());
  mapper.insert(order);
  mapper.insertItem(order.getId(), request.productName(), request.quantity());
  return order;
}

@Transactional
public boolean delete(long id) {
  mapper.deleteItems(id);
  return mapper.delete(id) == 1;
}

再起動すると DB は空になります。同じ DB 内で結果を比較するため、再起動後に次の 2 件を順に送ります。

curl -i -X POST http://localhost:8080/orders/with-item -H 'Content-Type: application/json' -d '{"customerName":"Success","productName":"Book","quantity":2}'
curl -i -X POST http://localhost:8080/orders/with-item -H 'Content-Type: application/json' -d '{"customerName":"AfterTransaction","productName":"Book","quantity":0}'

成功するリクエストは 201、失敗するリクエストは 500 です。 H2 コンソールに接続し直して、次を確認します。

SELECT * FROM purchase_order;
SELECT * FROM order_item;
SELECT COUNT(*) FROM purchase_order WHERE customer_name = 'AfterTransaction';

Success のヘッダーと明細が各 1 件あり、AfterTransaction のヘッダーは 0 件です。 今度は明細の失敗により、同じトランザクションのヘッダー登録もロールバックされます。 成功した注文を DELETE し、両テーブルからその注文のデータが消えることも確認しましょう。 ロールバック後の ID は欠番になる場合があります。連番であることを成功判定に使わないでください。

練習

  1. 数量の制約として @Positive を追加する。数量 0 の応答が 400 となり、SQL は実行されないことを確認する。
  2. 入力検証を通過した後にも起きる失敗を考える。DB 接続断や、一意制約違反などが例になる。
  3. 成功時と失敗時に、ヘッダーと明細の件数を検証する統合テストを作る。

テストでは Spring から注入された Service を呼びます。 テストメソッドに @Transactional を付けると、そのトランザクションの影響で Service の設定漏れを見逃す場合があります。 Service の境界を確認するテストは、テスト側のトランザクションで包まずに実行しましょう。

練習で追加した @Positive は、演習を終えたら外してください。 DB を含む統合テスト入門 では、数量 0 のリクエストを明細の INSERT まで通し、DB の CHECK 制約で失敗させます。

座学で学ぶ DB アクセス・トランザクション

Controller / Service / Mapper の責務

層主な責務今回の例
ControllerHTTP の入出力とステータスの決定JSON の受け取り、201・404 の返却
Service業務処理と処理単位の決定注文と明細を一緒に登録
MapperSQL と Java の対応付けINSERT、行の取得、更新件数の返却

Controller に SQL を直接書くと、HTTP の処理とデータ保存の手順が混ざります。 Service に処理の順序を置くことで、HTTP 以外の入口からも同じ業務処理を呼べます。 Mapper は Repository に相当するデータアクセスの役割を担います。

バインド変数と更新件数

#{name} のようなバインド変数は、入力を SQL の値として渡します。 ${name} は文字列置換です。利用者の入力をそのまま埋め込むと SQL インジェクションにつながります。 テーブル名やソート項目を切り替える場合は、許可した候補から選ぶ設計にします。

UPDATE / DELETE の戻り値は、対象の存在確認にも使えます。 SELECT で存在を確認しても、更新までの間に別の処理から削除される可能性があります。 今回のように ID を条件に更新し、更新件数を確認する方法なら、その SQL の実行結果で判断できます。

トランザクションと整合性

トランザクションは、複数の処理をひとまとまりにしてコミットまたはロールバックする仕組みです。 注文だけ保存されて明細がない状態を避けるため、今回は 2 件の INSERT を同じ単位にしました。 削除も、明細削除とヘッダー削除を同じ単位にしています。

用語意味
コミットトランザクションの変更を確定する
ロールバックトランザクションの変更を取り消す
原子性一連の変更が全部成功するか、全部取り消される
整合性制約や業務ルールを満たす状態を保つ
分離性同時実行する処理の影響を、分離レベルに応じて制御する
永続性コミットした結果を保持する

この教材の H2 はメモリー DB なので、プロセス終了後にはデータを保持しません。 トランザクションを使っても、業務ルールや一意制約の設計が不要になるわけではありません。

Spring のプロキシとトランザクション境界

この節は発展内容です。基本編では、ハンズオンで登録途中の失敗がロールバックされることを確認してください。

標準的な設定では、Spring が Service の手前にプロキシを置きます。 Controller からプロキシを通ってメソッドを呼ぶと、処理前にトランザクションを開始し、処理後に確定または取り消します。 MyBatis-Spring は、そのトランザクションに参加して SQL を実行します。 同じ DataSource を使う Mapper とトランザクションマネージャーが必要です。

次のような自己呼び出しは、通常のプロキシを通りません。

public void register(OrderWithItemRequest request) {
  this.createWithItem(request);
}

register にトランザクションがなく、呼び出し先だけに付けても、この呼び出しでは開始されません。 外部から呼ばれる業務処理の入口に付けるか、別の Spring Bean に処理を切り出します。 new OrderService(...) で自分で作ったインスタンスも Spring のプロキシを通りません。

ロールバック条件と例外の扱い

標準設定では、メソッドの外に伝わった RuntimeException と Error がロールバック対象です。 チェック例外を対象にする場合は、@Transactional(rollbackFor = IOException.class) のように指定します。 アプリ全体の設定でルールを変更している場合は、その設定も確認してください。

今回の DB 制約違反は、MyBatis-Spring によって Spring のデータアクセス例外に変換されます。 これは非チェック例外なので、Service の外に伝わるとロールバック対象になります。

例外を catch して正常終了すると、Spring はメソッドが成功したと判断する場合があります。 失敗を握りつぶさず、業務例外へ変換する場合も原因を保持して外に伝えます。 DB 側の状態などによっては、例外を捕捉しても後でコミットに失敗することがあります。 「catch したから確定できる」と考えず、失敗後の継続を明示的に設計してください。

同時更新とトランザクションの範囲

@Transactional を付けただけでは、同時に編集した利用者同士の上書きをすべて防げません。 更新競合には、バージョン列を条件にする楽観ロックや、DB のロックを使う方法があります。 更新件数 0 を「削除済み」と「他の利用者が変更した」に分ける設計も必要になります。

トランザクション内で外部 API を呼ぶと、その応答待ちの間も DB 接続やロックを保持する場合があります。 DB のロールバックは、送信済みメールや外部 API の操作を取り消しません。 まず DB の業務処理を短い単位にまとめ、外部連携には別途、再試行や重複防止を設計します。

@Transactional の既定の伝播は REQUIRED です。 既存のトランザクションがあれば参加し、なければ開始します。 REQUIRES_NEW、分離レベル、複数 DB は発展内容として、必要な場面で公式資料を確認しましょう。

まとめ

  • Mapper に SQL を置き、Service に業務処理の単位を置く。
  • 更新件数と取得結果を使い、処理結果を確認する。
  • 複数の更新をまとめるときは、途中失敗後の DB 状態まで確認する。
  • @Transactional は、呼び出し方と例外の伝わり方にも依存する。

次は 例外処理・エラー応答入門 で、失敗を利用者向けの HTTP 応答に変換する方法を学びます。

参考資料