Blog

Sequence que pula números e ID que acaba: cache de sequence, rollback, integer que estoura e a migração para bigint

Um varejista com 380 lojas mantinha os preços de cada loja numa tabela precos com 4,2 milhões de linhas, criada em 2019 com id serial. Ninguém imaginava que ela pudesse ficar sem ID: o count(*) estava a menos de 0,2% do limite de 2.147.483.647 de um integer. Mesmo assim, numa madrugada de sexta, a sincronização com o ERP começou a falhar com "reached maximum value of sequence" e nenhum preço novo entrou nas lojas. A causa era um deploy de 17 dias antes, que trocou a sincronização incremental diária por uma carga completa a cada hora com INSERT ... ON CONFLICT DO UPDATE. Cada linha proposta consome um valor da sequência, mesmo quando vira UPDATE. A correção de emergência também tropeçou: o plantão migrou a coluna para bigint e o erro continuou, porque a sequência de um serial não muda junto. Depois vieram a chave estrangeira em integer, o serviço Java que lia o id com getInt e a API em Node que passou a receber o id como string. Este artigo explica o que consome uma sequência além das linhas inseridas, onde o limite de 32 bits se esconde fora da coluna da chave primária, como medir o consumo real antes do erro e como corrigir sem trocar um incidente por outro.

2026-11-20 / Arquitetura / 12 min

01

A tabela de 4,2 milhões de linhas que ficou sem ID

A sincronização antiga recebia do ERP só os preços alterados no dia, cerca de 200 mil linhas, e fazia um upsert com elas. Em cinco anos, a sequência tinha chegado a 430 milhões, um número alto para uma tabela de 4,2 milhões de linhas, mas ainda longe do limite. A refatoração de setembro simplificou o processo: o ERP passou a exportar o catálogo inteiro de preços a cada hora e o job fazia upsert de tudo, porque era idempotente e dispensava controlar o que tinha mudado. O consumo saltou de 200 mil para 100,8 milhões de valores por dia, e os 1,7 bilhão restantes duraram 17 dias.

D-17       deploy: sincronização de preços passa de diária e incremental para horária e completa
           (4,2 milhões de linhas por hora com ON CONFLICT DO UPDATE: 100,8 milhões de nextval por dia)
D0  03:12  nextval: reached maximum value of sequence "precos_id_seq"; nenhum preço novo entra
D0  03:40  plantão roda ALTER TABLE precos ALTER COLUMN id TYPE bigint (41 s com a tabela bloqueada)
D0  04:05  o mesmo erro volta: a sequência do serial continua AS integer
D0  04:20  ALTER SEQUENCE precos_id_seq AS bigint; a sincronização volta a rodar
D0  04:21  gatilho de historico_precos falha: integer out of range (preco_id é integer)
D0  05:10  historico_precos.preco_id migrada para bigint (9 min de tabela bloqueada)
D0  09:00  serviço de catálogo em Java: Bad value for type int : 2147483651
D0  11:30  API em Node: cache de preços deixa de casar, porque o id passou a chegar como string
D1         sincronização reescrita: consumo cai de 100,8 milhões para cerca de 180 mil valores por dia

Nenhum monitoramento acusou nada antes, porque todos olhavam para a tabela: tamanho em disco, quantidade de linhas, crescimento diário. Todos estáveis. O único número que importava, o last_value da sequência, não estava em nenhum painel. E cada etapa da correção revelou um lugar diferente onde o mesmo limite de 32 bits estava gravado.

02

Quem consome a sequência além das linhas inseridas

Uma sequência não sabe se o valor que entregou virou linha. O nextval é chamado quando o valor default da coluna é avaliado, e a partir daí o valor está gasto, aconteça o que acontecer com a transação. No INSERT ... ON CONFLICT, o default é avaliado para cada linha proposta antes de o Postgres verificar o conflito, então um upsert que só atualiza linhas existentes consome a sequência exatamente como se estivesse inserindo.

CREATE TABLE precos (
  id      serial PRIMARY KEY,
  loja_id integer       NOT NULL,
  sku     text          NOT NULL,
  valor   numeric(12,2) NOT NULL,
  UNIQUE (loja_id, sku)
);

-- Duas linhas novas: a sequência entrega 1 e 2.
INSERT INTO precos (loja_id, sku, valor) VALUES (1, 'A', 10.00), (1, 'B', 20.00);
SELECT last_value FROM precos_id_seq;          -- 2

-- As mesmas duas chaves de novo, só com um preço diferente. Nenhuma linha nova:
-- O default de id é avaliado antes da checagem de conflito, para toda linha proposta.
INSERT INTO precos (loja_id, sku, valor) VALUES (1, 'A', 10.00), (1, 'B', 21.00)
ON CONFLICT (loja_id, sku) DO UPDATE SET valor = excluded.valor;
SELECT last_value FROM precos_id_seq;          -- 4

-- A tabela continua com 2 linhas; a sequência já gastou 4 valores.
SELECT count(*), max(id) FROM precos;          -- 2 | 2

-- serial cria a sequência AS integer desde o PostgreSQL 10.
SELECT data_type, max_value FROM pg_sequences WHERE sequencename = 'precos_id_seq';
 data_type | max_value
-----------+------------
 integer   | 2147483647
Origem do consumoValores gastosQuando vira problema
INSERT que vira linha1 por linhaSó em tabelas realmente grandes ou de eventos
INSERT ... ON CONFLICT DO UPDATE ou DO NOTHING1 por linha proposta, inclusive as que já existiamUpsert periódico do conjunto inteiro, como sincronização de catálogo
INSERT que falha ou transação com ROLLBACK1 por linha tentadaRetentativas em laço, validação feita depois do INSERT
CACHE n na sequênciaAté n por sessão encerradaCACHE alto com conexões de vida curta, como funções serverless
Crash ou failoverAté 32 por sequênciaRaramente relevante para o limite, só para buracos

A razão entre last_value e count(*) é o indicador mais útil aqui. Na tabela precos, ela era 102 antes do deploy e passou de 500 no dia do incidente. Uma tabela em que essa razão passa de 10 tem algum padrão de escrita que gasta a sequência sem gerar linha, e esse padrão define quando o ID acaba, não o tamanho da tabela.

03

Migrar a coluna não basta: a sequência do serial continua integer

Desde o PostgreSQL 10, serial cria a sequência com AS integer, e o máximo dela é 2.147.483.647 independentemente do tipo da coluna. ALTER TABLE ... ALTER COLUMN id TYPE bigint reescreve a tabela e os índices, mas não toca na sequência de um serial, que é um objeto separado ligado à coluna só por dependência. Colunas GENERATED AS IDENTITY se comportam diferente: ao mudar o tipo da coluna, o Postgres ajusta junto o tipo da sequência interna. Como a mesma base costuma ter tabelas criadas em épocas diferentes, com serial e com identity, o seguro é sempre conferir em pg_sequences depois da migração.

ERROR:  nextval: reached maximum value of sequence "precos_id_seq" (2147483647)

-- A coluna vira bigint (reescreve a tabela inteira)...
ALTER TABLE precos ALTER COLUMN id TYPE bigint;

-- ...mas a sequência de um serial continua integer e o nextval segue falhando.
SELECT data_type, max_value, last_value
  FROM pg_sequences WHERE sequencename = 'precos_id_seq';
 data_type | max_value  | last_value
-----------+------------+------------
 integer   | 2147483647 | 2147483647

-- Só a sequência precisa mudar: catálogo, sem reescrever nada.
ALTER SEQUENCE precos_id_seq AS bigint;

-- O máximo era o do tipo antigo, então acompanha o tipo novo.
SELECT data_type, max_value FROM pg_sequences WHERE sequencename = 'precos_id_seq';
 data_type |      max_value
-----------+---------------------
 bigint    | 9223372036854775807

SELECT nextval('precos_id_seq');               -- 2147483648

No incidente, os 41 segundos de tabela bloqueada da reescrita foram desnecessários para destravar a escrita. Para uma sequência que estoura com a coluna já em bigint, o ALTER SEQUENCE ... AS bigint resolve sozinho e é instantâneo. Se a coluna ainda for integer e a tabela for grande demais para uma reescrita de emergência, existe um recurso de último caso: ALTER SEQUENCE ... MINVALUE -2147483648 RESTART WITH -2147483648 dá mais 2,1 bilhões de valores negativos enquanto a migração para bigint é feita com calma. Só use se a aplicação aceitar ids negativos, o que vale testar antes, não durante o incidente.

04

Onde mais o limite de 32 bits se esconde

O id não mora só na chave primária. Ele é copiado para chaves estrangeiras, gatilhos de histórico, tabelas de auditoria, mensagens de fila, caches e tipos da aplicação. Cada cópia criada quando o id era integer continua com o limite antigo, e cada uma falha no primeiro valor acima de 2.147.483.647, em horários diferentes, com mensagens diferentes.

LugarComo falhaCorreção
Sequência AS integer de um serialnextval: reached maximum value of sequenceALTER SEQUENCE ... AS bigint
Chave estrangeira integer apontando para bigintinteger out of range no INSERT da tabela filhaMigrar a coluna filha para bigint
Coluna que guarda o id sem FK (auditoria, jsonb, filas)integer out of range ou valor truncado no consumidorMigrar a coluna e o schema da mensagem
Java ou Kotlin com int, ResultSet.getIntBad value for type intlong e getLong
C# com int, Go com int32, Protobuf int32Overflow ou exceção na conversãolong, int64, int64
Node com node-postgresint8 chega como string; comparações estritas e chaves de Map deixam de casarParser explícito para int8 ou tratar ids como string
JavaScript no navegador ou JSONPerde precisão acima de 2^53 - 1Serializar ids como string a partir de bigint

O caso do Node é o mais traiçoeiro, porque não dá erro. O node-postgres converte int4 para Number, mas devolve int8 como string, para não perder precisão acima de 2^53 - 1. Depois da migração, a mesma consulta passou a devolver "2147483651" em vez de um número, e o cache de preços, um Map indexado pelo id numérico vindo da URL, deixou de encontrar qualquer entrada. Um parser explícito torna a decisão visível no código, em vez de depender do tipo da coluna no banco.

import pg from 'pg';

// node-postgres devolve int8 como string por padrão, para não perder precisão.
// Converte para Number, mas falha alto em vez de arredondar acima de 2^53 - 1.
pg.types.setTypeParser(pg.types.builtins.INT8, (valor) => {
  const numero = Number(valor);
  if (!Number.isSafeInteger(numero)) {
    throw new RangeError(`int8 fora do intervalo seguro de Number: ${valor}`);
  }
  return numero;
});

05

Medir antes do erro: percentual, consumo por dia e tipos desalinhados

O monitoramento que faltou não é complicado. pg_sequences mostra o último valor e o máximo de cada sequência, mas o percentual sozinho não basta: 40% pode significar dez anos ou dez dias. O script abaixo guarda uma foto diária de todas as sequências, calcula o consumo por dia e os dias restantes e, na mesma execução, lista sequências com tipo diferente da coluna que alimentam e chaves estrangeiras com tipo diferente da chave referenciada.

// monitorar-sequencias.js
// node monitorar-sequencias.js  (rodar 1x por dia; sai com código 1 se houver risco)
import pg from 'pg';

const LIMITE_PCT = 75;
const LIMITE_DIAS = 90;
const client = new pg.Client({ connectionString: process.env.DATABASE_URL });

// Cada execução guarda uma foto de todas as sequências para calcular o consumo diário.
const SQL_FOTO = `
  CREATE TABLE IF NOT EXISTS monitor_sequencias (
    capturado_em timestamptz NOT NULL DEFAULT now(),
    sequencia    text        NOT NULL,
    ultimo_valor bigint      NOT NULL
  );
  INSERT INTO monitor_sequencias (sequencia, ultimo_valor)
  SELECT format('%I.%I', schemaname, sequencename), last_value
    FROM pg_sequences
   WHERE last_value IS NOT NULL`;

// Percentual usado e consumo por dia, comparando com a foto de ~1 dia atrás.
const SQL_CONSUMO = `
  WITH atual AS (
    SELECT format('%I.%I', schemaname, sequencename) AS sequencia,
           data_type::text AS tipo, last_value, max_value
      FROM pg_sequences
     WHERE last_value IS NOT NULL AND increment_by > 0
  ),
  anterior AS (
    SELECT DISTINCT ON (sequencia) sequencia, capturado_em, ultimo_valor
      FROM monitor_sequencias
     WHERE capturado_em BETWEEN now() - interval '8 days' AND now() - interval '20 hours'
     ORDER BY sequencia, capturado_em DESC
  )
  SELECT a.sequencia, a.tipo,
         a.last_value::text AS ultimo, a.max_value::text AS maximo,
         round(100.0 * a.last_value / a.max_value, 2)::float8 AS pct,
         round((a.last_value - p.ultimo_valor)
               / (extract(epoch FROM now() - p.capturado_em) / 86400))::float8 AS por_dia
    FROM atual a
    LEFT JOIN anterior p USING (sequencia)
   ORDER BY pct DESC`;

// Sequência de tipo diferente da coluna que ela alimenta (serial migrado pela metade).
const SQL_SEQUENCIA_X_COLUNA = `
  SELECT d.refobjid::regclass::text AS tabela, a.attname AS coluna,
         format_type(a.atttypid, a.atttypmod) AS tipo_coluna,
         s.seqrelid::regclass::text AS sequencia,
         s.seqtypid::regtype::text AS tipo_sequencia
    FROM pg_sequence s
    JOIN pg_depend d    ON d.objid = s.seqrelid
                       AND d.classid = 'pg_class'::regclass
                       AND d.refclassid = 'pg_class'::regclass
                       AND d.deptype IN ('a', 'i')
    JOIN pg_attribute a ON a.attrelid = d.refobjid AND a.attnum = d.refobjsubid
   WHERE s.seqtypid <> a.atttypid`;

// Chave estrangeira com tipo diferente da chave que ela referencia.
const SQL_FK_DESALINHADA = `
  SELECT con.conname AS fk,
         con.conrelid::regclass::text  || '.' || af.attname AS coluna_filha,
         format_type(af.atttypid, af.atttypmod) AS tipo_filha,
         con.confrelid::regclass::text || '.' || ap.attname AS coluna_pai,
         format_type(ap.atttypid, ap.atttypmod) AS tipo_pai
    FROM pg_constraint con
    CROSS JOIN LATERAL unnest(con.conkey, con.confkey) AS k(filha, pai)
    JOIN pg_attribute af ON af.attrelid = con.conrelid  AND af.attnum = k.filha
    JOIN pg_attribute ap ON ap.attrelid = con.confrelid AND ap.attnum = k.pai
   WHERE con.contype = 'f' AND af.atttypid <> ap.atttypid`;

async function main() {
  await client.connect();
  try {
    await client.query(SQL_FOTO);
    const { rows: sequencias } = await client.query(SQL_CONSUMO);

    const relatorio = sequencias.map((s) => {
      const restante = Number(s.maximo) - Number(s.ultimo);
      // Sem foto anterior ainda: só o percentual vale nesta execução.
      const dias = s.por_dia > 0 ? Math.floor(restante / s.por_dia) : null;
      const risco = s.pct >= LIMITE_PCT || (dias !== null && dias <= LIMITE_DIAS);
      return { ...s, dias_restantes: dias, risco };
    });
    console.table(relatorio.filter((s) => s.risco || s.pct >= 10));

    const { rows: desalinhadas } = await client.query(SQL_SEQUENCIA_X_COLUNA);
    const { rows: fks } = await client.query(SQL_FK_DESALINHADA);
    if (desalinhadas.length) console.table(desalinhadas);
    if (fks.length) console.table(fks);

    if (relatorio.some((s) => s.risco) || desalinhadas.length || fks.length) {
      process.exitCode = 1;
    }
  } finally {
    await client.end();
  }
}

main().catch((erro) => {
  console.error(erro);
  process.exit(1);
});
  • Rode uma vez por dia, no agendador que já existir, e trate o código de saída 1 como alerta. Um limite de 90 dias dá tempo de planejar a migração sem pressa.
  • pg_sequences só mostra last_value para sequências em que o usuário tem permissão de leitura. Rode com um papel que tenha USAGE ou SELECT em todas, ou o relatório fica incompleto sem avisar.
  • Mudança brusca de consumo é sinal tão importante quanto o percentual. Comparar o por_dia com a média da semana anterior teria apontado o deploy de setembro no dia seguinte.
  • As duas checagens de tipo valem como teste de migração: rodar o script no CI contra um banco migrado impede que um serial ou uma FK em integer passem despercebidos.

06

Corrigir sem trocar um incidente por outro

A ordem dos passos define quanto tempo a escrita fica parada e quantos incidentes novos a correção cria. O que funcionou, refeito do jeito certo, foi este:

  1. Destravar a escrita com o menor comando possível: ALTER SEQUENCE ... AS bigint se a coluna já for bigint; reescrita da coluna só se a tabela for pequena; ids negativos como último recurso.
  2. Antes de liberar o tráfego, listar todas as colunas que recebem esse id: chaves estrangeiras pela consulta do script, gatilhos e funções pelo código-fonte, colunas sem FK pelo nome e pelo conhecimento do domínio.
  3. Migrar as colunas filhas pequenas na hora e planejar as grandes com coluna nova, gatilho e backfill, enquanto o id ainda tem margem.
  4. Auditar os consumidores do id na aplicação: getInt, int32, schemas de mensagem e parsers de banco. Um teste de integração que insere uma linha com id 2.147.483.648 encontra todos de uma vez.
  5. Corrigir a fonte do consumo, para que a próxima sequência não chegue ao limite pelo mesmo motivo.

O último passo é o que de fato resolve. A sincronização foi reescrita para separar o que muda do que é novo: UPDATE só nas linhas cujo preço mudou e INSERT só das chaves que não existem. O ON CONFLICT continua, mas só dispara na corrida rara entre duas execuções. O consumo caiu de 100,8 milhões para cerca de 180 mil valores por dia, e como bônus o UPDATE com IS DISTINCT FROM deixou de gerar 4,2 milhões de tuplas mortas por hora, o que também aliviou o autovacuum.

-- A carga horária do ERP chega inteira nesta tabela de staging.
CREATE UNLOGGED TABLE IF NOT EXISTS precos_staging (
  loja_id integer       NOT NULL,
  sku     text          NOT NULL,
  valor   numeric(12,2) NOT NULL
);

BEGIN;

-- Atualiza só o que mudou: não consome sequência e não gera tupla morta à toa.
UPDATE precos p
   SET valor = s.valor
  FROM precos_staging s
 WHERE p.loja_id = s.loja_id
   AND p.sku = s.sku
   AND p.valor IS DISTINCT FROM s.valor;

-- Insere só o que é novo. O ON CONFLICT fica para a corrida rara entre dois processos.
INSERT INTO precos (loja_id, sku, valor)
SELECT s.loja_id, s.sku, s.valor
  FROM precos_staging s
 WHERE NOT EXISTS (
         SELECT 1 FROM precos p
          WHERE p.loja_id = s.loja_id AND p.sku = s.sku
       )
ON CONFLICT (loja_id, sku) DO NOTHING;

TRUNCATE precos_staging;

COMMIT;

Para tabelas novas, a regra que evita todo o resto é simples: chave primária bigint GENERATED ALWAYS AS IDENTITY, chaves estrangeiras bigint e long ou int64 na aplicação. Os 4 bytes economizados por linha com integer não pagam nem uma madrugada como essa.

FAQ

Perguntas frequentes

Posso usar CYCLE para a sequência voltar ao início quando chegar ao limite?

Não numa chave primária. Com CYCLE, depois do máximo o nextval volta ao MINVALUE e entrega ids que já existem, então o INSERT passa a falhar com duplicate key em vez de reached maximum value. CYCLE só faz sentido quando o valor não precisa ser único, como um contador circular de lote. Para identificador, a saída é sempre aumentar o tipo.

Vale trocar para UUID em vez de bigint?

Só se houver outro motivo, como gerar o id fora do banco ou não expor quantidade de registros. O bigint vai até 9,2 quintilhões: mesmo com os 100,8 milhões de valores por dia do incidente, levaria mais de 250 milhões de anos para acabar. UUID ocupa 16 bytes e, na versão 4, é aleatório, o que espalha as inserções pelo índice inteiro. Se a escolha for UUID, prefira a versão 7, ordenada por tempo, que o PostgreSQL 18 gera com uuidv7().

ALTER SEQUENCE ... AS bigint é seguro em produção com tráfego?

Sim. Ele altera só o catálogo e o próprio objeto da sequência, que é minúsculo, sem tocar na tabela. Se o MINVALUE e o MAXVALUE eram os padrões do tipo antigo, passam automaticamente para os do bigint; se alguém definiu um MAXVALUE explícito, ele permanece e precisa ser alterado no mesmo comando. Sessões com valores em CACHE terminam de usar o bloco já reservado, o que não causa problema porque todos estão abaixo do limite antigo.

O ID acaba onde ninguém está olhando

Uma sequência acaba pelo número de chamadas a nextval, não pelo número de linhas, e upsert, rollback e CACHE podem fazer uma tabela pequena gastar bilhões de valores. Quando acaba, o limite de 32 bits não está só na coluna: está na sequência do serial, nas chaves estrangeiras, nos gatilhos e nos tipos da aplicação. Monitorar o last_value com consumo diário, conferir tipos de sequência e de FK depois de cada migração e criar tabelas novas com bigint identity transformam esse incidente de madrugada numa tarefa planejada.