Menu

Tipos enum no PostgreSQL: CREATE TYPE AS ENUM

Um tipo enum é uma lista fixa e ordenada de valores permitidos, criada com CREATE TYPE ... AS ENUM. Como adicionar e renomear valores, listar, ordenar e quando uma restrição CHECK é a melhor escolha.

Esta página tem editores executáveis. Edite, execute e veja a saída na hora.

Um enum é um tipo de dado cujos valores vêm de uma lista fixa que você declara: CREATE TYPE name AS ENUM ('a', 'b', 'c'). Uma coluna desse tipo só aceita esses rótulos e os ordena na ordem declarada, não em ordem alfabética.

As linhas voltam na ordem new, paid, shipped, delivered. Inserir um rótulo que não está na lista, como 'lost', falha com invalid input value for enum order_status: "lost".

Comparar e filtrar por posição

Como os valores são ordenados, <, > e BETWEEN comparam posições na lista. "Pago ou qualquer status posterior" vira uma única condição:

Os pedidos 1, 3 e 4 batem. min(status) e max(status) também seguem a ordem declarada.

Listar os valores de um enum

enum_range(NULL::type) retorna todos os rótulos como um array, e unnest transforma esse array em linhas:

enum_first(NULL::mood) e enum_last(NULL::mood) retornam o primeiro e o último rótulo. No psql, \dT+ mood mostra o tipo com seus valores.

Adicionar ou renomear um valor

ALTER TYPE ... ADD VALUE acrescenta um rótulo no fim, ou o posiciona com BEFORE ou AFTER. RENAME VALUE muda um rótulo, e todas as linhas que o usam acompanham, porque as linhas guardam uma referência ao rótulo e não o texto dele.

A lista agora é pending, paid, packed, shipped, delivered. Com IF NOT EXISTS, adicionar um rótulo que já existe não faz nada.

O PostgreSQL não consegue remover um valor nem reordenar os existentes. Em vez disso, crie um tipo novo, converta a coluna para ele e remova o antigo:

CREATE TYPE order_status_new AS ENUM ('pending', 'paid', 'shipped');
UPDATE orders SET status = 'shipped' WHERE status = 'delivered';
ALTER TABLE orders
    ALTER COLUMN status DROP DEFAULT,
    ALTER COLUMN status TYPE order_status_new USING status::text::order_status_new;
DROP TYPE order_status;
ALTER TYPE order_status_new RENAME TO order_status;

O valor padrão é removido antes porque ele tem o tipo do enum antigo. Defina de novo depois.

Enum vs restrição CHECK

Uma coluna text com uma restrição CHECK dá a mesma proteção, e a lista pode ser alterada com um ALTER TABLE comum:

Aqui a ordenação é alfabética: new e depois paid.

Enumtext + CHECK
OrdenaçãoOrdem declaradaAlfabética
Armazenamento4 bytesTamanho do texto
Remover um valorTipo novo e conversão da colunaTrocar a restrição
Reusar em várias tabelasUm único tipoRepetir a restrição

Escolha um enum para uma lista curta e estável cuja ordem tenha significado, como status ou tamanhos. Escolha CHECK, ou uma tabela de referência com uma chave estrangeira, quando a lista muda com frequência ou valores são removidos. O capítulo sobre enum do manual cobre os demais detalhes.

Perguntas frequentes

Como remover um valor de um enum no PostgreSQL?

Não existe ALTER TYPE ... DROP VALUE. Crie um enum novo sem o valor, converta a coluna com ALTER TABLE ... ALTER COLUMN ... TYPE new_type USING col::text::new_type depois de atualizar as linhas que usam o valor e então remova o tipo antigo.

Quanto espaço ocupa um valor enum?

4 bytes por valor em disco, seja qual for o tamanho do rótulo. Os rótulos diferenciam maiúsculas e podem ter até 63 bytes.

Posso usar ALTER TYPE ADD VALUE dentro de uma transação?

Pode, desde o PostgreSQL 12. O novo valor só pode ser usado depois do commit dessa transação.

Como comparar uma coluna enum com texto?

Um literal de string é convertido para o enum automaticamente, então WHERE status = 'paid' funciona. Uma coluna ou parâmetro de texto precisa de conversão, status = $1::order_status, ou compare como texto com status::text = $1.

Ilustração das linguagens de programação do Coddy

Aprenda a programar com o Coddy

Começar