Armazenando Enums no Banco de Dados: @Enumerated, Tipos Enum do Postgres e Tabelas de Lookup
Quase todo modelo de domínio tem um campo que só pode conter um punhado de valores. Um pedido é
PENDING, PAID, SHIPPED, DELIVERED ou CANCELLED. Um pagamento é autorizado ou capturado. Uma
assinatura está em um de quatro planos. Em Java, você recorre a um enum sem pensar. A pergunta
interessante é o que acontece na fronteira — como esse conjunto finito de valores realmente vive no
banco de dados — e o que cada opção custa seis meses depois, quando o conjunto muda.
Este artigo percorre todas as maneiras comuns de persistir um enum com Hibernate, na ordem em que você
realmente as encontraria: os dois modos do @Enumerated, um tipo ENUM real do Postgres, um
AttributeConverter e, por fim, a abordagem de tabela de lookup, em que o enum se torna uma tabela
própria. Vou evoluir um único exemplo — o status de um pedido — do começo ao fim, e terminar com a
escolha que eu realmente faço.
Stack: Java, Spring Boot, Hibernate, PostgreSQL.
TL;DR
- O
@Enumerated(ORDINAL)armazena a posição do enum — compacto, mas inserir um valor no meio corrompe silenciosamente todas as linhas seguintes. Se precisar usá-lo, fixe os ordinais com um teste de unidade. - O
@Enumerated(STRING)armazena o nome da constante — autodescritivo, fácil de depurar, imune a reordenação. Este é o padrão sensato. - Não se conforme com um
varcharpuro — defina um tipoENUMreal do Postgres para que o próprio banco rejeite valores inválidos. - Um
AttributeConverterpersiste um código estável, desacoplado do nome Java, então renomear deixa de ser um problema de banco de dados. - Uma tabela de lookup só vale a pena quando os valores carregam dados de negócio editáveis — não como solução para renomeações.
O Cenário
Estamos construindo gestão de pedidos. Um pedido atravessa um ciclo de vida fixo:
stateDiagram-v2
[*] --> PENDING
PENDING --> PAID
PENDING --> CANCELLED
PAID --> SHIPPED
SHIPPED --> DELIVERED
PAID --> CANCELLED
Em Java, é um enum óbvio:
public enum OrderStatus {
PENDING,
PAID,
SHIPPED,
DELIVERED,
CANCELLED
}
A entidade de pedido tem um campo status. A única questão é como o Hibernate o mapeia para uma
coluna — e essa única escolha de anotação tem consequências que sobrevivem ao código que você escreve
hoje.
Parte 1 — @Enumerated(ORDINAL): Armazenar como Int
O default do JPA para um enum é ORDINAL. Cada constante é armazenada como a sua posição na
declaração: PENDING → 0, PAID → 1, SHIPPED → 2, e assim por diante.
@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
);
Salve um pedido com status PAID e a coluna conterá 1. É compacto e, no papel, está tudo ok.
❌ A Armadilha: Inserir um Valor no Meio
O ordinal não é armazenado como um rótulo — é armazenado como uma posição, e a posição é definida pela ordem no código-fonte. No dia em que alguém adiciona uma etapa de empacotamento entre pago e enviado:
public enum OrderStatus {
PENDING,
PAID,
PACKED, // <-- inserted here
SHIPPED,
DELIVERED,
CANCELLED
}
…toda constante depois de PAID desloca uma posição:
| Constante | Ordinal antes | Ordinal depois |
|---|---|---|
PENDING |
0 | 0 |
PAID |
1 | 1 |
PACKED |
— | 2 |
SHIPPED |
2 | 3 |
DELIVERED |
3 | 4 |
CANCELLED |
4 | 5 |
Nada no banco de dados mudou. Todo pedido SHIPPED existente ainda contém o inteiro 2 — mas 2
agora decodifica para PACKED. Pedidos enviados viram silenciosamente empacotados. Entregue vira
enviado. Não há erro, nem migração que falhou, nem linha de log. Os dados não se moveram; a sua
interpretação deles, sim. Você descobre quando um cliente pergunta por que o pedido dele, já entregue,
diz que está sendo empacotado.
A Salvaguarda: Fixe os Ordinais
Se você tem um motivo para manter ORDINAL — um schema legado, uma tabela genuinamente quente e
enorme em que a diferença de bytes importa — então torne explícito que a ordenação sustenta os dados,
com um teste que falha no instante em que alguém reordena o enum:
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);
}
}
É um teste de unidade puro — sem contexto Spring, sem banco de dados. Ele transforma um bug invisível
de corrupção de dados em um build vermelho no instante em que alguém mexe no enum. Novos valores
continuam permitidos; eles só precisam ir para o fim, onde acrescentar é seguro. Essa é a regra
inteira da qual o ORDINAL depende silenciosamente, escrita e registrada.
Parte 2 — @Enumerated(STRING): Armazenar como Varchar
A correção para quase todo mundo é uma palavra:
@Enumerated(EnumType.STRING)
@Column(nullable = false)
private OrderStatus status;
Agora a coluna armazena o nome da constante:
CREATE TABLE orders_string (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
status VARCHAR NOT NULL
);
Um pedido PAID armazena a string literal 'PAID'. Três coisas melhoram imediatamente:
- Reordenar é inofensivo. O valor é o próprio nome; posições não importam mais. Adicione
PACKEDonde quiser. - Dá para depurar.
SELECT * FROM orders_string WHERE status = 'PAID'lê-se como inglês. Sem tabela de decodificação e sem precisar consultar o código Java de cabeça. - Dumps e logs são autodescritivos. Uma linha em um export CSV significa algo por si só.
Sim, 'DELIVERED' custa mais bytes que 3. Para a esmagadora maioria das tabelas, essa diferença é
ruído — e você sempre pode adicionar um índice. Armazenar o nome é o default certo, e “compacto”
quase nunca vale “silenciosamente errado”.
A Armadilha que Restou: Renomeações
O STRING remove a armadilha da ordenação, mas introduz uma menor. O valor armazenado é o
identificador Java, então renomear a constante deixa as linhas existentes órfãs:
PENDING → AWAITING_PAYMENT
Toda linha 'PENDING' antiga deixa de corresponder a qualquer constante, e o Hibernate lança exceção
ao lê-la de volta. Os dados armazenados e o código se distanciaram silenciosamente. Você pode corrigir
isso com uma migração de dados (UPDATE … SET status = 'AWAITING_PAYMENT' WHERE status = 'PENDING') —
e essa é uma resposta perfeitamente aceitável. Também veremos, na Parte 4, uma maneira de transformar
renomeações em algo totalmente indolor.
Parte 3 — Do Jeito Certo: Um Tipo Enum Real do Postgres
Ambas as opções acima armazenam em uma coluna que o banco não entende de verdade — um smallint ou um
varchar que por acaso contém valores de enum. O Postgres pode fazer melhor. Ele tem tipos enum de
primeira classe:
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
);
Agora o banco impõe o domínio. Um INSERT … VALUES ('SHPPED') — um typo, uma migração ruim, um
script fora de controle — falha na origem com invalid input value for enum order_status. Com um
varchar puro, esse lixo entra na tabela e você o descobre depois. O tipo enum é documentação e
constraint em um só lugar: o tipo da coluna literalmente lista os seus valores legais.
Mapeá-lo no Hibernate é o mesmo @Enumerated(STRING) de antes — o Hibernate vincula o nome da
constante como string e o Postgres o armazena no enum:
@Enumerated(EnumType.STRING)
@Column(nullable = false, columnDefinition = "order_status")
private OrderStatus status;
Há exatamente uma peça de configuração. Por padrão, o driver JDBC do PostgreSQL envia uma String
Java como tipo varchar, e o Postgres não faz cast implícito de varchar → order_status, então
você receberia column "status" is of type order_status but expression is of type character varying.
Adicione stringtype=unspecified à URL JDBC e o driver envia o valor como unknown, permitindo que
o Postgres faça o cast para o enum:
spring:
datasource:
url: jdbc:postgresql://localhost:5434/mydatabase?stringtype=unspecified
(O Hibernate 6 também oferece @JdbcTypeCode(SqlTypes.NAMED_ENUM) para mirar um tipo enum nomeado
diretamente; a combinação @Enumerated(STRING) + stringtype=unspecified acima é a mais comum e a
que eu uso.)
A única ressalva a saber: ALTER TYPE order_status ADD VALUE 'PACKED' apenas acrescenta. Você
pode adicionar um valor (e, desde o PostgreSQL 12, até antes/depois de um específico), mas não pode
remover nem reordenar valores existentes sem recriar o tipo. Isso parece limitador até você perceber
que é a mesma regra que o teste do ordinal impunha — nunca reordene, apenas adicione — exceto que
aqui o banco a garante em vez de um teste de unidade. A constraint é a funcionalidade.
Parte 4 — AttributeConverter: Desacople o Nome do Valor
A armadilha da renomeação da Parte 2 existe porque deixamos o valor armazenado e o identificador
Java serem a mesma string. Um AttributeConverter do JPA quebra esse acoplamento: você persiste um
código estável que não tem nada a ver com o nome da constante.
Dê a cada constante um código explícito e permanente:
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));
}
}
Depois, um conversor que mapeia enum ↔ código:
@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);
}
}
E ligue-o no campo com @Convert em vez de @Enumerated:
@Convert(converter = OrderStatusConverter.class)
@Column(nullable = false)
private OrderStatus status;
Agora o banco armazena 'PAID' como código, não como identificador. Renomeie a constante Java
PENDING para AWAITING_PAYMENT e o código armazenado 'PND' nunca muda — a renomeação é uma
refatoração pura, com zero impacto no banco. Você desacoplou o que o banco conhece de como você chama
as coisas no código, que é exatamente a propriedade pela qual as pessoas recorrem a tabelas de
lookup. Guarde isso para a próxima parte.
Parte 5 — A Abordagem de Tabela de Lookup
A última abordagem deixa de tratar o status como um enum. Em vez disso, o conjunto de status vive em uma tabela própria, e os pedidos referenciam uma linha por chave estrangeira:
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)
);
No JPA, o status vira um relacionamento, não um valor enumerado:
@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;
}
Para saber qual status um pedido tem — o rótulo humano, se ele é terminal — você faz join:
SELECT o.id, s.code, s.label
FROM orders_lookup o
JOIN order_statuses s ON s.id = o.status_id
WHERE o.id = ?;
✅ Quando Isso Vale o Investimento
A tabela de lookup compra uma coisa real: o conjunto de valores, e os metadados anexados a cada um, passa a viver em dados em vez de em código. Isso é genuinamente valioso quando:
- Cada valor carrega dados de negócio editáveis — um rótulo de exibição, uma ordem de classificação, uma cor, um feature flag, um SLA. O status não é só uma identidade; é um pequeno registro.
- Pessoas não desenvolvedoras gerenciam os valores, ou eles são configurados por tenant, ou mudam em runtime sem deploy.
- Você tem mudanças em massa genuínas — renomear um rótulo que aparece em milhões de linhas
atualizando uma única linha em
order_statuses, não todo pedido.
Esse último ponto é o argumento mais forte: mude em um lugar, não em todos. Se o seu “enum” é, na verdade, um catálogo mantido, este é o modelo certo.
Minha Opinião
Para um enum simples — um conjunto fixo de estados no nível do código, como o ciclo de vida de um pedido — eu não uso tabela de lookup e argumentaria contra ela em um code review.
A justificativa que normalmente ouço é “e se precisarmos renomear um valor?”. Mas acabamos de ver que
isso se resolve sem tabela: um AttributeConverter desacopla o código armazenado do nome Java, e um
rótulo que muda é uma migração de uma linha. Você não precisa de uma chave estrangeira e de um join
em toda query para sobreviver a uma renomeação.
O que a tabela de lookup realmente adiciona, nesse caso, é custo permanente: toda leitura faz join ou
carrega uma segunda query, o status vira um relacionamento gerenciado em vez de um valor, e um
switch exaustivo em tempo de compilação sobre os seus estados vira uma consulta em runtime que pode
falhar. Você trocou um valor que o seu compilador entende por uma linha que ele não entende, para
comprar uma flexibilidade que um ciclo de vida fixo nunca usa.
Então a minha regra é sobre o que o valor é, não sobre renomeações:
- Se o valor é apenas identidade — é
SHIPPED, ponto final — mantenha-o como enum. Mapeie com@Enumerated(STRING), respalde-o com um tipo enum do Postgres e recorra a umAttributeConverterquando quiser que renomeações sejam gratuitas. - Se o valor é um registro — tem campos que são editados, por pessoas, em runtime — então ele nunca foi realmente um enum. Dê uma tabela a ele.
Renomear não é o fator decisivo. O fator decisivo é se a coisa tem dados próprios.
Guia de Decisão
| Abordagem | Armazena | Use quando | Risco principal |
|---|---|---|---|
@Enumerated(ORDINAL) |
posição (1) |
quase nunca | reordenar corrompe linhas silenciosamente |
@Enumerated(STRING) |
nome da constante ('PAID') |
o padrão sensato | renomeações deixam linhas órfãs |
Tipo ENUM do Postgres |
nome, validado pelo banco | você quer que o banco rejeite valores inválidos | ADD VALUE apenas acrescenta |
AttributeConverter |
código estável ('PAID') |
você quer renomeações gratuitas | uma pequena classe para manter |
| Tabela de lookup | FK para uma linha | valores carregam dados editáveis | um join em toda leitura |
Um default sólido para a maioria dos projetos: @Enumerated(STRING) sobre um tipo enum do
Postgres, migrando para um AttributeConverter no momento em que você quiser o valor armazenado
isolado do nome Java.
Código
O código deste artigo está disponível em
github.com/javaAndScriptDeveloper/enums-article —
o mesmo enum OrderStatus persistido das cinco maneiras, o teste de fixação dos ordinais e um teste
de round-trip por abordagem, que verifica o que cada uma realmente grava no disco. Tudo roda
localmente com Docker e um único ./gradlew test.
Considerações Finais
Escolher como armazenar um enum parece uma decisão de cinco segundos, e é exatamente por isso que vale a pena desacelerar. A armadilha do ordinal, a cilada da renomeação, a constraint ausente no banco — nenhuma delas aparece no dia em que você escreve a anotação. Elas aparecem no dia em que o conjunto de valores muda, o que sempre acontece, geralmente muito depois de você ter esquecido o trade-off que fez.
A boa notícia é que os defaults são fáceis: armazene o nome, deixe o banco validá-lo e desacople o código do identificador quando precisar. Reserve a tabela de lookup para os casos que são genuinamente um catálogo, e não um enum. Acerte isso uma vez e os seus status continuam entediantes — o que é o maior elogio que uma coluna pode receber.
Vamos Conversar
Se você armazena enums de forma diferente — ou foi queimado por uma dessas armadilhas de um modo que eu não cobri — eu gostaria de saber. Os links de contato estão no rodapé.
Perguntas frequentes
Devo usar @Enumerated ORDINAL ou STRING?
Use STRING. O @Enumerated(ORDINAL) armazena a posição do enum (0, 1, 2…), então inserir uma nova constante em qualquer lugar que não seja o fim faz todas as linhas existentes passarem a apontar, em silêncio, para outro valor. O @Enumerated(STRING) armazena o nome da constante (‘PAID’), que é autodescritivo, fácil de depurar direto no SQL e imune a reordenação. Os poucos bytes extras de armazenamento são irrelevantes perto da segurança.
O que quebra quando adiciono um valor de enum no meio com ORDINAL?
Toda linha armazenada depois da constante inserida passa a decodificar para o valor errado. Se SHIPPED era o ordinal 2 e você insere PACKED antes dele, SHIPPED vira 3 — mas todas as linhas existentes ainda guardam o inteiro 2, que agora lê-se como PACKED. O banco não muda; a sua interpretação dele muda. Proteja-se com um teste de unidade que fixe o ordinal() de cada constante.
Como armazenar um enum como um tipo enum do Postgres?
Crie o tipo com CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', …), defina a coluna com esse tipo e mapeie no Hibernate com @Enumerated(EnumType.STRING). Adicione stringtype=unspecified à URL JDBC para que o driver envie o valor como unknown e o Postgres possa fazer o cast de string → enum. O banco então rejeita qualquer valor fora do enum.
Como renomear uma constante de enum sem quebrar as linhas existentes?
Desacople o valor armazenado do identificador Java. Com um AttributeConverter do JPA você persiste um código estável (‘PAID’) em vez do nome da constante, então renomear PENDING para AWAITING_PAYMENT é uma mudança puramente de código — sem migração, sem linhas órfãs. É por isso que raramente você precisa de uma tabela de lookup apenas para sobreviver a renomeações.
Quando devo usar uma tabela de lookup em vez de @Enumerated?
Quando os valores carregam dados de negócio editáveis, e não apenas identidade — um rótulo exibido aos usuários, uma ordem de classificação, um feature flag — ou quando pessoas não desenvolvedoras precisam adicioná-los/editá-los em runtime. Se o enum é um conjunto fixo de estados no nível do código, uma tabela de lookup praticamente só adiciona um join e uma indireção por uma flexibilidade que você nunca vai usar.