Pular para o conteúdo
Setup do Dev
Guias

O id pulou de 8 para 12: por que a sequência do PostgreSQL tem buracos

Rollback, ON CONFLICT e insert que falha gastam números da sequência. Testamos cada caso e o contador que dá número sem buraco quando a lei exige.

Por Setup do Dev
4 min de leitura
Compartilhar
Capa cinza-azulada com o elefante do PostgreSQL, a manchete "O id que pulou números" e uma lista de ids 1, 2, 4, 6, 8, 12 com os buracos marcados.

A tabela de pedidos tem os ids 1, 2, 4, 6, 8 e 12, e ninguém apagou nada. A pergunta aparece em todo projeto que usa serial ou identity no PostgreSQL, e a resposta curta está na documentação das sequências: elas não servem para numeração sem buraco, por desenho.

Montamos o caso com uma tabela temporária no PostgreSQL 18.4, provocando cada buraco de propósito, e depois testamos o jeito de numerar sem pular quando isso é obrigatório, como na nota fiscal.

O teste

CREATE TEMPORARY TABLE pedido (
  id     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  codigo text UNIQUE NOT NULL,
  valor  numeric(10,2) NOT NULL CHECK (valor > 0)
);
INSERT INTO pedido (codigo, valor) VALUES ('A', 10), ('B', 20);

Os dois primeiros receberam 1 e 2. Daí em diante, cada operação abaixo deixou um buraco:

  • Rollback. Um INSERT dentro de uma transação desfeita levou o 3. O pedido seguinte recebeu 4.
  • Upsert que não inseriu. INSERT … ON CONFLICT (codigo) DO NOTHING com um código repetido não gravou nada e gastou o 5.
  • Insert recusado. Um valor negativo bateu no CHECK, e a própria mensagem de erro mostrou o número gasto: “Registro que falhou contém (7, F, -1.00)”.
  • Várias linhas de uma vez. Um INSERT de três linhas em que a terceira repetia um código falhou inteiro e levou o 9, o 10 e o 11. O pedido seguinte recebeu 12.
Linha com os números de 1 a 12. Ficaram na tabela os ids 1, 2, 4, 6, 8 e 12. O 3 foi gasto por um rollback, o 5 por um ON CONFLICT DO NOTHING, o 7 por um insert recusado pelo CHECK, e o 9, o 10 e o 11 por um insert de três linhas em que uma falhou.
Os seis pedidos gravados no teste e o que gastou cada número que falta

Por que é assim

Se o número voltasse para a fila quando a transação desfaz, cada INSERT teria de esperar o anterior terminar para saber se o número ficou com ele. A documentação diz exatamente isso: para não travar transações que pedem números ao mesmo tempo, o valor do nextval não é reaproveitado se a transação aborta, e o ON CONFLICT calcula a linha, com o nextval, antes de descobrir o conflito. Por isso o upsert gasta número mesmo quando não insere, assunto que já apareceu no guia do ON CONFLICT.

Há mais um caso que não reproduzimos: o cache de sequência. Com CACHE maior que 1, cada sessão reserva um lote de números, e o que ela não usa se perde quando a sessão termina. E há a queda do banco, que a documentação também lista entre as causas de buraco: o número entregue antes da queda não volta.

O contrário do buraco: a sequência que ficou para trás

O erro mais comum com sequência não é o buraco, é a colisão depois de uma importação. Gravamos três clientes com o id escrito à mão, numa coluna GENERATED BY DEFAULT AS IDENTITY, e o insert seguinte, sem id, falhou com “duplicar valor da chave viola a restrição de unicidade”: a sequência não sabia dos três e entregou o 1. O conserto é avisá-la de onde parar:

SELECT setval(pg_get_serial_sequence('cliente', 'id'), (SELECT max(id) FROM cliente));

Depois dele, o insert seguinte recebeu 4. Com GENERATED ALWAYS o banco recusa o id escrito à mão e pede OVERRIDING SYSTEM VALUE; usando a opção, a sequência também fica para trás (no teste, o id 10 entrou e o insert seguinte recebeu 1). Por isso, toda importação que traz o id termina com esse setval, de preferência no mesmo script que importa, para ninguém esquecer.

Quando o buraco não pode existir

Para chave primária, buraco não é problema: o id identifica a linha, e não conta nada. Se o que você quer é numerar uma lista na tela, quem faz isso é o row_number() na consulta, que deu 1 a 6 para os pedidos do teste sem mexer no id.

Quando a numeração é regra de negócio, como na nota fiscal ou no protocolo, a saída é um contador numa tabela comum, atualizado dentro da mesma transação que grava o documento:

CREATE TABLE contador (serie text PRIMARY KEY, ultimo bigint NOT NULL);

WITH c AS (
  UPDATE contador SET ultimo = ultimo + 1
  WHERE serie = 'nota-2026'
  RETURNING ultimo
)
INSERT INTO nota (numero, cliente) SELECT ultimo, 'Ana' FROM c;

No teste, gravamos a nota da Ana, desfizemos a da Bia e gravamos a do Caio. As notas saíram com os números 1 e 2, e o contador terminou em 2: o rollback desfez o UPDATE junto. Com uma sequência no mesmo roteiro, o terceiro nextval devolveu 3, e o 2 ficou perdido.

O preço é o que a sequência evita. O UPDATE trava a linha do contador até o fim da transação, e quem pedir o próximo número da mesma série espera, como descreve a documentação das travas. Por isso a transação que usa o contador deve ser curta: busque e valide tudo antes, e deixe o número para o fim. Uma série por ano ou por loja também divide a fila, porque cada série tem a sua própria linha no contador e a sua própria trava.

Fontes: Documentação do PostgreSQL: funções de sequência, Documentação do PostgreSQL: CREATE SEQUENCE, Documentação do PostgreSQL: travas explícitas

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. O teste
  2. Por que é assim
  3. O contrário do buraco: a sequência que ficou para trás
  4. Quando o buraco não pode existir

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.