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 部構成です。
- 触って学ぶ DB アクセス・トランザクション: 注文 API を作り、CRUD と途中失敗を体験するハンズオン。
- 座学で学ぶ DB アクセス・トランザクション: 各層の責務、SQL の扱い、トランザクションの仕組みを整理する座学。
触って学ぶ DB アクセス・トランザクション
題材とする注文 API
注文のヘッダーと明細を別のテーブルに保存します。
最初はヘッダーだけで CRUD を実装し、その後、ヘッダーと明細をまとめて登録する処理を追加します。
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 のあるディレクトリで起動します。
別のターミナルで次を実行します。コマンドは 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 は欠番になる場合があります。連番であることを成功判定に使わないでください。
練習
- 数量の制約として
@Positive を追加する。数量 0 の応答が 400 となり、SQL は実行されないことを確認する。
- 入力検証を通過した後にも起きる失敗を考える。DB 接続断や、一意制約違反などが例になる。
- 成功時と失敗時に、ヘッダーと明細の件数を検証する統合テストを作る。
テストでは Spring から注入された Service を呼びます。
テストメソッドに @Transactional を付けると、そのトランザクションの影響で Service の設定漏れを見逃す場合があります。
Service の境界を確認するテストは、テスト側のトランザクションで包まずに実行しましょう。
練習で追加した @Positive は、演習を終えたら外してください。
DB を含む統合テスト入門 では、数量 0 のリクエストを明細の INSERT まで通し、DB の CHECK 制約で失敗させます。
座学で学ぶ DB アクセス・トランザクション
Controller / Service / Mapper の責務
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 応答に変換する方法を学びます。
参考資料