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

@Configuration()
class TestClock {
  @Bean()
  DateTimeProvider dateTimeProvider() =>
      DateTimeProvider(() => DateTime.utc(2026, 3, 1, 10));
}

Things to know

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.

See also