> 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.

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

## 講義の区切り

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

## 概要

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

## 対象読者

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

## 事前準備と到達目標

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

[Spring Initializr](https://start.spring.io/) で 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 /orders`           | 201 と登録した注文         |
| 注文を取得    | `GET /orders/{id}`       | 200 と注文、存在しなければ 404 |
| 注文名を変更   | `PUT /orders/{id}`       | 204、存在しなければ 404     |
| 注文を削除    | `DELETE /orders/{id}`    | 204、存在しなければ 404     |
| 注文と明細を登録 | `POST /orders/with-item` | 201 と登録した注文         |

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

### 依存関係と DB の設定

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

```xml title="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 の対応表](https://mybatis.org/spring-boot-starter/mybatis-spring-boot-autoconfigure/) を参照できます。

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

```yaml title="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` を作成します。

```sql title="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 マイグレーション入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/DBマイグレーション入門.md) を参照してください。
このプロジェクトに Flyway は追加しません。

### DTO と DB の行を表すクラス

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

```java title="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;
  }
}
```

```java title="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) {}
```

```java title="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 の対応は、次のようにアノテーションで書きます。

```java title="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 の作成

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

```java title="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 の作成

```java title="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
./mvnw spring-boot:run
```

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

```bash
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 の明細を送ります。

```bash
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 を実行してください。

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

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

### トランザクションを追加

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

```java title="トランザクションの import"
import org.springframework.transaction.annotation.Transactional;
```

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

```java title="トランザクション付きメソッド"
@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 件を順に送ります。

```bash
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 コンソールに接続し直して、次を確認します。

```sql
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 を含む統合テスト入門](/Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/DBを含む統合テスト入門.md) では、数量 0 のリクエストを明細の INSERT まで通し、DB の CHECK 制約で失敗させます。

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

### Controller / Service / Mapper の責務

| 層          | 主な責務               | 今回の例                   |
| ---------- | ------------------ | ---------------------- |
| Controller | HTTP の入出力とステータスの決定 | JSON の受け取り、201・404 の返却 |
| Service    | 業務処理と処理単位の決定       | 注文と明細を一緒に登録            |
| Mapper     | SQL と 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 とトランザクションマネージャーが必要です。

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

```java
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` は、呼び出し方と例外の伝わり方にも依存する。

次は [例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) で、失敗を利用者向けの HTTP 応答に変換する方法を学びます。

## 参考資料

- [MyBatis Starter](https://mybatis.org/spring-boot-starter/mybatis-spring-boot-autoconfigure/)
- [MyBatis-Spring のトランザクション](https://mybatis.org/spring/transactions.html)
- [Spring の @Transactional](https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/annotations.html)
- [Spring のロールバック条件](https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/rolling-back.html)
