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 IDENTITYrejeita um valor explícito noINSERT, a menos que o insert digaOVERRIDING SYSTEM VALUE. É o padrão mais seguro.GENERATED BY DEFAULT AS IDENTITYusa 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.