UtcDateTimeConverter class

Writes a timestamp (a Postgres timestamptz column) as a UTC instant.

json_serializable's default for a DateTime is toIso8601String(), which for a local time has no offset (2026-10-01T23:30:00.000). Postgres reads an offset-less timestamptz in the session time zone, UTC on Supabase, so 23:30 in Paris was stored as 23:30Z: two hours in the future. A card built with nextReviewAt: DateTime.now() was then not due until the device's UTC offset had elapsed.

toJson converts to UTC first, so the string always ends in Z. fromJson is DateTime.parse, what the generated code did before: reads return the same values as without the converter.

Put it on every timestamptz field of a model, nullable or not (json_serializable skips the converter for a null value):

@UtcDateTimeConverter() required DateTime createdAt,
@UtcDateTimeConverter() DateTime? endedAt,

Do not put it on a calendar date (a Postgres DATE column such as due_date, target_date or deadline). A date is local midnight, and converting that to UTC moves it to the previous day east of Greenwich. test/data/utc_timestamp_writes_test.dart enforces both rules.