Enums in der Datenbank speichern: @Enumerated, Postgres-Enum-Typen und Lookup-Tabellen
Fast jedes Domänenmodell hat ein Feld, das nur einen von einer Handvoll Werte annehmen kann. Eine
Bestellung ist PENDING, PAID, SHIPPED, DELIVERED oder CANCELLED. Eine Zahlung ist
autorisiert oder eingezogen. Ein Abo hat einen von vier Tarifen. In Java greifst du ohne
Nachdenken zu einem enum. Interessant ist, was an der Schnittstelle zur Datenbank passiert:
Wie liegt diese endliche Menge von Werten dort tatsächlich vor, und was kostet dich jede
Option sechs Monate später, wenn sich die Menge ändert?
Dieser Artikel geht jeden gängigen Weg durch, ein Enum mit Hibernate zu persistieren, und zwar in
der Reihenfolge, in der du ihnen in der Praxis begegnest: die beiden @Enumerated-Modi, einen echten
Postgres-ENUM-Typ, einen AttributeConverter und schließlich den Lookup-Tabellen-Ansatz, bei dem
das Enum zur eigenen Tabelle wird. Ich führe ein einziges Beispiel, den Status einer Bestellung,
durch alle Varianten und ende mit der Entscheidung, die ich tatsächlich treffe.
Stack: Java, Spring Boot, Hibernate, PostgreSQL.
TL;DR
@Enumerated(ORDINAL)speichert die Position des Enums — kompakt, aber das Einfügen eines Werts in der Mitte beschädigt stillschweigend jede nachfolgende Zeile. Wenn du es wirklich brauchst, schreibe die Ordinals mit einem Unit-Test fest.@Enumerated(STRING)speichert den Namen der Konstante — selbsterklärend, debuggbar, unempfindlich gegen Umordnen. Das ist der vernünftige Standard.- Gib dich nicht mit einem nackten
varcharzufrieden – definiere einen echten Postgres-ENUM-Typ, damit die Datenbank selbst ungültige Werte ablehnt. - Ein
AttributeConverterpersistiert einen stabilen Code, entkoppelt vom Java-Namen — Umbenennungen sind kein Datenbankthema mehr. - Eine Lookup-Tabelle lohnt sich nur, wenn die Werte editierbare Business-Daten tragen — nicht als Umweg, um Umbenennungen zu überleben.
Das Szenario
Wir bauen eine Bestellverwaltung. Eine Bestellung durchläuft einen festen Lebenszyklus:
stateDiagram-v2
[*] --> PENDING
PENDING --> PAID
PENDING --> CANCELLED
PAID --> SHIPPED
SHIPPED --> DELIVERED
PAID --> CANCELLED
In Java ist das ein offensichtliches Enum:
public enum OrderStatus {
PENDING,
PAID,
SHIPPED,
DELIVERED,
CANCELLED
}
Die Order-Entity hat ein status-Feld. Die einzige Frage ist, wie Hibernate es auf eine Spalte
mappt – und diese eine Entscheidung bei der Annotation hat Folgen, die den Code, den du heute
schreibst, überdauern.
Teil 1 — @Enumerated(ORDINAL): Als Int speichern
Der JPA-Standard für ein Enum ist ORDINAL. Jede Konstante wird als ihre Position in der Deklaration
gespeichert: PENDING → 0, PAID → 1, SHIPPED → 2 und so weiter.
@Entity
@Table(name = "orders_ordinal")
public class OrderOrdinal {
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;
@Enumerated(EnumType.ORDINAL) // this is also the default if you omit @Enumerated
@Column(nullable = false)
private OrderStatus status;
}
CREATE TABLE orders_ordinal (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
status SMALLINT NOT NULL
);
Speicherst du eine Bestellung mit Status PAID, hält die Spalte 1. Das ist kompakt und wirkt
auf dem Papier unproblematisch.
❌ Die Falle: Einen Wert in der Mitte einfügen
Das Ordinal wird nicht als Label gespeichert, sondern als Position, und die Position ergibt sich aus der Reihenfolge im Quellcode. An dem Tag, an dem jemand einen Pack-Schritt zwischen bezahlt und verschickt einfügt:
public enum OrderStatus {
PENDING,
PAID,
PACKED, // <-- inserted here
SHIPPED,
DELIVERED,
CANCELLED
}
… rutscht jede Konstante nach PAID um eine Position nach hinten:
| Konstante | Ordinal vorher | Ordinal nachher |
|---|---|---|
PENDING |
0 | 0 |
PAID |
1 | 1 |
PACKED |
— | 2 |
SHIPPED |
2 | 3 |
DELIVERED |
3 | 4 |
CANCELLED |
4 | 5 |
In der Datenbank hat sich nichts geändert. Jede bestehende SHIPPED-Bestellung hält weiterhin
die Integer 2 — aber 2 dekodiert jetzt als PACKED. Verschickte Bestellungen werden
stillschweigend zu gepackten, aus zugestellten werden verschickte. Kein Fehler, keine
fehlgeschlagene Migration, keine Logzeile. Die Daten haben sich nicht verändert, nur ihre
Deutung. Auffallen wird es erst, wenn ein Kunde fragt, warum seine bereits zugestellte Bestellung
gerade gepackt wird.
Der Schutz: Ordinals festpinnen
Hast du einen Grund, bei ORDINAL zu bleiben (ein Legacy-Schema, eine riesige, stark
beanspruchte Tabelle, bei der der Byte-Unterschied zählt), dann mache die tragende Reihenfolge
explizit, mit einem Test, der fehlschlägt, sobald jemand das Enum umordnet:
class OrdinalPinTest {
@Test
void ordinalsAreFrozen() {
// If this test fails, you reordered OrderStatus. Existing ORDINAL-mapped rows now mean
// something different. Revert the reorder, or append the new value at the end.
assertThat(OrderStatus.PENDING.ordinal()).isZero();
assertThat(OrderStatus.PAID.ordinal()).isEqualTo(1);
assertThat(OrderStatus.SHIPPED.ordinal()).isEqualTo(2);
assertThat(OrderStatus.DELIVERED.ordinal()).isEqualTo(3);
assertThat(OrderStatus.CANCELLED.ordinal()).isEqualTo(4);
assertThat(OrderStatus.values()).hasSize(5);
}
}
Das ist ein reiner Unit-Test, ohne Spring Context und ohne Datenbank. Er macht aus einem
unsichtbaren Datenkorruptions-Bug einen roten Build, sobald jemand das Enum anfasst. Neue
Werte sind weiterhin erlaubt; sie müssen nur ans Ende, wo Anhängen sicher ist. Das ist die
gesamte Regel, auf der ORDINAL stillschweigend beruht, schwarz auf weiß.
Teil 2 — @Enumerated(STRING): Als Varchar speichern
Die Lösung für fast alle Fälle besteht aus einem Wort:
@Enumerated(EnumType.STRING)
@Column(nullable = false)
private OrderStatus status;
Jetzt speichert die Spalte den Namen der Konstante:
CREATE TABLE orders_string (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
status VARCHAR NOT NULL
);
Eine PAID-Bestellung speichert den Literal-String 'PAID'. Drei Dinge werden sofort besser:
- Umordnen ist harmlos. Der Wert ist sein eigener Name; Positionen spielen keine Rolle mehr.
Füge
PACKEDein, wo du willst. - Es ist debuggbar.
SELECT * FROM orders_string WHERE status = 'PAID'liest sich wie Klartext. Kein Entschlüsseln, kein gedanklicher Join gegen deinen Java-Quellcode. - Dumps und Logs sind selbsterklärend. Eine Zeile in einem CSV-Export ist auch ohne Kontext verständlich.
Ja, 'DELIVERED' kostet mehr Bytes als 3. Für die allermeisten Tabellen ist
dieser Unterschied vernachlässigbar, und einen Index kannst du immer ergänzen. Den Namen zu speichern
ist der richtige Standard, und „kompakt“ ist fast nie den Preis von „stillschweigend falsch“ wert.
Die eine verbleibende Falle: Umbenennungen
STRING beseitigt die Reihenfolge-Falle, führt aber eine kleinere ein. Der gespeicherte Wert ist
der Java-Bezeichner — benennst du die Konstante um, verwaisen bestehende Zeilen:
PENDING → AWAITING_PAYMENT
Jede alte 'PENDING'-Zeile passt auf keine Konstante mehr, und Hibernate wirft beim Lesen eine
Exception. Gespeicherte Daten und Code sind stillschweigend auseinandergedriftet. Beheben lässt
sich das mit einer Datenmigration (UPDATE … SET status = 'AWAITING_PAYMENT' WHERE status =
'PENDING'), und das ist eine völlig legitime Lösung. In Teil 4 sehen wir außerdem einen Weg,
Umbenennungen ganz zum Nicht-Ereignis zu machen.
Teil 3 — Sauberer Stil: Ein echter Postgres-Enum-Typ
Beide Optionen oben schreiben in eine Spalte, die die Datenbank nicht wirklich versteht: ein
smallint oder ein varchar, das zufällig Enum-Werte enthält. Postgres kann es besser, denn es
kennt echte Enum-Typen:
CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', 'SHIPPED', 'DELIVERED', 'CANCELLED');
CREATE TABLE orders_pgenum (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
status order_status NOT NULL
);
Jetzt erzwingt die Datenbank die Wertemenge. Ein INSERT … VALUES ('SHPPED') – ein Tippfehler,
eine fehlerhafte Migration, ein wild geschriebenes Skript – scheitert direkt an der Quelle mit invalid input value
for enum order_status. Bei einem nackten varchar landet dieser Müll in der Tabelle, und du
entdeckst ihn erst später. Der Enum-Typ ist Dokumentation und Constraint in einem: Der Spaltentyp
listet seine zulässigen Werte wörtlich auf.
Das Mapping in Hibernate ist dasselbe @Enumerated(STRING) wie zuvor: Hibernate bindet den
Konstantennamen als String, und Postgres speichert ihn im Enum:
@Enumerated(EnumType.STRING)
@Column(nullable = false, columnDefinition = "order_status")
private OrderStatus status;
Es gibt genau eine Stelle, die du noch konfigurieren musst. Standardmäßig sendet der
PostgreSQL-JDBC-Treiber einen Java-String als Typ varchar, und Postgres castet varchar nicht
implizit auf order_status, du bekämst also column "status" is of type order_status but expression is of type character
varying. Hänge stringtype=unspecified an die JDBC-URL, und der Treiber sendet den Wert als
unknown, sodass Postgres ihn auf das Enum casten kann:
spring:
datasource:
url: jdbc:postgresql://localhost:5434/mydatabase?stringtype=unspecified
(Hibernate 6 bietet außerdem @JdbcTypeCode(SqlTypes.NAMED_ENUM), um einen benannten Enum-Typ
direkt anzusprechen; die Kombination aus @Enumerated(STRING) und stringtype=unspecified oben
ist die gängigste, und ich greife zu ihr.)
Der eine Haken, den du kennen solltest: ALTER TYPE order_status ADD VALUE 'PACKED' fügt
nur etwas hinzu. Du kannst einen Wert ergänzen (seit PostgreSQL 12 sogar vor oder nach einem
bestimmten), aber bestehende Werte kannst du nicht löschen oder umordnen, ohne den Typ neu zu
erzeugen. Das klingt einschränkend, bis dir auffällt, dass es dieselbe Regel ist, die der
Ordinal-Test erzwungen hat (nie umordnen, nur ergänzen), nur dass hier die Datenbank sie
garantiert statt eines Unit-Tests. Die Einschränkung ist das Feature.
Teil 4 — AttributeConverter: Name und gespeicherten Wert entkoppeln
Die Umbenennungs-Falle aus Teil 2 gibt es, weil gespeicherter Wert und Java-Bezeichner
derselbe String sind. Ein JPA-AttributeConverter löst diese Kopplung: Du persistierst einen
stabilen Code, der mit dem Namen der Konstante nichts zu tun hat.
Gib jeder Konstante einen expliziten, permanenten Code:
public enum OrderStatus {
PENDING("PND"),
PAID("PAID"),
SHIPPED("SHP"),
DELIVERED("DLV"),
CANCELLED("CNC");
private final String code;
OrderStatus(String code) {
this.code = code;
}
public String getCode() {
return code;
}
public static OrderStatus fromCode(String code) {
return Arrays.stream(values())
.filter(s -> s.code.equals(code))
.findFirst()
.orElseThrow(() -> new IllegalArgumentException("Unknown OrderStatus code: " + code));
}
}
Dann ein Converter, der Enum ↔ Code mappt:
@Converter
public class OrderStatusConverter implements AttributeConverter<OrderStatus, String> {
@Override
public String convertToDatabaseColumn(OrderStatus status) {
return status == null ? null : status.getCode();
}
@Override
public OrderStatus convertToEntityAttribute(String code) {
return code == null ? null : OrderStatus.fromCode(code);
}
}
Und binde ihn am Feld mit @Convert statt @Enumerated ein:
@Convert(converter = OrderStatusConverter.class)
@Column(nullable = false)
private OrderStatus status;
Jetzt speichert die Datenbank einen Code, nicht den Bezeichner. Benenne die
Java-Konstante PENDING in AWAITING_PAYMENT um, und der gespeicherte Code 'PND' ändert sich
nie. Die Umbenennung ist ein reiner Refactor ohne jede Auswirkung auf die Datenbank. Du hast
entkoppelt, was die Datenbank weiß, von dem, wie du Dinge im Code nennst – genau die Eigenschaft,
derentwegen viele zu Lookup-Tabellen greifen. Merk dir das für den nächsten Teil.
Teil 5 — Der Lookup-Tabellen-Ansatz
Der letzte Ansatz behandelt den Status gar nicht mehr als Enum. Stattdessen liegt die Menge der Status in einer eigenen Tabelle, und Bestellungen verweisen per Foreign Key auf eine Zeile:
CREATE TABLE order_statuses (
id INTEGER PRIMARY KEY,
code VARCHAR NOT NULL UNIQUE,
label VARCHAR NOT NULL,
terminal BOOLEAN NOT NULL DEFAULT FALSE
);
INSERT INTO order_statuses (id, code, label, terminal) VALUES
(1, 'PND', 'Pending', FALSE),
(2, 'PAID', 'Paid', FALSE),
(3, 'SHP', 'Shipped', FALSE),
(4, 'DLV', 'Delivered', TRUE),
(5, 'CNC', 'Cancelled', TRUE);
CREATE TABLE orders_lookup (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
status_id INTEGER NOT NULL REFERENCES order_statuses (id)
);
In JPA wird der Status zu einer Relation, nicht zu einem Enum-Wert:
@Entity
@Table(name = "orders_lookup")
public class OrderLookup {
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;
@ManyToOne(fetch = FetchType.EAGER, optional = false)
@JoinColumn(name = "status_id", nullable = false)
private OrderStatusDefinition status;
}
Um zu wissen, welchen Status eine Bestellung hat (ihr lesbares Label, ob sie terminal ist), musst du joinen:
SELECT o.id, s.code, s.label
FROM orders_lookup o
JOIN order_statuses s ON s.id = o.status_id
WHERE o.id = ?;
✅ Wann sich das lohnt
Die Lookup-Tabelle bringt einen echten Vorteil: Die Menge der Werte samt der an jedem hängenden Metadaten liegt in Daten statt in Code. Das ist dann wirklich wertvoll, wenn:
- Jeder Wert editierbare Fachdaten trägt: ein Anzeige-Label, eine Sortierreihenfolge, eine Farbe, ein Feature-Flag, ein SLA. Der Status ist nicht nur eine Identität, sondern ein kleiner Datensatz.
- Nicht-Entwickler die Werte pflegen, sie pro Tenant konfiguriert werden oder sich zur Laufzeit ohne Deployment ändern.
- Du echte Massenänderungen hast: Ein Label, das in Millionen von Zeilen erscheint, benennst
du um, indem du eine Zeile in
order_statusesaktualisierst statt jeder Bestellung.
Der letzte Punkt ist das stärkste Argument: Du änderst eine Stelle statt aller. Ist dein „Enum“ tatsächlich ein gepflegter Katalog, ist das das richtige Modell.
Meine Einschätzung
Für ein schlichtes Enum, also eine feste Menge von Zuständen im Code wie einen Bestell-Lebenszyklus, nutze ich keine Lookup-Tabelle, und im Review würde ich dagegen halten.
Die übliche Begründung, die ich höre, lautet: „Was ist, wenn wir einen Wert umbenennen müssen?“
Das lässt sich aber, wie wir gerade gesehen haben, auch ohne Tabelle lösen: Ein AttributeConverter
entkoppelt den gespeicherten Code vom Java-Namen, und ein geändertes Label ist eine
Migration mit einer einzigen Zeile. Du brauchst keinen Foreign Key und keinen Join in jeder Query, um eine
Umbenennung zu überstehen.
Was die Lookup-Tabelle in diesem Fall tatsächlich hinzufügt, sind dauerhafte Kosten: Jeder
Lesezugriff joint entweder oder braucht eine zweite Query, der Status ist jetzt eine verwaltete
Relation statt eines Werts, und ein switch über deine Zustände, den der Compiler auf
Vollständigkeit prüft, wird zu einem Lookup zur Laufzeit, der ins Leere laufen kann. Du hast einen
Wert, den dein Compiler versteht, gegen eine Zeile getauscht, die er nicht versteht, um eine
Flexibilität zu erkaufen, die ein fester Lebenszyklus nie nutzt.
Meine Regel hängt also davon ab, was der Wert ist, nicht von Umbenennungen:
- Ist der Wert nur Identität (es ist
SHIPPED, Punkt), lass es ein Enum. Mappe es mit@Enumerated(STRING), sichere es mit einem Postgres-Enum-Typ ab und greife zu einemAttributeConverter, wenn Umbenennungen nichts kosten sollen. - Ist der Wert ein Datensatz (er hat Felder, die Menschen zur Laufzeit editieren), dann war er nie wirklich ein Enum. Gib ihm eine Tabelle.
Nicht das Umbenennen gibt den Ausschlag, sondern die Frage, ob das Ding eigene Daten hat.
Entscheidungshilfe
| Ansatz | Speichert | Einsetzen, wenn | Hauptrisiko |
|---|---|---|---|
@Enumerated(ORDINAL) |
Position (1) |
fast nie | Umordnen beschädigt stillschweigend Zeilen |
@Enumerated(STRING) |
Name der Konstante ('PAID') |
der vernünftige Standard | Umbenennungen lassen Zeilen verwaisen |
Postgres-ENUM-Typ |
Name, von der DB validiert | die DB soll ungültige Werte ablehnen | ADD VALUE kann nur anhängen |
AttributeConverter |
stabiler Code ('PND') |
Umbenennungen sollen nichts kosten | eine kleine Klasse, die gewartet werden muss |
| Lookup-Tabelle | FK auf eine Zeile | Werte tragen editierbare Daten | ein Join bei jedem Lesezugriff |
Ein solider Standard für die meisten Projekte: @Enumerated(STRING) auf einem
Postgres-Enum-Typ, mit dem Wechsel auf einen AttributeConverter, sobald du den
gespeicherten Wert vom Java-Namen entkoppeln willst.
Code
Den Code zu diesem Artikel findest du unter
github.com/javaAndScriptDeveloper/enums-article:
dasselbe OrderStatus-Enum, auf alle fünf Arten persistiert, der Test, der die Ordinals festschreibt, und ein
Round-Trip-Test pro Ansatz, der prüft, was tatsächlich in die Datenbank geschrieben wird. Alles läuft
lokal mit Docker und einem einzigen ./gradlew test.
Abschließende Gedanken
Wie man ein Enum speichert, fühlt sich wie eine Entscheidung für fünf Sekunden an, und genau deshalb lohnt es sich, hier langsamer zu machen. Die Ordinal-Falle, die Umbenennungs-Falle, der fehlende Constraint in der Datenbank: Keine davon zeigt sich an dem Tag, an dem du die Annotation schreibst. Sie zeigt sich an dem Tag, an dem sich die Wertemenge ändert, und das geschieht immer, meist lange nachdem du vergessen hast, welchen Trade-off du eingegangen bist.
Die gute Nachricht: Die Standardwege sind einfach. Speichere den Namen, lass die Datenbank ihn validieren und entkoppel den Code vom Bezeichner, wenn du es brauchst. Heb dir die Lookup-Tabelle für die Fälle auf, die wirklich ein Katalog und kein Enum sind. Machst du das einmal richtig, bleiben deine Status langweilig – das größte Kompliment, das man einer Spalte machen kann.
Lass uns sprechen
Wenn du Enums anders speicherst oder von einer dieser Fallen auf eine Weise erwischt wurdest, die ich nicht behandelt habe, würde ich gerne davon hören. Kontaktlinks findest du im Footer.
Häufig gestellte Fragen
Sollte ich @Enumerated ORDINAL oder STRING verwenden?
Verwende STRING. @Enumerated(ORDINAL) speichert die Position des Enums (0, 1, 2 …), sodass jede neue Konstante, die nicht ganz am Ende eingefügt wird, stillschweigend bestehende Zeilen auf einen anderen Wert umbiegt. @Enumerated(STRING) speichert den Namen der Konstante (‘PAID’) — selbsterklärend, direkt per SQL debuggbar und unempfindlich gegen Umordnen. Die paar Bytes mehr Speicherplatz fallen neben dem Sicherheitsgewinn nicht ins Gewicht.
Was geht kaputt, wenn ich mit ORDINAL einen Enum-Wert in der Mitte einfüge?
Jede Zeile, die nach der eingefügten Konstante gespeichert wurde, dekodiert jetzt auf den falschen Wert. War SHIPPED das Ordinal 2 und du fügst PACKED davor ein, wird SHIPPED zu 3 – aber alle bestehenden Zeilen enthalten weiterhin die 2, die nun als PACKED gelesen wird. Die Datenbank ändert sich nicht; deine Interpretation tut es. Schütze dich mit einem Unit-Test, der ordinal() jeder Konstante festschreibt.
Wie speichere ich ein Enum als Postgres-Enum-Typ?
Lege den Typ mit CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', …) an, gib der Spalte diesen Typ und mappe ihn in Hibernate mit @Enumerated(EnumType.STRING). Hänge stringtype=unspecified an die JDBC-URL, damit der Treiber den Wert als unknown sendet und Postgres den Cast von String auf Enum vornehmen kann. Die Datenbank weist dann jeden Wert außerhalb des Enums zurück.
Wie benenne ich eine Enum-Konstante um, ohne bestehende Zeilen zu zerstören?
Entkopple den gespeicherten Wert vom Java-Bezeichner. Mit einem JPA-AttributeConverter persistierst du einen stabilen Code (‘PAID’) statt des Konstantennamens — die Umbenennung von PENDING in AWAITING_PAYMENT wird damit zu einer reinen Code-Änderung: keine Migration, keine verwaisten Zeilen. Deshalb braucht man selten eine Lookup-Tabelle, nur um Umbenennungen zu überstehen.
Wann sollte ich eine Enum-Lookup-Tabelle statt @Enumerated verwenden?
Wenn die Werte editierbare Business-Daten tragen, nicht nur Identität (ein den Nutzern angezeigtes Label, eine Sortierreihenfolge, ein Feature-Flag), oder wenn Nicht-Entwickler sie zur Laufzeit ergänzen und bearbeiten müssen. Ist das Enum eine feste Menge von Zuständen, die nur im Code existieren, bringt eine Lookup-Tabelle vor allem einen Join und eine zusätzliche Indirektion für eine Flexibilität, die du nie nutzen wirst.