{"id":598,"date":"2025-04-19T01:22:55","date_gmt":"2025-04-19T00:22:55","guid":{"rendered":"https:\/\/www.javaeinfacherkl\u00e4rt.de\/?p=598"},"modified":"2025-05-10T01:24:18","modified_gmt":"2025-05-10T00:24:18","slug":"offsetdatetime-mit-offset-korrekt-in-postgresql-speichern-und-laden-mit-spring-data","status":"publish","type":"post","link":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/?p=598","title":{"rendered":"OffsetDateTime mit Offset korrekt in PostgreSQL speichern und laden mit Spring Data"},"content":{"rendered":"\n

Einleitung<\/h2>\n\n\n\n

Zeitangaben mit Offset geh\u00f6ren zu den h\u00e4ufigsten und zugleich sensibelsten Daten in modernen Softwareanwendungen. Die Java-Klasse OffsetDateTime<\/code> aus dem Paket java.time<\/code> erlaubt es, neben Datum und Uhrzeit auch explizit den zugeh\u00f6rigen UTC-Offset (etwa +02:00<\/code>) mitzuf\u00fchren. Dies ist insbesondere in dom\u00e4nenkritischen Anwendungen, wie Protokollierung, Auditing oder internationalen Zeitvergleichen, von gro\u00dfer Bedeutung.<\/p>\n\n\n\n

Wird eine solche Zeitangabe mit Offset in einer PostgreSQL-Datenbank gespeichert, erwartet man typischerweise, dass der Offset ebenfalls persistiert wird. Doch genau hier liegt die Herausforderung: Der g\u00e4ngige PostgreSQL-Datentyp timestamptz<\/code> (timestamp with time zone) speichert den Offset nicht<\/strong> mit. Stattdessen wird der Wert intern nach UTC normalisiert, wodurch der urspr\u00fcngliche Offset verloren geht. Das f\u00fchrt dazu, dass bei der sp\u00e4teren Abfrage nicht mehr rekonstruierbar ist, welcher Offset urspr\u00fcnglich verwendet wurde.<\/p>\n\n\n\n

In diesem Artikel wird ein Ansatz vorgestellt, wie man OffsetDateTime<\/code>-Werte in einer Spring-Boot-Anwendung mithilfe von Spring Data so speichern und laden kann, dass der Offset vollst\u00e4ndig erhalten bleibt. Der beschriebene Weg ist unabh\u00e4ngig von der Systemzeitzone oder JDBC-Konfiguration und basiert auf einem verlustfreien Speichermodell.<\/p>\n\n\n\n

Problemstellung: Der Verlust des Offsets in PostgreSQL<\/h2>\n\n\n\n

PostgreSQL unterscheidet zwischen zwei Zeittypen: timestamp without time zone<\/code> und timestamp with time zone<\/code>. W\u00e4hrend ersterer keinerlei Kontext zu Zeitzonen bietet, suggeriert letzterer, Zeitinformationen inklusive Zeitzonen oder Offsets zu speichern. Tats\u00e4chlich speichert PostgreSQL jedoch bei timestamptz<\/code> ausschlie\u00dflich Zeitpunkte in UTC und verwirft jegliche Offset-Angaben der Eingabewerte.<\/p>\n\n\n\n

Ein Beispiel veranschaulicht das Verhalten: Wird der Wert 2025-05-10T14:00:00+02:00<\/code> gespeichert, legt PostgreSQL ihn intern als 2025-05-10T12:00:00+00:00<\/code> ab. Der urspr\u00fcngliche Offset +02:00<\/code> ist damit dauerhaft verloren. Auch beim Auslesen \u00fcber JDBC wird der Offset nicht rekonstruiert, es sei denn, er wird auf Anwendungsebene separat gespeichert.<\/p>\n\n\n\n

Da OffsetDateTime<\/code> explizit f\u00fcr solche Informationen gedacht ist, ist der Einsatz von timestamptz<\/code> in Verbindung mit dieser Klasse nur bedingt geeignet. Eine zuverl\u00e4ssige Speicherung des vollst\u00e4ndigen Werts erfordert eine alternative L\u00f6sung.<\/p>\n\n\n\n

L\u00f6sung: Speicherung als ISO-8601-String<\/h2>\n\n\n\n

Die zuverl\u00e4ssigste M\u00f6glichkeit, OffsetDateTime<\/code> inklusive Offset zu speichern, besteht darin, ihn als formatierten String in einer PostgreSQL-Spalte vom Typ TEXT<\/code> oder VARCHAR<\/code> abzulegen. Das ISO-8601-Format (yyyy-MM-dd'T'HH:mm:ssXXX<\/code>) eignet sich ideal daf\u00fcr, da es von Java nativ unterst\u00fctzt wird und sowohl den Zeitpunkt als auch den Offset in einem Wert kodiert.<\/p>\n\n\n\n

Ein Beispielwert sieht folgenderma\u00dfen aus:<\/p>\n\n\n

2025-05-10T14<\/span>:23<\/span>:00+02<\/span>:00<\/span>\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
Wird dieser String gespeichert, bleibt der Offset erhalten und l\u00e4sst sich sp\u00e4ter exakt wieder in ein OffsetDateTime<\/code>-Objekt umwandeln. F\u00fcr diese Konvertierung bietet sich in Spring ein benutzerdefinierter AttributeConverter<\/code> an.<\/p>\n\n\n\n
Umsetzung mit Spring Boot und Spring Data<\/h2>\n\n\n\n
Die Implementierung in einer Spring-Anwendung ist unkompliziert. Die relevanten Schritte umfassen die Definition des Datenbankmodells, die Entit\u00e4tsklasse, den Konverter sowie das Repository.<\/p>\n\n\n\n
1. Datenbankstruktur<\/h3>\n\n\n\n
Die entsprechende Tabelle in PostgreSQL verwendet f\u00fcr die Zeitspalte den Typ TEXT<\/code>:<\/p>\n\n\n
CREATE TABLE events (\n    id UUID PRIMARY KEY,\n    name TEXT NOT NULL<\/span>,\n    occurred_at TEXT NOT NULL<\/span>\n);\n<\/code><\/span>Code-Sprache:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Alternativ kann VARCHAR<\/code> mit einer L\u00e4ngenbegrenzung verwendet werden. Ein ISO-8601-String ben\u00f6tigt typischerweise 25 bis 35 Zeichen, abh\u00e4ngig von Genauigkeit und Offset.<\/p>\n\n\n\n
2. Konverter f\u00fcr OffsetDateTime<\/h3>\n\n\n\n
Der Konverter \u00fcbernimmt die Umwandlung zwischen OffsetDateTime<\/code> und String<\/code>:<\/p>\n\n\n
import jakarta.persistence.AttributeConverter;\nimport jakarta.persistence.Converter;\nimport java.time.OffsetDateTime;\nimport java.time.format.DateTimeFormatter;\n\n@Converter(autoApply = true<\/span>)\npublic<\/span> class<\/span> OffsetDateTimeStringConverter<\/span> implements<\/span> AttributeConverter<\/span><OffsetDateTime<\/span>, String<\/span>> <\/span>{\n\n    private<\/span> static<\/span> final<\/span> DateTimeFormatter FORMATTER = DateTimeFormatter.ISO_OFFSET_DATE_TIME;\n\n    @Override\n    public<\/span> String convertToDatabaseColumn(OffsetDateTime attribute) {\n        return<\/span> attribute != null<\/span> ? FORMATTER.format(attribute) : null<\/span>;\n    }\n\n    @Override\n    public<\/span> OffsetDateTime convertToEntityAttribute(String dbData) {\n        return<\/span> dbData != null<\/span> ? OffsetDateTime.parse(dbData, FORMATTER) : null<\/span>;\n    }\n}\n<\/code><\/span>Code-Sprache:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Dank autoApply = true<\/code> wird der Konverter automatisch auf alle Felder vom Typ OffsetDateTime<\/code> angewendet, sofern kein anderer Konverter angegeben ist.<\/p>\n\n\n\n
3. Entity-Klasse<\/h3>\n\n\n\n
Die Entit\u00e4t verwendet das OffsetDateTime-Feld wie gewohnt:<\/p>\n\n\n
import<\/span> jakarta.persistence.Entity;\nimport<\/span> jakarta.persistence.Id;\nimport<\/span> java.time.OffsetDateTime;\nimport<\/span> java.util.UUID;\n\n@Entity\npublic class<\/span> Event<\/span> <\/span>{\n\n    @Id\n    private UUID id;\n\n    private String<\/span> name;\n\n    private OffsetDateTime occurredAt;\n\n    public Event() {}\n\n    public Event(UUID id, String<\/span> name, OffsetDateTime occurredAt) {\n        this<\/span>.id = id;\n        this<\/span>.name = name;\n        this<\/span>.occurredAt = occurredAt;\n    }\n\n    \/\/ Getter und Setter<\/span>\n}\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
4. Repository und Nutzung<\/h3>\n\n\n\n
Das zugeh\u00f6rige Repository ben\u00f6tigt keine besonderen Anpassungen:<\/p>\n\n\n
import<\/span> org<\/span>.springframework<\/span>.data<\/span>.jpa<\/span>.repository<\/span>.JpaRepository<\/span>;\nimport<\/span> java<\/span>.util<\/span>.UUID<\/span>;\n\npublic<\/span> interface<\/span> EventRepository<\/span> extends<\/span> JpaRepository<\/span><Event<\/span>, UUID<\/span>> {\n}\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
Ein typischer Anwendungscode kann wie folgt aussehen:<\/p>\n\n\n
import org.springframework.stereotype.Service;\nimport java.time.OffsetDateTime;\nimport java.time.ZoneOffset;\nimport java.util.UUID;\n\n@Service\npublic<\/span> class<\/span> EventService<\/span> <\/span>{\n\n    private<\/span> final<\/span> EventRepository repository;\n\n    public<\/span> EventService(EventRepository repository) {\n        this.repository = repository;\n    }\n\n    public<\/span> void createEvent() {\n        OffsetDateTime dateTime = OffsetDateTime.now(ZoneOffset.ofHours(2<\/span>));\n        Event event = new<\/span> Event(UUID.randomUUID(), \"Systemstart\"<\/span>, dateTime);\n        repository.save(event);\n    }\n\n    public<\/span> OffsetDateTime getOccurredAt(UUID id) {\n        return<\/span> repository.findById(id)\n                .map(Event::getOccurredAt)\n                .orElseThrow();\n    }\n}\n<\/code><\/span>Code-Sprache:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Validierung und Tests<\/h2>\n\n\n\n
Beim Schreiben von Tests empfiehlt es sich, nicht nur den Zeitpunkt, sondern auch den Offset zu pr\u00fcfen:<\/p>\n\n\n
import<\/span> static<\/span> org.junit.jupiter.api.Assertions.*;\n\n@Test\nvoid<\/span> testOffsetDateTimePersistence() {\n    OffsetDateTime expected = OffsetDateTime.of(2025<\/span>, 5<\/span>, 10<\/span>, 14<\/span>, 0<\/span>, 0<\/span>, 0<\/span>, ZoneOffset.ofHours(3<\/span>));\n    Event event = new<\/span> Event(UUID.randomUUID(), \"Testevent\"<\/span>, expected);\n    repository.save(event);\n\n    Event loaded = repository.findById(event.getId()).orElseThrow();\n    assertEquals(expected, loaded.getOccurredAt());\n}\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Damit ist sichergestellt, dass Offset und Zeitpunkt identisch bleiben \u2013 unabh\u00e4ngig von der aktuellen JVM-Zeitzone oder Datenbankkonfiguration.<\/p>\n\n\n\n
Alternative: Zeit und Offset getrennt speichern<\/h2>\n\n\n\n
Ein alternativer Ansatz besteht darin, den UTC-Zeitpunkt (Instant<\/code>) und den Offset separat zu speichern, etwa in zwei Spalten: TIMESTAMPTZ<\/code> und INTEGER<\/code> (f\u00fcr Minuten-Offset). Diese Methode erlaubt komplexe zeitbasierte SQL-Abfragen, erfordert jedoch mehr manuellen Aufwand im Mapping und der Konvertierung.<\/p>\n\n\n\n
Fazit<\/h2>\n\n\n\n
Wenn es erforderlich ist, OffsetDateTime<\/code>-Werte in PostgreSQL vollst\u00e4ndig inklusive ihres Offsets zu speichern und wieder exakt zu laden, ist der Standardweg \u00fcber timestamptz<\/code> nicht ausreichend. Der Offset geht bei diesem Datentyp zwangsl\u00e4ufig verloren, da PostgreSQL intern alle Zeitangaben nach UTC konvertiert.<\/p>\n\n\n\n
Die zuverl\u00e4ssigste L\u00f6sung besteht darin, die Werte als ISO-8601-konforme Strings in einer TEXT<\/code>-Spalte zu speichern und in der Anwendung mit einem AttributeConverter<\/code> zu behandeln. Dadurch bleibt die gesamte Information \u2013 Datum, Uhrzeit und Offset \u2013 vollst\u00e4ndig erhalten und ist unabh\u00e4ngig von Zeitzonen- oder Konfigurationseinfl\u00fcssen der Datenbank oder des JDBC-Treibers.<\/p>\n\n\n\n
Diese Methode ist einfach zu implementieren, transparent zu debuggen und eignet sich besonders f\u00fcr Anwendungen, bei denen zeitliche Pr\u00e4zision und Nachvollziehbarkeit eine entscheidende Rolle spielen.<\/p>\n","protected":false},"excerpt":{"rendered":"
Einleitung Zeitangaben mit Offset geh\u00f6ren zu den h\u00e4ufigsten und zugleich sensibelsten Daten in modernen Softwareanwendungen. Die Java-Klasse OffsetDateTime aus dem Paket java.time erlaubt es, neben Datum und Uhrzeit auch explizit den zugeh\u00f6rigen UTC-Offset (etwa +02:00) mitzuf\u00fchren. Dies ist insbesondere in dom\u00e4nenkritischen Anwendungen, wie Protokollierung, Auditing oder internationalen Zeitvergleichen, von gro\u00dfer Bedeutung. Wird eine solche Zeitangabe […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-598","post","type-post","status-publish","format-standard","hentry","category-spring"],"_links":{"self":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/598","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=598"}],"version-history":[{"count":1,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/598\/revisions"}],"predecessor-version":[{"id":599,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/598\/revisions\/599"}],"wp:attachment":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=598"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=598"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=598"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}