Introduction to Spring Data JPA Auditing
Setting Up a Spring Boot Project with Spring Data JPA
Enabling Auditing in Spring Data JPA
Implementing Auditable Entities
Database Configuration for Auditing Fields
Testing Spring Data JPA Auditing
Using Custom Audit Listeners
Auditing Soft Deletes with Spring Data JPA

1. Introduction to Spring Data JPA Auditing

What is Auditing in Spring Data JPA?

Auditing in Spring Data JPA helps you automatically track and record changes to data in a database. This means you can keep track of things like:

🟠 Who created or changed the data
🟠 When the data was created or changed
🟠 What changes were made (with more advanced setups)

Spring Data JPA makes it easy to do this using annotations, which simplify the process by reducing the need for extra coding effort.

Benefits of Auditing in a Spring Boot Application

🟠 Automatic Metadata Tracking – Automatically records details of who created or updated data, saving time.
🟠 Data Integrity – Ensures a clear record of what was changed and by whom.
🟠 Compliance – Helps you meet legal requirements such as GDPR for tracking data changes.
🟠 Debugging – Allows you to easily find out when and who made changes that caused issues.
🟠 Historical Context – Offers extra information about your data by displaying its history.
🟠 Consistency – Provides uniform auditing for all data across the application.
🟠 Minimal Code – Reduces the need for repetitive code thanks to simple annotations.

Use Cases and Real-World Applications

🔹 User Management Systems

Track creation and modification of user accounts
Monitor updates to important user information

🔹 E-commerce Applications

Record changes to product details and identify the responsible admin
Track changes in order status over time

🔹 Financial Systems

Maintain audit trails for transactions, which is legally required in many areas
Track updates to account information

🔹 Content Management Systems

Display history of content changes
Identify who published or modified content

🔹 Healthcare Applications

Track updates to patient records, crucial for HIPAA compliance
Monitor access to sensitive health data

🔹 Enterprise Applications

Ensure accountability for data changes in multi-user environments
Support investigations into data issues

🔹 Configuration Management

Track changes to system settings
Identify who altered critical settings

🔹 Collaborative Applications

Show document edit history
Attribute contributions in team projects

Auditing in Spring Data JPA is useful for any application where tracking changes, accountability, or legal compliance is important. It is simple to implement, often requiring just a few annotations. Even if it's not the main focus of your application today, enabling auditing can save time and effort later when tracking changes becomes necessary.

2. Setting Up a Spring Boot Project with Spring Data JPA

Dependencies

To get started with Spring Data JPA in a Spring Boot project, you'll need these essential dependencies in your pom.xml (Maven) or build.gradle (Gradle):

Maven (`pom.xml`):

<dependencies>
    <!-- Spring Data JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    
    <!-- Web support (optional but common for REST APIs) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Database driver (choose one based on your DB) -->
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- OR for MySQL -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- OR for PostgreSQL -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- Lombok (optional but recommended for reducing boilerplate) -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Gradle (`build.gradle`):

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    
    // Choose one database
    runtimeOnly 'com.h2database:h2'
    // runtimeOnly 'mysql:mysql-connector-java'
    // runtimeOnly 'org.postgresql:postgresql'
    
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

Configuring a Relational Database

Configure your database in application.properties or application.yml:

H2 Database (in-memory, good for development):

# application.properties
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# JPA properties
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.format_sql=true

MySQL Database:

spring.datasource.url=jdbc:mysql://localhost:3306/your_database
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect

PostgreSQL Database:

spring.datasource.url=jdbc:postgresql://localhost:5432/your_database
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=org.postgresql.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

Creating an Entity Class with JPA

Here's an example of a complete entity class with common JPA annotations:

import javax.persistence.*;
import lombok.*;

@Entity
@Table(name = "products") // Optional - customizes table name
@Getter // Lombok - generates getters
@Setter // Lombok - generates setters
@NoArgsConstructor // Lombok - generates no-args constructor
@AllArgsConstructor // Lombok - generates all-args constructor
@ToString // Lombok - generates toString()
public class Product {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, length = 100)
    private String name;
    
    @Column(nullable = false)
    private Double price;
    
    @Column(length = 500)
    private String description;
    
    @Column(name = "created_at") // Custom column name
    private LocalDateTime createdAt;
    
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
    
    @Enumerated(EnumType.STRING)
    private ProductCategory category;
    
    // Pre-persist and pre-update hooks
    @PrePersist
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
        this.updatedAt = LocalDateTime.now();
    }
    
    @PreUpdate
    protected void onUpdate() {
        this.updatedAt = LocalDateTime.now();
    }
}

// Example enum
enum ProductCategory {
    ELECTRONICS, CLOTHING, BOOKS, FOOD
}

Key JPA Annotations Explained:

@Entity: Marks the class as a JPA entity
@Table: Optional - specifies table details
@Id: Marks the primary key field
@GeneratedValue: Configures how the primary key is generated
@Column: Optional - configures column details
@Enumerated: Specifies how to persist enum values
@PrePersist/@PreUpdate: Callback methods for lifecycle events

With this setup, your Spring Boot application is ready to perform CRUD operations using Spring Data JPA. The entity will be automatically mapped to a database table, and you can create a corresponding repository interface to interact with it.

3. Enabling Auditing in Spring Data JPA

Understanding `@EnableJpaAuditing

The @EnableJpaAuditing annotation is the key to activating Spring Data JPA's auditing features. This annotation should be added to your main application class or a configuration class:

@SpringBootApplication
@EnableJpaAuditing
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

What `@EnableJpaAuditing` does:

Enables the auditing infrastructure
Scans for entities with auditing annotations
Activates automatic population of auditing fields
Sets up the necessary components to track creation and modification dates
Enables user tracking when combined with AuditorAware

Configuring `AuditorAware` to Track User Changes

To track which user made changes (in addition to when changes were made), you need to implement the AuditorAware interface. This tells Spring how to get the current auditor (typically the current user).

Basic Implementation Concept:

public interface AuditorAware<T> {
    Optional<T> getCurrentAuditor();
}

The generic type <T> should match the type of your user identifier (typically String for username or Long for user ID).

Implementing a Custom `AuditorAware`

Here's a complete implementation example that works with Spring Security:

1. First, add the auditing fields to your entity:

@Entity
@EntityListeners(AuditingEntityListener.class) // Required for auditing
public class Product {
    // ... existing fields ...
    
    @CreatedBy
    private String createdBy;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    // ... rest of the entity ...
}

2. Create an `AuditorAware` implementation:

import org.springframework.data.domain.AuditorAware;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import java.util.Optional;

public class SpringSecurityAuditorAware implements AuditorAware<String> {
    
    @Override
    public Optional<String> getCurrentAuditor() {
        // Get the current authentication from Spring Security
        Authentication authentication = 
            SecurityContextHolder.getContext().getAuthentication();
        
        if (authentication == null || !authentication.isAuthenticated()) {
            return Optional.empty();
        }
        
        // Return the username of the currently logged-in user
        return Optional.of(authentication.getName());
    }
}

3. Register the `AuditorAware` bean in your configuration:

@Configuration
public class JpaAuditingConfig {
    
    @Bean
    public AuditorAware<String> auditorAware() {
        return new SpringSecurityAuditorAware();
    }
}

Alternative Implementation (for non-Spring Security applications):

public class SimpleAuditorAware implements AuditorAware<String> {
    
    @Override
    public Optional<String> getCurrentAuditor() {
        // In a real application, you might get this from:
        // - ThreadLocal storage
        // - Session
        // - JWT token
        // - Other security context
        
        // For demo purposes, we'll return a fixed value
        return Optional.of("system_user");
    }
}

Complete Auditing Entity Example

Here's how a fully audited entity might look:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Product {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String name;
    private Double price;
    
    @CreatedDate
    @Column(name = "created_date", updatable = false)
    private LocalDateTime createdDate;
    
    @LastModifiedDate
    @Column(name = "last_modified_date")
    private LocalDateTime lastModifiedDate;
    
    @CreatedBy
    @Column(name = "created_by", updatable = false)
    private String createdBy;
    
    @LastModifiedBy
    @Column(name = "last_modified_by")
    private String lastModifiedBy;
    
    // ... constructors, getters, setters ...
}

Key Auditing Annotations:

@CreatedDate - Automatically sets the creation timestamp
@LastModifiedDate - Updates on each modification
@CreatedBy - Records who created the entity
@LastModifiedBy - Records who last modified the entity
@EntityListeners(AuditingEntityListener.class) - Required on entities to enable auditing

With this setup, your application will automatically:

Set creation and modification timestamps
Track which user created and modified entities
Maintain this information without manual intervention
Provide a complete audit trail for all your JPA entities

The auditing information will be automatically managed whenever you save entities through your Spring Data JPA repositories.

4. Implementing Auditable Entities

Core Auditing Annotations

Spring Data JPA provides four main annotations for implementing auditable entities:

1. `@CreatedDate`

Automatically sets the entity's creation timestamp
Only set once when the entity is first persisted
Typically used with java.time classes or Date

2. `@LastModifiedDate`

Updates automatically on each modification
Tracks the last update timestamp
Useful for versioning and change tracking

3. `@CreatedBy`

Records who created the entity
Requires AuditorAware implementation
Works with String or custom user identifier types

4. `@LastModifiedBy`

Records who last modified the entity
Also requires AuditorAware
Updated on each save operation

Complete Auditable Entity Example

Here's a full implementation of an auditable entity class:

import javax.persistence.*;
import lombok.*;
import org.springframework.data.annotation.*;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;
import java.time.LocalDateTime;

@Entity
@Table(name = "orders")
@EntityListeners(AuditingEntityListener.class) // Required for auditing
@Getter @Setter
@NoArgsConstructor
@ToString
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String productName;
    private Integer quantity;
    private Double totalPrice;
    private String customerEmail;
    
    // Auditing fields
    @CreatedDate
    @Column(name = "created_at", updatable = false)
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
    
    @CreatedBy
    @Column(name = "created_by", updatable = false)
    private String createdBy;
    
    @LastModifiedBy
    @Column(name = "updated_by")
    private String updatedBy;
    
    @Version
    private Long version; // Optimistic locking
    
    // Business constructor (without auditing fields)
    public Order(String productName, Integer quantity, 
                Double totalPrice, String customerEmail) {
        this.productName = productName;
        this.quantity = quantity;
        this.totalPrice = totalPrice;
        this.customerEmail = customerEmail;
    }
}

Key Implementation Details

Entity Listener Requirement:
- @EntityListeners(AuditingEntityListener.class) is mandatory
- This enables the automatic population of auditing fields
Field Configuration:
- Creation fields should be updatable = false
- Use appropriate temporal types (LocalDateTime, Instant, etc.)
- Column names can be customized with @Column
Version Field:
- @Version provides optimistic locking
- Not required for auditing but often used with audited entities
Lombok Annotations:
- Reduce boilerplate code
- @Getter, @Setter, @ToString are commonly used
- Constructor annotations manage object creation

Alternative: Abstract Base Class Approach

For cleaner code across multiple entities, create an abstract auditable class:

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter @Setter
public abstract class AuditableEntity {
    
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdDate;
    
    @LastModifiedDate
    private LocalDateTime lastModifiedDate;
    
    @CreatedBy
    @Column(updatable = false)
    private String createdBy;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    @Version
    private Long version;
}

Then extend it in your entities:

@Entity
public class Product extends AuditableEntity {
    // Product-specific fields
    @Id
    private Long id;
    private String name;
    // ...
}

Database Considerations

The auditing fields will be created in your database tables with these typical SQL types:

Timestamp fields: TIMESTAMP or DATETIME
User fields: VARCHAR (size depends on your user identifier)
Version field: BIGINT

Testing Audited Entities

When testing, you can:

Mock the AuditorAware bean
Verify auditing fields are automatically set
Check that creation fields aren't updated on modifications

Example test snippet:

@Test
public void whenSaveOrder_thenAuditingFieldsPopulated() {
    Order order = new Order("Laptop", 1, 999.99, "test@example.com");
    order = orderRepository.save(order);
    
    assertNotNull(order.getCreatedAt());
    assertNotNull(order.getCreatedBy());
    assertEquals(order.getCreatedAt(), order.getUpdatedAt());
    
    // Modify and save again
    order.setQuantity(2);
    Order updated = orderRepository.save(order);
    
    assertNotEquals(updated.getCreatedAt(), updated.getUpdatedAt());
}

This implementation provides a complete audit trail for your entities with minimal coding effort, automatically tracking both temporal and user-based auditing information.

5. Database Configuration for Auditing Fields

Handling `created_at` and `updated_at` Fields

When implementing auditing fields in your database, there are several approaches to managing created_at and updated_at timestamps:

Database Column Definitions

-- MySQL/PostgreSQL example
CREATE TABLE products (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by VARCHAR(50),
    updated_by VARCHAR(50)
);

-- H2 Database example
CREATE TABLE orders (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    order_number VARCHAR(20) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
);

JPA Entity Configuration

@Column(name = "created_at", nullable = false, updatable = false)
@CreatedDate
private LocalDateTime createdAt;

@Column(name = "updated_at", nullable = false)
@LastModifiedDate
private LocalDateTime updatedAt;

Using Database Triggers vs JPA Auditing

Database Trigger Approach

Pros:

Works regardless of application layer
Consistent across all applications accessing the database
No need for application code changes

Example Trigger (MySQL):

DELIMITER //
CREATE TRIGGER before_product_update
BEFORE UPDATE ON products
FOR EACH ROW
BEGIN
    SET NEW.updated_at = NOW();
END//
DELIMITER ;

Cons:

Less portable across database vendors
Harder to debug and maintain
Doesn't track the "who" (user information)

JPA Auditing Approach

Pros:

Database agnostic
Can track both timestamps and users
Easier to maintain in code
Better integrated with application context

Cons:

Only works through JPA
Requires application layer enforcement

Configuring Automatic Timestamp Updates

Option 1: Pure JPA Approach (Recommended)

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Product {
    // ...
    
    @CreatedDate
    @Column(updatable = false)
    private Instant createdAt;
    
    @LastModifiedDate
    private Instant updatedAt;
    
    // No need for manual callbacks when using auditing
}

Option 2: JPA Callback Methods

@Entity
public class Order {
    // ...
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    
    @PrePersist
    protected void onCreate() {
        createdAt = LocalDateTime.now();
        updatedAt = LocalDateTime.now();
    }
    
    @PreUpdate
    protected void onUpdate() {
        updatedAt = LocalDateTime.now();
    }
}

Option 3: Hybrid Approach (JPA + Database)

@Entity
@Table(name = "customers")
public class Customer {
    @Column(name = "created_at", 
            columnDefinition = "TIMESTAMP DEFAULT CURRENT_TIMESTAMP")
    @CreatedDate
    private LocalDateTime createdAt;
    
    @Column(name = "updated_at", 
            columnDefinition = "TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP")
    @LastModifiedDate
    private LocalDateTime updatedAt;
}

Best Practices for Database Configuration

Column Definitions:

Use TIMESTAMP or DATETIME for temporal fields
Set appropriate precision (e.g., TIMESTAMP(6) for microseconds)
Consider timezone handling (TIMESTAMP WITH TIME ZONE)

2. Nullability Constraints:

@Column(nullable = false, updatable = false)
@CreatedDate
private Instant createdAt;

3. Indexing Auditing Fields:

CREATE INDEX idx_orders_created_at ON orders(created_at);
CREATE INDEX idx_orders_updated_at ON orders(updated_at);

4. Time Zone Considerations:

Store timestamps in UTC:

@CreatedDate
@Column(columnDefinition = "TIMESTAMP WITH TIME ZONE")
private OffsetDateTime createdAt;

5. Database-Specific Optimizations:

PostgreSQL:

CREATE TABLE audit_log (
    -- ...
    created_at TIMESTAMPTZ NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC'),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC')
);

MySQL:

CREATE TABLE products (
    -- ...
    created_at TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    updated_at TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) 
                ON UPDATE CURRENT_TIMESTAMP(6)
);

Migration Script Example

When adding auditing to existing tables:

-- PostgreSQL
ALTER TABLE users 
ADD COLUMN created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
ADD COLUMN updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW();

CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trigger_update_updated_at
BEFORE UPDATE ON users
FOR EACH ROW EXECUTE FUNCTION update_updated_at();

Performance Considerations

Indexing Strategy:
- Add indexes for frequently queried auditing fields
- Consider composite indexes for common filtering patterns
Batch Operations:
- Be aware that auditing hooks may not fire for bulk operations
- Use @Modifying with care in Spring Data JPA
Temporal Precision:
- Balance between precision needs and storage requirements
- Microsecond precision (TIMESTAMP(6)) is often sufficient

This configuration ensures your auditing fields are properly maintained whether changes originate from your application or direct database access, while maintaining data consistency and providing valuable temporal information about your entity lifecycle.

6. Testing Spring Data JPA Auditing

Writing Unit Tests with JUnit 5 and Testcontainers

For comprehensive testing of your auditing implementation, Testcontainers provides an excellent way to test against real databases:

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class ProductAuditingTests {
    
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine");
    
    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }
    
    @Autowired
    private ProductRepository productRepository;
    
    @Test
    void shouldAuditEntityCreation() {
        Product product = new Product("Test Product", 99.99);
        Product saved = productRepository.save(product);
        
        assertNotNull(saved.getId());
        assertNotNull(saved.getCreatedAt());
        assertNotNull(saved.getCreatedBy());
        assertEquals(saved.getCreatedAt(), saved.getUpdatedAt());
    }
}

Mocking AuditorAware for Testing

To test user auditing, create a test configuration that mocks the AuditorAware:

@TestConfiguration
class TestAuditConfig {
    @Bean
    @Primary
    public AuditorAware<String> testAuditorAware() {
        return () -> Optional.of("test-user");
    }
}

@SpringBootTest
@Import(TestAuditConfig.class)
class UserAuditingTests {
    
    @Autowired
    private UserRepository userRepository;
    
    @Test
    void shouldTrackCreatingUser() {
        User user = new User("john.doe@example.com");
        User saved = userRepository.save(user);
        
        assertEquals("test-user", saved.getCreatedBy());
    }
    
    @Test
    void shouldTrackModifyingUser() {
        User user = userRepository.save(new User("original@example.com"));
        
        // Simulate user change
        TestSecurityContext.setCurrentUser("admin-user");
        
        user.setEmail("updated@example.com");
        User updated = userRepository.save(user);
        
        assertEquals("test-user", updated.getCreatedBy());
        assertEquals("admin-user", updated.getLastModifiedBy());
    }
}

Verifying Audit Fields in the Database

For thorough verification, you can query the database directly:

@SpringBootTest
class AuditFieldVerificationTests {
    
    @Autowired
    private JdbcTemplate jdbcTemplate;
    
    @Autowired
    private OrderRepository orderRepository;
    
    @Test
    void shouldPersistAuditFieldsInDatabase() {
        Order order = new Order("Laptop", 1, 1500.00);
        orderRepository.save(order);
        
        Map<String, Object> dbRecord = jdbcTemplate.queryForMap(
            "SELECT created_at, created_by, updated_at FROM orders WHERE id = ?",
            order.getId()
        );
        
        assertNotNull(dbRecord.get("created_at"));
        assertNotNull(dbRecord.get("updated_at"));
        assertEquals(dbRecord.get("created_at"), dbRecord.get("updated_at"));
        assertEquals("system-user", dbRecord.get("created_by"));
    }
}

Comprehensive Test Examples

1. Testing Timestamp Updates

@Test
void shouldUpdateTimestampsOnModification() throws InterruptedException {
    Product product = productRepository.save(new Product("Original", 10.0));
    LocalDateTime initialCreation = product.getCreatedAt();
    LocalDateTime initialUpdate = product.getUpdatedAt();
    
    Thread.sleep(10); // Ensure timestamp difference
    
    product.setPrice(15.0);
    Product updated = productRepository.save(product);
    
    assertEquals(initialCreation, updated.getCreatedAt());
    assertTrue(updated.getUpdatedAt().isAfter(initialUpdate));
}

2. Testing User Context Changes

@Test
void shouldTrackDifferentUsersForCreationAndModification() {
    TestSecurityContext.setCurrentUser("user1");
    Document doc = documentRepository.save(new Document("Draft"));
    
    TestSecurityContext.setCurrentUser("user2");
    doc.setTitle("Final");
    Document updated = documentRepository.save(doc);
    
    assertEquals("user1", updated.getCreatedBy());
    assertEquals("user2", updated.getLastModifiedBy());
}

3. Testing Bulk Operations

@Test
void shouldHandleAuditingInBulkOperations() {
    List<Product> products = List.of(
        new Product("Bulk1", 10.0),
        new Product("Bulk2", 20.0)
    );
    
    productRepository.saveAll(products);
    
    products.forEach(p -> {
        assertNotNull(p.getCreatedAt());
        assertEquals("batch-user", p.getCreatedBy());
    });
}

Integration Test Setup

For complete integration testing with security context:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class AuditingIntegrationTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @Autowired
    private ObjectMapper objectMapper;
    
    @Test
    @WithMockUser(username = "api-user")
    void shouldAuditRestOperations() throws Exception {
        ProductDto dto = new ProductDto("Audited", 99.99);
        
        MvcResult result = mockMvc.perform(post("/api/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(dto)))
            .andExpect(status().isCreated())
            .andReturn();
        
        ProductResponse response = objectMapper.readValue(
            result.getResponse().getContentAsString(),
            ProductResponse.class
        );
        
        assertNotNull(response.createdAt());
        assertNotNull(response.createdBy());
        assertEquals("api-user", response.createdBy());
    }
}

Testing Edge Cases

@Test
void shouldHandleAnonymousUser() {
    TestSecurityContext.clearCurrentUser();
    
    Product product = productRepository.save(new Product("Anon", 0.0));
    
    assertEquals("system", product.getCreatedBy());
    assertNotNull(product.getCreatedAt());
}

@Test
void shouldNotOverwriteManualAuditFields() {
    LocalDateTime manualDate = LocalDateTime.now().minusDays(1);
    Product product = new Product("Manual", 10.0);
    product.setCreatedAt(manualDate);
    product.setCreatedBy("manual-user");
    
    Product saved = productRepository.save(product);
    
    assertEquals(manualDate, saved.getCreatedAt());
    assertEquals("manual-user", saved.getCreatedBy());
}

Performance Testing Considerations

@Test
@Tag("performance")
void shouldNotImpactSavePerformanceSignificantly() {
    int iterations = 1000;
    long start = System.currentTimeMillis();
    
    for (int i = 0; i < iterations; i++) {
        productRepository.save(new Product("PerfTest-" + i, i));
    }
    
    long duration = System.currentTimeMillis() - start;
    double avgTime = (double) duration / iterations;
    
    assertTrue(avgTime < 10, 
        "Average save time should be <10ms, was " + avgTime);
}

This comprehensive testing approach ensures your auditing implementation works correctly under various scenarios while maintaining application performance and data integrity.

7. Using Custom Audit Listeners

Implementing EntityListeners for Custom Auditing

Beyond Spring Data JPA's built-in auditing, you can implement custom EntityListeners to capture more detailed audit information:

Basic Custom EntityListener Example

public class CustomAuditListener {
    
    @PrePersist
    public void prePersist(Object entity) {
        if (entity instanceof Auditable auditable) {
            auditable.setCreatedAt(LocalDateTime.now());
            auditable.setCreatedBy(getCurrentUser());
            auditable.setSystemVersion("v1.0.0");
        }
    }
    
    @PreUpdate
    public void preUpdate(Object entity) {
        if (entity instanceof Auditable auditable) {
            auditable.setUpdatedAt(LocalDateTime.now());
            auditable.setUpdatedBy(getCurrentUser());
        }
    }
    
    private String getCurrentUser() {
        // Implementation to get current user
    }
}

Applying the Listener to an Entity

@Entity
@EntityListeners({AuditingEntityListener.class, CustomAuditListener.class})
public class Product implements Auditable {
    // ... fields and methods ...
}

Capturing Additional Metadata

To capture context information like IP addresses or user agents:

1. Create an Audit Context Holder

@Component
@Scope(value = WebApplicationContext.SCOPE_REQUEST, proxyMode = ScopedProxyMode.TARGET_CLASS)
public class AuditContext {
    private String ipAddress;
    private String userAgent;
    private String deviceInfo;
    
    // Getters and setters
}

2. Populate the Context via Interceptor

@WebFilter("/*")
public class AuditContextFilter implements Filter {
    
    @Autowired
    private AuditContext auditContext;
    
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, 
                        FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        
        auditContext.setIpAddress(httpRequest.getRemoteAddr());
        auditContext.setUserAgent(httpRequest.getHeader("User-Agent"));
        auditContext.setDeviceInfo(extractDeviceInfo(httpRequest));
        
        chain.doFilter(request, response);
    }
}

3. Enhanced EntityListener with Context Data

public class EnhancedAuditListener {
    
    @Autowired
    private AuditContext auditContext;
    
    @PrePersist
    public void prePersist(Object entity) {
        if (entity instanceof EnhancedAuditable auditable) {
            auditable.setCreatedFromIp(auditContext.getIpAddress());
            auditable.setUserAgent(auditContext.getUserAgent());
        }
    }
}

Storing Audit Logs in a Separate Table

For comprehensive audit trails, consider a dedicated audit log table:

1. Audit Log Entity Design

@Entity
@Table(name = "audit_log")
public class AuditLogEntry {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Enumerated(EnumType.STRING)
    private AuditAction action;
    
    private String entityType;
    private String entityId;
    private String changedBy;
    
    @Column(columnDefinition = "JSON")
    private String oldValue;
    
    @Column(columnDefinition = "JSON")
    private String newValue;
    
    private String ipAddress;
    private String userAgent;
    private LocalDateTime timestamp;
    
    public enum AuditAction {
        CREATE, UPDATE, DELETE
    }
}

2. Generic Audit Logger Service

@Service
public class AuditLogger {
    
    @Autowired
    private AuditLogRepository auditLogRepository;
    
    @Autowired
    private ObjectMapper objectMapper;
    
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public <T> void logChange(AuditAction action, T entity) {
        AuditLogEntry entry = new AuditLogEntry();
        entry.setAction(action);
        entry.setEntityType(entity.getClass().getSimpleName());
        entry.setEntityId(getEntityId(entity));
        entry.setChangedBy(getCurrentUser());
        entry.setTimestamp(LocalDateTime.now());
        
        if (action != AuditAction.CREATE) {
            entry.setOldValue(getOldValue(entity));
        }
        
        if (action != AuditAction.DELETE) {
            entry.setNewValue(objectMapper.writeValueAsString(entity));
        }
        
        auditLogRepository.save(entry);
    }
    
    // Helper methods...
}

3. Integrating with Entity Listeners

public class AuditLoggingListener {
    
    @Autowired
    private AuditLogger auditLogger;
    
    @PostPersist
    public void postPersist(Object entity) {
        auditLogger.logChange(AuditAction.CREATE, entity);
    }
    
    @PostUpdate
    public void postUpdate(Object entity) {
        auditLogger.logChange(AuditAction.UPDATE, entity);
    }
    
    @PostRemove
    public void postRemove(Object entity) {
        auditLogger.logChange(AuditAction.DELETE, entity);
    }
}

Complete Implementation Example

1. Base Auditable Interface

public interface FullAuditable {
    String getCreatedBy();
    String getLastModifiedBy();
    LocalDateTime getCreatedAt();
    LocalDateTime getUpdatedAt();
    String getCreatedFromIp();
    String getUserAgent();
}

2. Entity with Full Auditing

@Entity
@EntityListeners({AuditingEntityListener.class, CustomAuditListener.class, AuditLoggingListener.class})
public class Order implements FullAuditable {
    
    @Id
    @GeneratedValue
    private Long id;
    
    private String orderNumber;
    
    // Standard auditing fields
    @CreatedBy
    private String createdBy;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    @CreatedDate
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    private LocalDateTime updatedAt;
    
    // Extended auditing fields
    private String createdFromIp;
    private String userAgent;
    
    // Business methods...
}

3. Configuration Class

@Configuration
@EnableJpaAuditing(auditorAwareRef = "auditorAware")
@EnableTransactionManagement
public class AuditConfig {
    
    @Bean
    public AuditorAware<String> auditorAware() {
        return new SecurityAuditorAware();
    }
    
    @Bean
    public CustomAuditListener customAuditListener() {
        return new CustomAuditListener();
    }
    
    @Bean
    public AuditLoggingListener auditLoggingListener() {
        return new AuditLoggingListener();
    }
}

Querying Audit Logs

Example repository and query methods for audit logs:

public interface AuditLogRepository extends JpaRepository<AuditLogEntry, Long> {
    
    List<AuditLogEntry> findByEntityTypeAndEntityId(String entityType, String entityId);
    
    @Query("SELECT a FROM AuditLogEntry a WHERE a.entityId = :entityId ORDER BY a.timestamp DESC")
    List<AuditLogEntry> findEntityHistory(@Param("entityId") String entityId);
    
    List<AuditLogEntry> findByChangedByAndTimestampBetween(
        String username, LocalDateTime start, LocalDateTime end);
}

Performance Considerations

Asynchronous Logging:

@Async
public void logChangeAsync(AuditAction action, Object entity) {
    logChange(action, entity);
}

2. Batch Inserts:

@Transactional
public void logChangesInBatch(List<Pair<AuditAction, Object>> changes) {
    List<AuditLogEntry> entries = changes.stream()
        .map(pair -> createEntry(pair.getFirst(), pair.getSecond()))
        .collect(Collectors.toList());
    
    auditLogRepository.saveAll(entries);
}

3. Archiving Strategy:

Implement periodic archiving of old audit logs
Consider partitioning by date for large datasets

This comprehensive approach to custom auditing provides complete visibility into data changes while maintaining flexibility and performance. The separate audit log table ensures you have a complete historical record independent of your main data tables.

8. Auditing Soft Deletes with Spring Data JPA

Implementing Soft Deletes

Soft delete is a pattern where records are marked as deleted rather than physically removed from the database. This approach maintains data integrity and provides an audit trail of deletions.

Core Annotations for Soft Deletes

@Entity
@Table(name = "customers")
@SQLDelete(sql = "UPDATE customers SET deleted_at = NOW(), deleted_by = ? WHERE id = ?")
@Where(clause = "deleted_at IS NULL")
public class Customer {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String name;
    private String email;
    
    @Column(name = "deleted_at")
    private LocalDateTime deletedAt;
    
    @Column(name = "deleted_by")
    private String deletedBy;
    
    // Standard auditing fields
    @CreatedDate
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    private LocalDateTime updatedAt;
    
    // ... other fields and methods ...
}

Automatically Setting Deleted Timestamp

1. Entity Listener Approach

public class SoftDeleteListener {
    
    @PreRemove
    public void preRemove(Object entity) {
        if (entity instanceof SoftDeletable deletable) {
            deletable.setDeletedAt(LocalDateTime.now());
            
            // Get current user from security context
            Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
            if (authentication != null) {
                deletable.setDeletedBy(authentication.getName());
            }
            
            // Prevent actual deletion
            throw new SoftDeleteException();
        }
    }
}

public class SoftDeleteException extends RuntimeException {
    // Marker exception to prevent actual deletion
}

2. Custom Repository Implementation

public interface SoftDeleteRepository<T, ID> extends JpaRepository<T, ID> {
    
    @Override
    @Transactional
    default void delete(T entity) {
        if (entity instanceof SoftDeletable deletable) {
            deletable.setDeletedAt(LocalDateTime.now());
            save(entity); // Update instead of delete
        } else {
            throw new UnsupportedOperationException();
        }
    }
    
    @Query("UPDATE #{#entityName} e SET e.deletedAt = CURRENT_TIMESTAMP WHERE e = :entity")
    void softDelete(@Param("entity") T entity);
}

Querying Soft-Deleted Records

1. Base Repository with Soft Delete Support

@NoRepositoryBean
public interface ExtendedRepository<T, ID> extends JpaRepository<T, ID> {
    
    // Include deleted records
    @Query("SELECT e FROM #{#entityName} e WHERE e.id = :id")
    Optional<T> findByIdIncludeDeleted(@Param("id") ID id);
    
    // Find only deleted records
    @Query("SELECT e FROM #{#entityName} e WHERE e.deletedAt IS NOT NULL")
    List<T> findAllDeleted();
    
    // Restore a soft-deleted record
    @Modifying
    @Query("UPDATE #{#entityName} e SET e.deletedAt = NULL WHERE e.id = :id")
    void restoreById(@Param("id") ID id);
}

2. Custom Query Methods

public interface CustomerRepository extends ExtendedRepository<Customer, Long> {
    
    // Find customers deleted by a specific user
    @Query("SELECT c FROM Customer c WHERE c.deletedBy = :username")
    List<Customer> findDeletedByUser(@Param("username") String username);
    
    // Find customers deleted within a time range
    List<Customer> findByDeletedAtBetween(LocalDateTime start, LocalDateTime end);
}

Complete Soft Delete Implementation Example

1. SoftDeletable Interface

public interface SoftDeletable {
    LocalDateTime getDeletedAt();
    void setDeletedAt(LocalDateTime deletedAt);
    String getDeletedBy();
    void setDeletedBy(String deletedBy);
}

2. Full Auditable Entity

@Entity
@EntityListeners({AuditingEntityListener.class, SoftDeleteListener.class})
@SQLDelete(sql = "UPDATE products SET deleted_at = NOW(), deleted_by = ? WHERE id = ?")
@Where(clause = "deleted_at IS NULL")
public class Product implements SoftDeletable, FullAuditable {
    
    @Id
    @GeneratedValue
    private Long id;
    
    private String name;
    private BigDecimal price;
    
    // Soft delete fields
    @Column(name = "deleted_at")
    private LocalDateTime deletedAt;
    
    @Column(name = "deleted_by")
    private String deletedBy;
    
    // Standard auditing fields
    @CreatedDate
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    private LocalDateTime updatedAt;
    
    @CreatedBy
    private String createdBy;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    // ... getters and setters ...
}

3. Custom Repository Implementation

public class ProductRepositoryImpl extends SimpleJpaRepository<Product, Long> {
    
    private final EntityManager entityManager;
    
    public ProductRepositoryImpl(EntityManager entityManager) {
        super(Product.class, entityManager);
        this.entityManager = entityManager;
    }
    
    @Override
    @Transactional
    public void delete(Product product) {
        product.setDeletedAt(LocalDateTime.now());
        
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication != null) {
            product.setDeletedBy(authentication.getName());
        }
        
        entityManager.merge(product);
    }
    
    @Override
    @Transactional
    public void deleteById(Long id) {
        findById(id).ifPresent(this::delete);
    }
}

Working with Soft Deletes in Service Layer

1. Service Implementation Example

@Service
@Transactional
public class ProductService {
    
    @Autowired
    private ProductRepository productRepository;
    
    public Product createProduct(Product product) {
        return productRepository.save(product);
    }
    
    public void deleteProduct(Long id) {
        productRepository.deleteById(id);
    }
    
    public List<Product> getAllActiveProducts() {
        return productRepository.findAll();
    }
    
    public List<Product> getAllDeletedProducts() {
        return productRepository.findAllDeleted();
    }
    
    public void restoreProduct(Long id) {
        productRepository.restoreById(id);
    }
    
    public Product getProductHistory(Long id) {
        return productRepository.findByIdIncludeDeleted(id)
            .orElseThrow(() -> new EntityNotFoundException("Product not found"));
    }
}

Performance Considerations for Soft Deletes

1. Indexing Strategy:

CREATE INDEX idx_products_deleted_at ON products(deleted_at);
CREATE INDEX idx_products_active ON products(id) WHERE deleted_at IS NULL;

2. Partitioning:

Consider partitioning tables by deletion status for large datasets
Move deleted records to archive tables periodically

3. Query Optimization:

@Query("SELECT p FROM Product p WHERE p.deletedAt IS NULL AND p.price > :minPrice")
List<Product> findActiveByMinPrice(@Param("minPrice") BigDecimal minPrice);

Handling Relationships with Soft Deletes

1. Cascade Soft Deletes

@Entity
public class Order {
    
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL)
    @Where(clause = "deleted_at IS NULL")
    private List<OrderItem> items = new ArrayList<>();
    
    // When order is soft-deleted, items should be too
    @PreUpdate
    public void softDeleteItems() {
        if (this.deletedAt != null) {
            this.items.forEach(item -> {
                item.setDeletedAt(this.deletedAt);
                item.setDeletedBy(this.deletedBy);
            });
        }
    }
}

2. Join Filters

@Entity
public class Department {
    
    @OneToMany(mappedBy = "department")
    @Filter(name = "activeEmployeeFilter", condition = "deleted_at IS NULL")
    private List<Employee> employees;
}

// Enable filter when querying
@Repository
public interface DepartmentRepository extends JpaRepository<Department, Long> {
    
    @Query("SELECT d FROM Department d LEFT JOIN FETCH d.employees e")
    @EntityGraph(attributePaths = {"employees"})
    List<Department> findAllWithActiveEmployees();
}

This comprehensive approach to soft deletes provides a robust audit trail while maintaining data integrity. The implementation allows for:

Automatic tracking of who deleted records and when
Recovery of accidentally deleted records
Efficient querying of both active and deleted records
Proper handling of entity relationships
Minimal impact on existing application code

Table of Contents

1. Introduction to Spring Data JPA Auditing

What is Auditing in Spring Data JPA?

Benefits of Auditing in a Spring Boot Application

Use Cases and Real-World Applications

🔹 User Management Systems

🔹 E-commerce Applications

🔹 Financial Systems

🔹 Content Management Systems

🔹 Healthcare Applications

🔹 Enterprise Applications

🔹 Configuration Management

🔹 Collaborative Applications

2. Setting Up a Spring Boot Project with Spring Data JPA

Dependencies

Maven (pom.xml):

Gradle (build.gradle):

Configuring a Relational Database

H2 Database (in-memory, good for development):

MySQL Database:

PostgreSQL Database:

Creating an Entity Class with JPA

Key JPA Annotations Explained:

3. Enabling Auditing in Spring Data JPA

Understanding `@EnableJpaAuditing

What @EnableJpaAuditing does:

Configuring AuditorAware to Track User Changes

Basic Implementation Concept:

Implementing a Custom AuditorAware

1. First, add the auditing fields to your entity:

2. Create an AuditorAware implementation:

3. Register the AuditorAware bean in your configuration:

Alternative Implementation (for non-Spring Security applications):

Complete Auditing Entity Example

Key Auditing Annotations:

4. Implementing Auditable Entities

Core Auditing Annotations

1. @CreatedDate

2. @LastModifiedDate

3. @CreatedBy

4. @LastModifiedBy

Complete Auditable Entity Example

Key Implementation Details

Alternative: Abstract Base Class Approach

Database Considerations

Testing Audited Entities

5. Database Configuration for Auditing Fields

Handling created_at and updated_at Fields

Database Column Definitions

JPA Entity Configuration

Using Database Triggers vs JPA Auditing

Database Trigger Approach

JPA Auditing Approach

Configuring Automatic Timestamp Updates

Option 1: Pure JPA Approach (Recommended)

Option 2: JPA Callback Methods

Option 3: Hybrid Approach (JPA + Database)

Best Practices for Database Configuration

Migration Script Example

Performance Considerations

6. Testing Spring Data JPA Auditing

Writing Unit Tests with JUnit 5 and Testcontainers

Mocking AuditorAware for Testing

Verifying Audit Fields in the Database

Comprehensive Test Examples

1. Testing Timestamp Updates

2. Testing User Context Changes

3. Testing Bulk Operations

Integration Test Setup

Testing Edge Cases

Performance Testing Considerations

7. Using Custom Audit Listeners

Implementing EntityListeners for Custom Auditing

Basic Custom EntityListener Example

Applying the Listener to an Entity

Capturing Additional Metadata

1. Create an Audit Context Holder

2. Populate the Context via Interceptor

3. Enhanced EntityListener with Context Data

Storing Audit Logs in a Separate Table

Maven (`pom.xml`):

Gradle (`build.gradle`):

What `@EnableJpaAuditing` does:

Configuring `AuditorAware` to Track User Changes

Implementing a Custom `AuditorAware`

2. Create an `AuditorAware` implementation:

3. Register the `AuditorAware` bean in your configuration:

1. `@CreatedDate`

2. `@LastModifiedDate`

3. `@CreatedBy`

4. `@LastModifiedBy`

Handling `created_at` and `updated_at` Fields