How to Use Soft Deletes With Hibernate and Spring Data
Implement soft deletes with Hibernate: the @SoftDelete annotation, filtering deleted rows, restoring, unique constraints and when a real delete is better.

A soft delete keeps the row and marks it as deleted. Users cannot see it any more, the data is still there to restore, audit or report on, and the delete code in your application never loses anything. Since Hibernate 6.4 the framework does this for you with one annotation, and it handles the part that used to be error-prone, which is adding the filter to every query. This post shows the annotation, what it does to SQL, where it leaks (unique constraints, relationships and restore), and when a real delete is the better answer. It uses Hibernate 7 and Spring Boot 4 on JDK 25.
The annotation
@Entity
@SoftDelete
public class Customer {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true)
private String email;
private String name;
}@SoftDelete adds a boolean column to the table, named deleted by default, and changes the behaviour of the entity in three ways. Calling repository.delete(customer) runs update customer set deleted = true where id = ? and deleted = false instead of a delete. Every query, including findById, findAll, derived queries and JPQL, gets and deleted = false added. And the row stays in the table.
The strategy and column are configurable. @SoftDelete(strategy = SoftDeleteType.ACTIVE) stores active with the meaning inverted, which some teams prefer because a missing column reads as "active". columnName renames the column. If you want a timestamp of deletion rather than a flag, see the alternatives below. Choose between DELETED and ACTIVE once, since changing it means migrating the data.
Before Hibernate 6.4 the same effect needed @SQLDelete and @Where annotations, and @Where is deprecated now. If you maintain old code with them, the behaviour is the same and moving to @SoftDelete removes the hand-written SQL.
Unique constraints
The unique constraint on email is where soft deletes bite. A customer is deleted, then someone signs up again with the same email address. The deleted row still holds the value, and the database rejects the insert with a duplicate key violation, though no active customer has it.
Constrain only the active rows. PostgreSQL and SQL Server support partial indexes:
create unique index uk_customer_email_active
on customer (email) where deleted = false;MySQL has no partial indexes, so the common workaround is a generated column or including the deleted flag in a composite unique index (unique (email, deleted)), which allows one active and one deleted row, and fails if the same email is soft-deleted twice. Neither is perfect, and the right answer depends on the database. Remove the unique = true from the @Column and create the index in a migration, because Hibernate cannot generate a partial one from the annotation alone. Document it, so that a developer who sees the missing unique does not add it back.
Relationships
Soft deletion applies per entity, and the database's foreign keys do not know about it. Deleting a Customer leaves its Order rows pointing at a row that is invisible to queries, so loading an order's customer by lazy association can return nothing and then fail with EntityNotFoundException. Decide what each relationship means:
If orders should vanish with the customer, give Order its own @SoftDelete and cascade the removal with CascadeType.REMOVE. If orders must stay visible, as in accounting, keep them and show the customer through a query that ignores the filter, or copy the display name into the order at purchase time, which is good practice anyway because a customer's name changes.
Test every association you soft delete. Collections filter children that are themselves soft-deleted, while a many-to-one to a deleted parent can break loading. @NotFound(action = NotFoundAction.IGNORE) papers over it and disables lazy loading for that association, so use it with care.
Reading and restoring
The filter applies everywhere, which makes restoration awkward. To see or restore deleted rows, bypass the entity. A native query does it:
@Modifying
@Transactional
@Query(value = "update customer set deleted = false where id = :id", nativeQuery = true)
int restore(@Param("id") Long id);
@Query(value = "select * from customer where deleted = true", nativeQuery = true)
List<Customer> findDeleted();Hibernate applies the filter to JPQL and criteria, not to native SQL. Keep these methods in one repository with a name that makes the bypass obvious, and restrict who can call them. A separate read-only entity mapped to the same table without @SoftDelete is the other approach, useful for an admin screen that lists deleted records.
Alternatives
A deleted_at timestamp tells you when, and null means active. It is more informative than a flag. Check whether your Hibernate release offers a timestamp strategy on @SoftDelete; if not, write the filter yourself with @SQLRestriction("deleted_at is null") and @SQLDelete. If you need the full history of changes, and not only the last deletion, use Envers, which keeps every revision of the entity. Auditing fields record who changed what and when. An event-sourced model keeps every fact by design, see event sourcing. Choose the lightest of these that answers the question you need to answer later.
Testing the behaviour you rely on
Write three tests the day you add the annotation. One saves a customer, deletes it through the repository and asserts that findById returns empty while a native count still sees the row. One deletes a customer and creates another with the same email, which proves the partial index. One loads an order whose customer has been soft-deleted and asserts the page or API still renders, which exercises the relationship rule you chose. These cover the three places where soft deletes fail in production, and they take a few minutes with a real database in a container. H2 does not support partial indexes in the same way, so run them on the database you deploy.
The cost
Soft-deleted rows stay in the table and in its indexes. A table where most rows end up deleted, such as sessions or notifications, grows without bound and slows every query, so archive or purge old rows with a scheduled job, and partition if the volume is high. The flag adds a predicate to every query, which is cheap if indexes include it where it matters. Developers forget the filter in native SQL and reports, and soft-deleted data appears in a total. And data protection law, such as the GDPR's right to erasure, usually requires physical deletion of personal data on request, so a flag is not enough: anonymise or remove the personal columns of deleted rows after a retention period.
When a real delete is better
For data with no value after removal and no audit need, delete it. For personal data under an erasure obligation, delete or anonymise it. The annotation is documented in the SoftDelete Javadoc and the user guide, and the entity basics are in mapping the first entity.


