SpringのsaveメソッドでINSERTとUPDATEを自動判別！初心者向けガイド

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

新人

「Springのsave()メソッドって、INSERTもUPDATEもできるって聞いたんですけど、どうやって自動で判別してるんですか？」

先輩

「うん、それはJpaRepositoryの便利な機能の一つだね。ID（主キー）の値を見て、INSERTかUPDATEかを自動で判断してるんだよ。」

新人

「えっ！それって、手動で分けなくてもいいんですか？INSERT用とUPDATE用に分けるの面倒だと思ってました。」

先輩

「実はsave()一つで済むんだよ。どう動いてるのか、仕組みを一緒に見ていこうか。」

1. saveメソッドとは何か

Spring FrameworkのSpring Data JPAでは、JpaRepositoryというインタフェースを使ってデータベース操作を簡単に行うことができます。

Spring saveメソッドは、エンティティをデータベースに保存するための主要なメソッドです。このメソッドは、エンティティの状態に応じてINSERT（新規追加）とUPDATE（既存更新）を自動で使い分けてくれます。

つまり、save()を1つ書くだけで、INSERTかUPDATEかを自動で判定してくれる、非常に便利な仕組みです。

2. INSERTとUPDATEの違いと基本動作

Springのsave()メソッドは、次のようにID（主キー）を基準に動作を自動判別します。

INSERT: エンティティのIDがnull、またはデータベースに存在しない場合
UPDATE: エンティティのIDが存在し、かつデータベースに既にレコードが存在している場合

たとえば、次のようなUserエンティティがあるとします。


@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String username;
    private String email;

    // getter・setterは省略
}

このUserエンティティを保存するために、JpaRepositoryを継承したリポジトリインタフェースを作成します。


public interface UserRepository extends JpaRepository<User, Long> {
}

そして、コントローラクラスでは以下のように使います。


@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @PostMapping("/user/register")
    public String register(@RequestParam String username, @RequestParam String email) {
        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        userRepository.save(user); // IDがnull → INSERTされる
        return "register_success";
    }

    @PostMapping("/user/update")
    public String update(@RequestParam Long id, @RequestParam String username) {
        Optional<User> optionalUser = userRepository.findById(id);
        if (optionalUser.isPresent()) {
            User user = optionalUser.get();
            user.setUsername(username);
            userRepository.save(user); // IDが存在 → UPDATEされる
        }
        return "update_success";
    }
}

このように、INSERT UPDATE 自動判別がされることで、if文などで処理を分ける必要がありません。

3. 開発環境の前提説明（PleiadesとGradle）

この記事では、以下の環境でSpringアプリケーションを構築することを前提としています。

IDE: Pleiades（日本語化されたEclipse）
ビルドツール: Gradle（Mavenは使用しません）
コントローラ: @Controllerを使用（@RestControllerは使わない）
依存関係の追加: PleiadesのSpringプロジェクト作成画面から必要なライブラリにチェックを入れる

プロジェクト作成後、build.gradleに以下のような依存関係が自動で追加されていることを確認しましょう。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'com.h2database:h2'
}

また、application.propertiesでデータベース接続の設定を行います。


spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=update
spring.h2.console.enabled=true

この設定により、アプリケーション起動時に自動でテーブルが作成され、Spring saveメソッドをすぐに試すことができます。

4. saveメソッドでINSERT処理を行う方法

Spring save INSERTの処理は非常にシンプルで、エンティティのID（主キー）がnullであることが条件です。Spring Data JPAは、IDが未設定の場合、それを新規データとして扱い、INSERT文を実行します。

たとえば、ユーザーを新規登録する際に、IDをセットしない状態でsave()を呼び出すと、INSERTになります。

以下の例では、ユーザー名とメールアドレスを登録する画面を想定しています。


@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @PostMapping("/user/create")
    public String createUser(@RequestParam String username, @RequestParam String email) {
        User user = new User(); // IDはnullのまま
        user.setUsername(username);
        user.setEmail(email);
        userRepository.save(user); // INSERTされる
        return "user_created";
    }
}

このように、save INSERTの条件は非常に明確で、「IDが設定されていないこと」がポイントです。初心者が混乱しやすい点としては、IDがnullである限り、自動的にINSERTされるというルールをしっかり理解することが大切です。

また、IDは通常、@GeneratedValueで自動生成されるため、明示的に設定する必要はありません。PleiadesでSpringプロジェクトを作成した場合も、このアノテーションはデフォルトで使われるケースが多いです。

5. saveメソッドでUPDATE処理を行う方法

save UPDATE 違いを理解するには、すでにデータベースに存在しているエンティティを更新する場合の仕組みを知る必要があります。

UPDATEの場合は、エンティティのIDが存在し、かつそのIDに対応するレコードがデータベースに存在している必要があります。このとき、save()はUPDATE文を発行してくれます。

以下は、既存ユーザーの名前を変更する例です。


@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @PostMapping("/user/change")
    public String updateUser(@RequestParam Long id, @RequestParam String username) {
        Optional<User> optionalUser = userRepository.findById(id);
        if (optionalUser.isPresent()) {
            User user = optionalUser.get(); // 既存データ取得
            user.setUsername(username);     // 値を変更
            userRepository.save(user);      // UPDATEされる
        }
        return "user_updated";
    }
}

このように、IDが存在し、かつデータベースに同じIDのレコードがある場合は、自動的にsave()がUPDATE処理を行います。

注意点として、存在しないIDを指定してsave()を実行した場合、エラーになることはなく、新しいレコード（INSERT）が作成されてしまうこともあります。これを避けるためにも、findById()で事前に存在確認をするのが安全です。

このパターンは、SpringのJpaRepositoryを使ったフォーム入力後のデータ更新処理で頻繁に登場します。

6. 主キー（ID）による判別の仕組みと注意点

ID 自動判定はSpring Data JPAのsave()メソッドの根幹です。この判定ロジックに基づき、INSERTとUPDATEのどちらを行うかが決まります。

Springは、次のような手順で処理を自動で判断します：

エンティティのIDがnull → INSERT処理
IDが存在する → データベースにIDが一致する行を検索
存在すればUPDATE、存在しなければINSERT（ただし、ID手動設定時は要注意）

初心者が間違いやすい点は、「IDがあるからといって、必ずUPDATEになるわけではない」という点です。IDが手動で設定されていても、データベースに該当IDのレコードがなければ、INSERTが実行されてしまう可能性があります。

そのため、save()を使うときは以下のような対策が推奨されます：

新規作成時: IDを指定しない
更新時: findById()で存在確認をしてからsave()
ID自動生成: @GeneratedValueを必ず使用

以下は、IDの扱いに注意したエンティティの定義例です。


@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY) // 自動生成によりIDの手動ミスを防ぐ
    private Long id;

    private String username;
    private String email;

    // getter/setter省略
}

Springのsave()メソッドは非常に強力ですが、IDの状態に応じて振る舞いが変わるため、INSERT UPDATE 自動判別の仕組みを理解することが何よりも重要です。

Pleiadesでの開発においても、Gradle環境で簡単に動作確認が可能なので、実際にsave()を使ってINSERTとUPDATEの違いを検証してみるのがおすすめです。

7. よくあるエラーとその解決法

Springのsave()メソッドを使っていて、初心者が最も悩みやすいのが「データが保存されない」「IDがnullのまま」などのトラブルです。ここでは、Spring save エラーとしてよくある例と、その解決法を紹介します。

エラー1：IDがnullのままになり、UPDATEされない

これは、エンティティに@GeneratedValueが正しく付与されていない、あるいはIDを手動でセットしてしまった場合に起こりやすい問題です。


@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

このアノテーションがないと、IDが自動採番されず、常にnullとなり、INSERTやUPDATEが正しく行われません。

エラー2：save()したのにDBに反映されない

これは@Transactionalが適切に使われていない、またはメソッドの中で例外が発生してトランザクションがロールバックされた可能性があります。save()の直後に処理を中断するような例外がないかを確認しましょう。

エラー3：データ更新されず、INSERTされてしまう

これは、save()に渡したエンティティのIDが存在していても、データベースにそのIDのレコードが存在していない場合に発生します。findById()で事前確認することで、意図しないINSERTを防げます。

8. save()を使った実践的なフォーム画面処理例

ここでは、save 実用例として、同じ画面からINSERTとUPDATEの両方を実現するフォーム処理の例を紹介します。

Thymeleafを使用したHTMLテンプレートと、@Controllerによる処理を組み合わせて、登録・更新フォームを一つにまとめる方法を学びましょう。

UserController.java


@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/user/form")
    public String showForm(@RequestParam(required = false) Long id, Model model) {
        User user = (id != null) ? userRepository.findById(id).orElse(new User()) : new User();
        model.addAttribute("user", user);
        return "user_form";
    }

    @PostMapping("/user/save")
    public String saveUser(@ModelAttribute User user) {
        userRepository.save(user); // IDがnullならINSERT、あればUPDATE
        return "redirect:/user/form";
    }
}

user_form.html（Thymeleafテンプレート）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザーフォーム</title>
</head>
<body>
    <form th:action="@{/user/save}" th:object="${user}" method="post">
        <input type="hidden" th:field="*{id}" />
        <div>
            <label>名前:</label>
            <input type="text" th:field="*{username}" />
        </div>
        <div>
            <label>メール:</label>
            <input type="email" th:field="*{email}" />
        </div>
        <div>
            <button type="submit">保存</button>
        </div>
    </form>
</body>
</html>

この構成では、IDがhiddenフィールドに入っているため、既存ユーザーの編集時にはIDが渡され、save()でUPDATEが行われます。新規作成時にはIDがnullとなり、save()でINSERTが実行されます。

このように、フォームを分けることなく、登録・編集を一つの画面で行えるようになるのは、Spring saveメソッドの大きな利点です。