Menu

Chave primária no PostgreSQL: identity, SERIAL e UUID

Como definir uma chave primária no PostgreSQL e como gerá-la: colunas identity, o antigo SERIAL e UUIDs com gen_random_uuid(). Também chaves compostas e como resetar uma sequence.

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

Uma chave primária é a coluna, ou o conjunto de colunas, que identifica cada linha. Os valores precisam ser únicos e não NULL, e uma tabela só pode ter uma. No PostgreSQL, o comum é deixar o banco gerá-la com uma coluna identity: id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY.

Os ids são 1 e 2. Definir a chave também cria um índice único nela, chamado users_pkey.

Colunas identity: ALWAYS vs BY DEFAULT

Colunas identity são o jeito padrão do SQL para numerar linhas, disponíveis desde o PostgreSQL 10. Há duas formas:

  • GENERATED ALWAYS AS IDENTITY rejeita um valor explícito no INSERT, a menos que o insert diga OVERRIDING SYSTEM VALUE. É o padrão mais seguro.
  • GENERATED BY DEFAULT AS IDENTITY usa o valor gerado só quando você não informa um.

Com BY DEFAULT, inserir seus próprios ids deixa a sequence para trás, e o próximo id gerado colide. Depois de importar linhas com ids explícitos, avance a sequence para depois do maior id com setval:

Sem a linha do setval, o último insert receberia o id 1 e falharia com erro de chave duplicada. Com ela, a nova linha recebe 4.

SERIAL vs identity

serial (4 bytes) e bigserial (8 bytes) não são tipos de verdade. São um atalho que cria uma sequence e define o valor padrão da coluna como o nextval() dela:

A coluna é um integer comum com o valor padrão nextval('legacy_id_seq'::regclass). Nada impede um insert de gravar o próprio id, e a sequence precisa de permissões próprias. Colunas identity resolvem as duas coisas, então prefira-as em tabelas novas. serial continua funcionando, e você vai encontrá-lo em schemas e tutoriais antigos.

Use bigint (ou bigserial) em tabelas que podem crescer. Uma chave integer se esgota depois de uns 2,1 bilhões de valores.

Chaves primárias UUID

gen_random_uuid() retorna um UUID aleatório versão 4. Ele é nativo desde o PostgreSQL 13, então não precisa de extensão:

Cada execução mostra ids diferentes, com 36 caracteres cada em forma de texto. O tipo uuid os guarda em 16 bytes, então use-o em vez de text. O PostgreSQL 18 adiciona uuidv7(), que gera UUIDs ordenados por tempo que entram na ordem do índice. No PostgreSQL 17, gere esses UUIDs na aplicação.

Chaves primárias compostas

Uma chave pode abranger várias colunas, escrita numa linha própria do CREATE TABLE. É a chave natural de uma tabela de ligação, onde cada par pode aparecer uma vez:

O par repetido (1, 10) é ignorado, então a contagem é 3. Para adicionar uma chave a uma tabela existente, use ALTER TABLE t ADD PRIMARY KEY (col). A página de ALTER TABLE mostra as outras alterações. Outras tabelas apontam para a chave com chaves estrangeiras.

Perguntas frequentes

O PostgreSQL tem AUTO_INCREMENT?

Não com esse nome. O jeito padrão é uma coluna identity, id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, disponível desde o PostgreSQL 10. Os tipos antigos serial e bigserial fazem o mesmo com uma sequence e um valor padrão.

Por que a sequence de ids do PostgreSQL tem buracos?

Uma sequence entrega um valor mesmo quando o insert falha depois ou a transação faz rollback, e esse valor nunca é reutilizado. Buracos são normais e inofensivos, então não conte com ids consecutivos.

Uma chave primária cria um índice no PostgreSQL?

Sim. Uma chave primária (e toda restrição UNIQUE) cria automaticamente um índice B-tree único, chamado tablename_pkey no caso da chave primária.

Devo usar UUID ou bigint como chave primária?

Chaves identity bigint são menores (8 bytes contra 16) e entram na ordem do índice. UUIDs podem ser gerados em qualquer lugar sem consultar o banco e não revelam quantas linhas existem. UUIDs aleatórios espalham os inserts pelo índice, o que custa mais em tabelas grandes.

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

Aprenda a programar com o Coddy

Começar