
# 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

```dart
@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';
}
```

```dart
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>`** answers `getCurrentAuditor()`, synchronously or with a `Future`. An answer of `null` (nobody is logged in) leaves the properties as they are.
- **`DateTimeProvider`** is the clock. The default is `DateTime.now`; declare a bean to fix the time in tests:

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

## Things to know

- **Use what `save` returns.** An entity with `final` audit 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 repository `save` (see [References and keys](references.md)).
- **`JdbcTemplate` statements are not audited**, nor are `@Modifying` queries: auditing is part of a repository's `save`.

## In Spring (Java)

```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

- [Entities](entities.md)
- [Repositories](repositories.md)
