Soft Delete

In many real-world applications, deleting data permanently from the database is risky and often unacceptable.

Business requirements usually demand data recovery, auditing, history tracking, and compliance.

This is where Soft Delete becomes essential.

What Is Soft Delete?

Soft Delete is a technique where:

• A record is not physically removed from the database
• Instead, it is marked as deleted using:
  • a boolean flag (deleted, is_deleted)
  • or a timestamp (deleted_at)
  • or a status column (ACTIVE, DELETED, BLOCKED)
• Application queries exclude deleted records by default

Soft Delete is when a record is marked as deleted instead of being physically removed from the database, allowing it to be recovered, audited, or kept for compliance purposes.

👉 The data still exists, but behaves as if it were deleted.

Soft Delete vs Hard Delete

Why Soft Delete Is Important

Soft Delete is widely used because it:

• Prevents accidental data loss
• Allows data recovery
• Supports audit logs & legal compliance
• Keeps historical data
• Maintains foreign key integrity
• Helps implement business rules (deactivated users, cancelled orders)

Common Soft Delete Approaches

• Boolean flag is the most commonly used soft delete approach.
• Timestamp is preferred when audit history is required.
• Status column is useful when an entity has multiple lifecycle states.

Basic Soft Delete Entity Design

@Entity
@Table(name = "users")
publicclassUser {

@Id
@GeneratedValue
private Long id;

private String name;

privatebooleandeleted=false;
}

How Soft Delete Works (Flow)

DELETE request
     ↓
UPDATE deleted flag =true
     ↓
Record staysindatabase
     ↓
Application queries ignore it

Problem with Default JPA Delete

userRepository.deleteById(id);

• This performs a hard delete
• Data is permanently removed

Solution 1: Manual Soft Delete

This is the simplest way to implement soft delete in Spring Data JPA.

You manually update a flag instead of deleting the record.

Repository Method (Soft Delete)

@Modifying
@Query("UPDATE User u SET u.deleted = true WHERE u.id = :id")
voidsoftDeleteById(Long id);

What this does:

• Executes an UPDATE query instead of a DELETE
• Marks the record as deleted (deleted = true)
• The row remains in the database

Fetching Only Active (Non-Deleted) Records

List<User>findByDeletedFalse();

What this does:

• Returns only records where deleted = false
• Ensures soft-deleted data is excluded manually

Solution 2: Hibernate Soft Delete

Hibernate provides built-in support for soft delete using annotations.

This approach is automatic, safe, and widely used in real-world Spring Boot applications.

Entity Configuration

@Entity
@Table(name = "users")
@SQLDelete(sql = "UPDATE users SET is_deleted = true WHERE id = ?")
@Where(clause = "is_deleted = false")
publicclassUser {

@Id
@GeneratedValue
private Long id;

private String name;

@Column(name = "is_deleted")
privatebooleandeleted=false;
}

What Each Annotation Does

@SQLDelete

• Overrides the default DELETE SQL
• Converts delete operations into an UPDATE
• Marks the record as deleted instead of removing it

UPDATE usersSET is_deleted=trueWHERE id= ?

@Where

• Automatically adds a filter to all SELECT queries
• Ensures soft-deleted records are excluded by default

WHERE is_deleted=false

What Happens Internally

Using Soft Delete with Spring Data JPA

userRepository.deleteById(id);

Internally Executed SQL

UPDATE usersSET is_deleted=trueWHERE id= ?

• No physical deletion
• Fully transparent to service and controller layers
• No need to change repository methods

Advantages of Hibernate Soft Delete

• Automatic filtering of deleted records
• Eliminates human error (no forgotten conditions)
• Clean repository and service code

Works seamlessly with:

• @EntityGraph
• DTO Projections
• Pagination
• Specifications

When This Approach Is Best

• Medium to large applications
• Enterprise systems
• Audit-compliant projects
• Applications with many queries
• Systems where data safety matters

Fetching Deleted Records (Admin Use Case)

By default, soft-deleted records are hidden because of the @Where clause.

For admin or audit scenarios, you may need to fetch deleted data explicitly.

Option 1: Using Native Query (Simple & Safe)

@Query(value = "SELECT * FROM users WHERE is_deleted = true", nativeQuery = true)
List<User>findDeletedUsers();

Why native query?

• @Where does not apply to native queries
• Allows direct access to deleted records
• Best for admin dashboards and audit reports

Advanced: Soft Delete with Hibernate Filters

Hibernate Filters provide dynamic control over soft delete behavior.

Use this approach when:

• You want to toggle deleted / non-deleted records
• You need both views in the same application

Entity Configuration

@FilterDef(
    name = "deletedFilter",
    parameters = @ParamDef(name = "isDeleted", type = Boolean.class)
)
@Filter(name = "deletedFilter", condition = "is_deleted = :isDeleted")
@Entity
publicclassUser {
// fields
}

Enabling the Filter

Sessionsession= entityManager.unwrap(Session.class);

session.enableFilter("deletedFilter")
       .setParameter("isDeleted",false);

Now:

• false → fetch active records
• true → fetch deleted records

⚠️ Advanced usage — not required for most projects

Soft Delete Using Timestamp (Audit-Friendly Approach)

Instead of a boolean flag, use a timestamp.

Entity Fields

@Column(name = "deleted_at")
private LocalDateTime deletedAt;

Hibernate Configuration

@SQLDelete(sql = "UPDATE users SET deleted_at = NOW() WHERE id = ?")
@Where(clause = "deleted_at IS NULL")

Benefits

• Tracks when data was deleted
• Ideal for compliance and auditing
• Preferred in enterprise systems

⚠️ Slightly more complex than boolean flag

Soft Delete with Relationships

⚠️ Important Limitation

Soft delete does NOT cascade automatically.

What this means:

• Parent entity is soft-deleted
• Child entities remain unchanged unless handled explicitly

How to Handle It

• Apply @SQLDelete on child entities
• OR handle cascade logic in service layer
• OR mark children as deleted explicitly

Soft Delete with @EntityGraph

• @EntityGraph works normally
• @Where filtering still applies
• Soft-deleted child entities are automatically excluded

✔ Safe and recommended combination

✔ No extra configuration required

Soft Delete with DTO Projections

DTO projections automatically respect soft delete because:

• Filtering happens at SQL level
• Deleted rows never reach the projection

Why this is powerful

• Perfect for APIs
• Prevents lazy loading issues
• Improves performance
• Avoids entity exposure

Soft Delete + Auditing

private LocalDateTime deletedAt;
private String deletedBy;

This enables:

• Who deleted the record
• When it was deleted
• Compliance-ready audit trails

Common Pitfalls

• Forgetting @Where → deleted data leaks
• Expecting cascade soft delete automatically
• Overusing soft delete for logs or temporary tables
• Not indexing the delete flag column

Best Practices (Real-World)

• Use @SQLDelete + @Where
• Add index on is_deleted or deleted_at
• Prefer DTO projections for APIs
• Handle cascading deletes explicitly
• Use timestamps for audit-heavy systems
• Avoid soft delete for log or temp tables

Soft Delete vs DTO Projection

Conclusion

• Soft Delete keeps data logically deleted, not physically removed.
• Prevents accidental data loss and supports recovery.
• Implemented cleanly using @SQLDelete + @Where.
• Works seamlessly with repositories, DTOs, and EntityGraphs.
• Essential for scalable, safe, enterprise-grade Spring Boot applications.