In Spring Data JPA, the save() method is commonly used to persist or update entities. A frequent misconception is that the same entity instance passed to save() is always the one managed by the persistence context. In reality, this is not always true. Let us delve into understanding how Spring Data JPA’s save() returned instance affects persist and merge behavior.
1. Introduction to the Problem
Developers often write code like this:
userRepository.save(user);
user.setStatus("ACTIVE");
This works in some cases but can lead to subtle bugs in others. The key issue is that save() may return a different instance than the one passed in. Ignoring the returned value can result in changes not being persisted as expected.
1.1 Detached vs. Managed State
In JPA, entities can exist in different states depending on their relationship with the persistence context. A managed entity is one that is currently tracked by the persistence context. Any changes made to a managed entity are automatically detected and synchronized with the database when the transaction commits or the persistence context flushes. On the other hand, a detached entity is no longer associated with the persistence context—this typically happens when the entity has been serialized, the persistence context has been closed, or the entity was created outside of the current transaction. Changes made to a detached entity are not automatically persisted unless the entity is reattached (merged) back into the persistence context. Understanding the distinction between these states is critical for effective use of Spring Data JPA’s save() method, as it decides internally whether to persist a new entity or merge a detached one, and importantly, returns the managed instance to work with.
1.1.1 persist() vs merge()
In JPA, EntityManager.persist() and EntityManager.merge() serve different purposes for managing entity lifecycle states, and understanding their differences is crucial for effective use of Spring Data JPA’s save() method.
persist()is typically used when saving a new entity without an ID; the entity instance passed remains managed after the call.merge()is used when you want to update an existing entity that is detached (for example, received from a client or a previous session). It returns a new managed instance that should be used going forward.
2. Code Example
2.1 Entity
This entity represents a simple user model that will be managed by the JPA persistence context and mapped to a relational database table.
@Entity
@Table(name = "users")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name;
private String status;
// getters and setters
}
The @Entity annotation marks this class as a JPA entity, meaning it will be tracked and managed by the persistence context. The @Table(name = "users") annotation explicitly maps the entity to the users table in the database. The id field is designated as the primary key using @Id, and its value is automatically generated by the database through the GenerationType.IDENTITY strategy, which is commonly used for auto-increment columns. The name and status fields are simple persistent attributes that map directly to table columns. When an instance of this entity is passed to Spring Data JPA’s save() method, the presence or absence of the id value determines whether the entity will be persisted as new or merged as an existing record.
2.2 Repository
This repository interface provides data access operations for the User entity using Spring Data JPA.
public interface UserRepository extends JpaRepository<User, Long> {
}
By extending JpaRepository<User, Long>, this interface automatically inherits a rich set of CRUD and pagination methods without requiring any boilerplate implementation code. Spring Data JPA generates the runtime proxy that handles entity persistence, retrieval, updates, and deletion. The generic parameters specify that the repository manages the User entity type and uses Long as the primary key. The inherited save() method is central to this discussion, as it internally decides whether to call EntityManager.persist() or EntityManager.merge() based on the entity’s identifier and state, and returns the managed instance that must be used for subsequent updates.
2.3 Service
This service layer demonstrates how Spring Data JPA’s save method behaves differently during persist and merge operations and why the returned instance must always be used.
@Service
public class UserService {
private final UserRepository userRepository;
public UserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
@Transactional
public User persistAndUpdate() {
// ----------- PERSIST SCENARIO -----------
User newUser = new User();
newUser.setName("Alice");
newUser.setStatus("NEW");
User persistedUser = userRepository.save(newUser);
// persistedUser is managed
persistedUser.setStatus("CREATED");
// ----------- DETACHED SCENARIO -----------
User detachedUser = new User();
detachedUser.setId(persistedUser.getId());
detachedUser.setName("Alice Updated");
detachedUser.setStatus("UPDATED");
// save() triggers merge()
User managedUser = userRepository.save(detachedUser);
// IMPORTANT: update the returned instance
managedUser.setStatus("ACTIVE");
return managedUser;
}
}
The class is annotated with @Service, indicating that it contains business logic and is managed by the Spring container. The UserRepository is injected through constructor injection, which is the recommended approach for immutability and testability. The @Transactional annotation ensures that all operations within the persistAndUpdate() method execute within a single persistence context. In the first section, a new User entity without an identifier is saved, causing Spring Data JPA to invoke EntityManager.persist(), which makes the same instance managed and allows subsequent updates to be automatically flushed. In the second section, a new User object is created with an existing identifier, making it a detached entity; calling save() in this case triggers EntityManager.merge(), which returns a new managed instance. Only the returned managedUser is tracked by the persistence context, so updating its status to ACTIVE is persisted, while any further changes to the detached instance would be ignored.
2.4 Controller
This REST controller exposes an endpoint to demonstrate the behavior of the save() method and the importance of using its returned instance.
@RestController
@RequestMapping("/users")
public class UserController {
private final UserService userService;
public UserController(UserService userService) {
this.userService = userService;
}
@PostMapping("/demo")
public User demo() {
return userService.persistAndUpdate();
}
}
The class is annotated with @RestController, which marks it as a Spring MVC controller that returns JSON responses by default. It maps HTTP requests under the “/users” path. The UserService is injected via constructor injection to promote clean, testable code. The single POST endpoint “/demo” invokes the persistAndUpdate() method of the service, which handles both persisting a new user and merging a detached user, returning the final managed user entity. This endpoint allows easy testing and verification of how the returned instance from save() is critical for tracking entity changes and ensuring data consistency.
2.5 What Happens Internally
During the first save() call, because the entity has no ID, persist() is used to create a new record, and the returned instance becomes managed and tracked by the persistence context. On the second save() call, where the entity has an ID but is detached, merge() is invoked, which returns a new managed instance representing the updated state. Importantly, only changes made to this returned managed instance will be persisted to the database.
2.5.1.1 Incorrect Pattern (What NOT to Do)
Avoid modifying the detached entity instance after calling save() because such changes will not be tracked or persisted by JPA.
userRepository.save(detachedUser);
detachedUser.setStatus("ACTIVE"); // ignored by JPA
In this example, the detachedUser is passed to save(), which performs a merge operation and returns a new managed instance. However, updating the detached instance’s status afterward has no effect since it is not managed by the persistence context. Consequently, JPA ignores the change, and it will not be saved to the database, potentially causing data inconsistencies.
2.5.1.2 Correct Pattern
To ensure changes are persisted, always use the instance returned by save() and make updates on that managed entity.
User managed = userRepository.save(detachedUser);
managed.setStatus("ACTIVE"); // persisted
In this correct usage, the save() method returns a managed entity instance. By updating the status on this managed instance, the changes are tracked by the persistence context and will be properly flushed to the database at transaction commit, ensuring data consistency.
2.5.1.3 Database Output
select * from users; +----+---------------+--------+ | id | name | status | +----+---------------+--------+ | 1 | Alice Updated | ACTIVE | +----+---------------+--------+
3. Conclusion
The save() method does not guarantee that the entity passed to it becomes managed; in merge scenarios, only the instance returned by save() is tracked by the persistence context, so as a rule of thumb, you should always assign and use the returned value of save() to ensure safe and correct persistence behavior.
