Auditing
Auditing fills four kinds of properties when an entity is saved: the time it was created, the time it was last changed, who created it and who last changed it. You mark the properties and switch auditing on with @EnableDataAuditing() on a configuration class.
Why
"Who changed this row, and when?" is asked of almost every table. Setting these values in every service is easy to forget, and the values drift (one service uses local time, another UTC). With auditing the repository sets them on every save, from one clock and one source of the current user.
Example
@Table('books')
class Book {
Book({this.id, required this.title});
@Id()
int? id;
String title;
@CreatedDate()
DateTime? createdAt; // the time of the insert, kept afterwards
@LastModifiedDate()
DateTime? modifiedAt; // the time of each save
@CreatedBy()
String? createdBy; // the auditor at the insert
@LastModifiedBy()
String? modifiedBy; // the auditor at each save
}
@Configuration()
@EnableDataAuditing()
class AuditingSetup {}
// Who is acting: read it from your security context, a request, a job name...
@Component()
class CurrentUser implements AuditorAware<String> {
@override
String? getCurrentAuditor() => 'librarian';
}
final saved = await books.save(Book(title: 'Dune'));
print(saved.createdBy); // librarian
print(saved.createdAt == saved.modifiedAt); // true: an insert also sets the "last modified" values
The annotations
| Annotation | Type | Set |
|---|---|---|
@CreatedDate() |
DateTime |
at the insert, then kept |
@LastModifiedDate() |
DateTime |
at each save (and at the insert, with modifyOnCreate) |
@CreatedBy() |
the auditor's type | at the insert, then kept |
@LastModifiedBy() |
the auditor's type | at each save (and at the insert, with modifyOnCreate) |
@EnableDataAuditing
| Attribute | Default | Meaning |
|---|---|---|
auditorAwareRef |
'' |
The name of the AuditorAware bean; empty for the only one. |
dateTimeProviderRef |
'' |
The name of the DateTimeProvider bean; empty for the only one, or the system clock when there is none. |
setDates |
true |
Whether @CreatedDate and @LastModifiedDate are set; when false, only the auditor properties are. |
modifyOnCreate |
true |
Whether an insert also sets @LastModifiedDate and @LastModifiedBy, to the creation's values. |
Without @EnableDataAuditing the annotations do nothing: the auditingHandler bean exists only when a bean carries it.
The auditor and the clock
AuditorAware<T>answersgetCurrentAuditor(), synchronously or with aFuture. An answer ofnull(nobody is logged in) leaves the properties as they are.DateTimeProvideris the clock. The default isDateTime.now; declare a bean to fix the time in tests:
@Configuration()
class TestClock {
@Bean()
DateTimeProvider dateTimeProvider() =>
DateTimeProvider(() => DateTime.utc(2026, 3, 1, 10));
}
Things to know
- Use what
savereturns. An entity withfinalaudit properties is copied with the new values, so the instance you passed in is unchanged. - Database cascades are not audited. A row changed by
@OnDelete(OnDeleteAction.setNull)goes through no repositorysave(see References and keys). JdbcTemplatestatements are not audited, nor are@Modifyingqueries: auditing is part of a repository'ssave.
In Spring (Java)
@Configuration
@EnableJdbcAuditing(auditorAwareRef = "currentUser")
class AuditingSetup {}
@Component
class CurrentUser implements AuditorAware<String> {
public Optional<String> getCurrentAuditor() { return Optional.of("librarian"); }
}
The annotation is @EnableDataAuditing instead of @EnableJdbcAuditing; getCurrentAuditor returns a nullable value (or a Future of one) instead of an Optional.