Blog

Collation que muda depois da atualização do sistema operacional: glibc, índice com ordem errada e REINDEX

Uma plataforma de e-commerce B2B precisava sair do CentOS 7, que tinha chegado ao fim de suporte. O plano parecia o mais seguro possível: subir uma réplica física do PostgreSQL 15 num servidor novo com Rocky Linux 9, esperar ela alcançar o primário e promover. A troca levou quatro minutos e nenhum teste falhou. Na manhã seguinte, o suporte começou a receber chamados de produtos que apareciam na listagem mas davam 404 quando buscados pelo SKU. Três dias depois, o importador de catálogo tinha criado 4.137 produtos duplicados numa tabela com UNIQUE (tenant_id, sku). Nada no banco tinha mudado: mesmos dados, mesma versão do Postgres, mesmos índices copiados byte a byte. O que mudou foi a glibc, que define como o Postgres compara textos em collations como pt_BR.UTF-8, e com ela a ordem que o índice B-tree assume ao ser percorrido. Este artigo explica por que um índice de texto depende da versão da biblioteca do sistema operacional, quais estratégias de migração carregam o problema e quais não, como detectar com a versão de collation e o amcheck e como corrigir com REINDEX, limpeza de duplicatas e REFRESH COLLATION VERSION.

2026-11-19 / Arquitetura / 13 min

01

O failover sem erro que fez o índice único deixar passar duplicatas

A tabela produtos tinha 12 milhões de linhas, chave primária bigint e um índice único em (tenant_id, sku), usado tanto pela API de busca por SKU quanto pelo ON CONFLICT do importador. Os SKUs vinham dos ERPs dos clientes e misturavam letras, números, hífens e espaços. Era exatamente o tipo de texto em que a ordenação linguística mudou entre versões da glibc.

D-30      CentOS 7 chega ao fim de suporte; plano: réplica em Rocky Linux 9 e failover
D0 22:00  réplica física (streaming) no servidor novo, mesmo PostgreSQL 15, pg_basebackup
D0 23:40  promote da réplica, aplicação apontada para o servidor novo; 4 minutos de troca
D0 23:41  WARNING de collation version mismatch começa a aparecer no log, a cada conexão
D1 09:15  suporte: produtos com SKU como 'AB-12' retornam 404 na API, mas aparecem na listagem
D3 14:00  importador de catálogo criou 4.137 produtos duplicados apesar do UNIQUE (tenant_id, sku)
D3 16:30  enable_indexscan = off encontra as linhas; bt_index_check acusa ordem violada
D3 18:00  limpeza de duplicatas, REINDEX CONCURRENTLY de 23 índices, REFRESH COLLATION VERSION

O diagnóstico demorou porque os sintomas pareciam bugs da aplicação. A busca por SKU falhava em 0,3% dos casos, sempre com SKUs que tinham hífen ou espaço. O mesmo produto aparecia na listagem, que filtrava por tenant e ordenava por nome. O importador não registrava erro, porque o ON CONFLICT nunca disparava: para o índice, a linha antiga não existia. O aviso que explicava tudo estava no log desde o primeiro minuto, repetido em cada conexão, mas era um WARNING no meio de milhares de linhas e ninguém olhava o log do banco depois de uma troca que tinha dado certo.

02

Por que um índice de texto depende da glibc

Um índice B-tree guarda as chaves em ordem e usa essa ordem para navegar: em cada página, compara a chave procurada com as chaves separadoras e desce pelo ramo correspondente. Para tipos como bigint ou timestamptz, a comparação é fixa. Para text e varchar com uma collation da libc, como pt_BR.UTF-8 ou en_US.UTF-8, o Postgres chama strcoll da glibc, e a ordem vem das tabelas de locale da biblioteca instalada no sistema operacional. O índice não guarda a regra de comparação, só o resultado dela: a posição de cada chave foi decidida pela glibc que estava instalada quando a linha foi inserida.

Na glibc 2.28, as tabelas de collation foram atualizadas para uma versão nova da ISO 14651 e a ordem de muitos textos mudou, especialmente com pontuação, hífens e espaços. Debian 10, Ubuntu 18.10 e RHEL 8 em diante já vêm com a regra nova; CentOS 7, Ubuntu 18.04 e Debian 9 têm a antiga. Uma troca entre esses dois grupos é praticamente garantia de índices de texto com ordem errada.

# Servidor antigo, CentOS 7 (glibc 2.17): o hífen é ignorado no primeiro nível.
$ printf '1-1\n11\n1-2\n1\n' | LC_COLLATE=en_US.UTF-8 sort
1
1-1
11
1-2

# Servidor novo, Rocky Linux 9 (glibc 2.34): o hífen passa a contar.
$ printf '1-1\n11\n1-2\n1\n' | LC_COLLATE=en_US.UTF-8 sort
1
1-1
1-2
11

-- A mesma comparação, dentro do Postgres, muda de resposta sem ninguém mudar o banco.
SELECT '1-2' < '11' COLLATE "en_US.utf8";
-- glibc 2.17: f    glibc 2.34: t

-- O índice foi construído com a ordem antiga. Pela PK a linha existe:
SELECT id, sku FROM produtos WHERE id = 88412;
  id   |  sku
-------+-------
 88412 | AB-12
(1 row)

-- Pelo índice único, que agora desce pelo ramo errado da árvore, ela some:
SELECT id FROM produtos WHERE tenant_id = 731 AND sku = 'AB-12';
(0 rows)

-- E o mesmo índice que não encontra a linha também não impede a duplicata:
INSERT INTO produtos (tenant_id, sku, nome) VALUES (731, 'AB-12', 'Cabo 12 vias')
ON CONFLICT (tenant_id, sku) DO NOTHING;
INSERT 0 1
  • Busca por igualdade ou faixa: a descida pela árvore usa a comparação nova sobre chaves posicionadas pela antiga, cai na página errada e conclui que a chave não existe.
  • UNIQUE e PRIMARY KEY em texto: a verificação de unicidade é a mesma busca. Se ela não encontra a chave existente, a inserção duplicada passa, e o ON CONFLICT nunca dispara.
  • ORDER BY atendido pelo índice devolve a ordem antiga, enquanto um Sort devolve a nova. Paginação por keyset que mistura os dois pula ou repete linhas.
  • Merge join entre colunas de texto pode perder pares, porque assume que as duas entradas estão na mesma ordem.
  • Particionamento por faixa de texto pode ter linhas em partições cujos limites, pela regra nova, não as aceitariam mais.

03

O que é afetado e o que não é

O problema está restrito a estruturas que dependem da ordem de texto definida pela libc. Saber exatamente quais são permite estimar o tamanho do REINDEX antes da migração, em vez de reconstruir o banco inteiro por precaução ou, pior, não reconstruir nada.

EstruturaAfetada?Por quê
B-tree em text ou varchar com collation libc (pt_BR.UTF-8, en_US.UTF-8)SimA ordem das chaves vem de strcoll da glibc
PRIMARY KEY e UNIQUE em colunas de textoSim, e aceita duplicatasA verificação de unicidade é uma busca no índice
Índice de expressão como lower(email)SimO resultado é texto ordenado pela mesma collation
Índice com COLLATE "C" ou text_pattern_opsNãoComparação byte a byte, independente de locale
B-tree em bigint, integer, uuid, timestamptz, numericNãoComparação definida pelo próprio tipo
Índice hash em textNãoDepende só de igualdade, que em collation determinística é igualdade de bytes
Particionamento por faixa em coluna de textoSimOs limites das partições são comparados pela collation
Collation ICUDepende da versão da ICU, não da glibcO Postgres registra a versão por collation e avisa quando muda

No incidente, 23 índices entravam na lista: chaves únicas em SKU, e-mail e código externo, índices de expressão em lower(email) e índices compostos com uma coluna de texto depois do tenant_id. Os índices em ids, datas e valores, que eram a maioria, não precisavam de nada.

04

Detectar antes que o cliente perceba: versão de collation e amcheck

A partir do PostgreSQL 15, o banco registra em pg_database.datcollversion a versão da glibc usada quando a collation padrão foi definida, e compara com a versão atual a cada conexão. Collations explícitas têm o mesmo controle em pg_collation.collversion. Essa comparação é a primeira verificação a fazer depois de qualquer troca de servidor, imagem ou sistema operacional, e deveria fazer parte do checklist da migração.

-- PostgreSQL 15+: versão registrada no banco contra a versão que o SO entrega agora.
SELECT datname,
       datcollate,
       datcollversion                            AS versao_registrada,
       pg_database_collation_actual_version(oid) AS versao_do_so
  FROM pg_database
 WHERE datname = current_database();

 datname | datcollate  | versao_registrada | versao_do_so
---------+-------------+-------------------+--------------
 loja    | pt_BR.UTF-8 | 2.17              | 2.34

-- Collations explícitas (libc e ICU): mesma comparação, por collation.
SELECT collname, collprovider, collversion,
       pg_collation_actual_version(oid) AS versao_do_so
  FROM pg_collation
 WHERE collversion IS DISTINCT FROM pg_collation_actual_version(oid);

-- O aviso que fica no log a cada conexão enquanto nada for corrigido.
WARNING:  database "loja" has a collation version mismatch
DETAIL:  The database was created using collation version 2.17, but the operating system provides version 2.34.
HINT:  Rebuild all objects in this database that use the default collation and run ALTER DATABASE loja REFRESH COLLATION VERSION, or build PostgreSQL with the right library version.

A versão diz que há risco, não onde há dano. Para isso existe a extensão amcheck: bt_index_check percorre o índice e verifica se as chaves estão na ordem que o comparador atual espera, e com heapallindexed = true também confere se cada linha da tabela está no índice. O script abaixo lista os índices B-tree que dependem de collation da libc, roda o amcheck em cada um e, com --reindex, reconstrói todos sem bloquear escrita.

// auditar-collation.js
// node auditar-collation.js            -> relatorio
// node auditar-collation.js --reindex  -> relatorio + REINDEX CONCURRENTLY
import pg from 'pg';

const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
const reindexar = process.argv.includes('--reindex');

// Índices B-tree com pelo menos uma coluna ou expressão em collation da libc diferente de C.
const SQL_INDICES_AFETADOS = `
  SELECT DISTINCT
         i.indrelid::regclass::text   AS tabela,
         i.indexrelid::regclass::text AS indice,
         i.indisunique                AS unico
    FROM pg_index i
    JOIN pg_class c      ON c.oid = i.indexrelid
    JOIN pg_am am        ON am.oid = c.relam
    CROSS JOIN LATERAL unnest(i.indcollation::oid[]) AS col(oid)
    JOIN pg_collation co ON co.oid = col.oid
    JOIN pg_database d   ON d.datname = current_database()
   WHERE am.amname = 'btree'
     AND c.relnamespace <> 'pg_catalog'::regnamespace
     AND (
           (co.collprovider = 'c' AND co.collname NOT IN ('C', 'POSIX'))
        OR (co.collprovider = 'd' AND d.datlocprovider = 'c'
            AND d.datcollate NOT IN ('C', 'POSIX'))
         )
   ORDER BY 1, 2`;

async function main() {
  await client.connect();
  try {
    // amcheck lê o índice e o heap; precisa de superusuário ou de GRANT nas funções.
    await client.query('CREATE EXTENSION IF NOT EXISTS amcheck');

    const { rows: indices } = await client.query(SQL_INDICES_AFETADOS);
    const relatorio = [];

    for (const { tabela, indice, unico } of indices) {
      let amcheck = 'ok';
      try {
        // heapallindexed = true confere também se toda linha do heap está no índice.
        await client.query('SELECT bt_index_check($1::regclass, true)', [indice]);
      } catch (erro) {
        amcheck = erro.message;
      }
      relatorio.push({ tabela, indice, unico, amcheck });
    }

    console.table(relatorio);
    if (!reindexar) return;

    for (const { indice } of relatorio) {
      try {
        // REINDEX CONCURRENTLY não roda dentro de transação: cada índice em um comando.
        // O nome vem de ::regclass::text, já com aspas e schema quando necessário.
        await client.query(`REINDEX INDEX CONCURRENTLY ${indice}`);
        console.log(`ok: ${indice}`);
      } catch (erro) {
        // Falhou: sobra um índice inválido com sufixo _ccnew, que precisa de DROP INDEX CONCURRENTLY.
        console.error(`erro: ${indice}: ${erro.message}`);
        process.exitCode = 1;
      }
    }
    // Depois de reconstruir tudo: ALTER DATABASE ... REFRESH COLLATION VERSION.
  } finally {
    await client.end();
  }
}

main().catch((erro) => {
  console.error(erro);
  process.exit(1);
});

Dois cuidados. bt_index_check com heapallindexed lê o índice e a tabela inteira, então rode fora do pico ou numa réplica com a mesma glibc do servidor novo. E o amcheck pode não acusar um índice cuja ordem mudou só em pontos que a verificação não alcança: use o resultado para medir o dano e priorizar, mas reconstrua todos os índices da lista, não só os que falharam.

05

Corrigir: duplicatas primeiro, REINDEX depois, versão por último

A ordem importa. Um índice único não pode ser reconstruído enquanto houver duplicatas na tabela: o REINDEX falha com could not create unique index, e no modo CONCURRENTLY ainda deixa um índice inválido com sufixo _ccnew. E a versão registrada só deve ser atualizada quando todos os índices afetados estiverem reconstruídos, porque o REFRESH COLLATION VERSION apenas silencia o aviso, sem corrigir nada.

  1. Tirar do ar ou pausar os processos que inserem em massa nas tabelas afetadas, como importadores, para que novas duplicatas não entrem durante a correção.
  2. Encontrar as duplicatas com os índices desligados na sessão, porque um GROUP BY resolvido pelo índice corrompido pode esconder justamente os grupos repetidos.
  3. Decidir a regra de fusão com o negócio: qual linha fica, o que acontece com estoque, preço e pedidos que apontam para a duplicata.
  4. Reconstruir com REINDEX INDEX CONCURRENTLY, um índice por vez, começando pelos únicos. Se algum falhar, remover o _ccnew com DROP INDEX CONCURRENTLY e tratar o que sobrou.
  5. Rodar o amcheck de novo em todos os índices da lista e só então executar ALTER DATABASE ... REFRESH COLLATION VERSION.
BEGIN;

-- Desliga os índices só para encontrar as duplicatas: o GROUP BY não pode confiar no índice corrompido.
SET LOCAL enable_indexscan = off;
SET LOCAL enable_indexonlyscan = off;
SET LOCAL enable_bitmapscan = off;

-- Regra do negócio: mantém o produto mais antigo e aponta as referências para ele.
CREATE TEMP TABLE duplicados ON COMMIT DROP AS
SELECT id, manter
  FROM (SELECT id, min(id) OVER (PARTITION BY tenant_id, sku) AS manter
          FROM produtos) t
 WHERE id <> manter;

-- A partir daqui os índices voltam: produto_id é bigint e não depende de collation.
RESET enable_indexscan;
RESET enable_indexonlyscan;
RESET enable_bitmapscan;

UPDATE itens_pedido ip
   SET produto_id = d.manter
  FROM duplicados d
 WHERE ip.produto_id = d.id;

DELETE FROM produtos p
 USING duplicados d
 WHERE p.id = d.id;

COMMIT;

-- Com as duplicatas removidas, o índice único pode ser reconstruído.
REINDEX INDEX CONCURRENTLY produtos_tenant_sku_key;

-- Só depois de reconstruir todos os índices afetados do banco.
ALTER DATABASE loja REFRESH COLLATION VERSION;

No incidente, a limpeza das 4.137 duplicatas e os 23 REINDEX CONCURRENTLY levaram pouco menos de duas horas, sem janela de manutenção. O maior índice, de 1,1 GB, levou 14 minutos. Depois disso, o amcheck passou em todos os índices, a busca por SKU voltou a 100% e o WARNING saiu do log.

06

Planejar a troca de sistema operacional e não repetir o problema

A causa raiz não foi o Rocky Linux nem a glibc nova, e sim a escolha de uma estratégia de migração que copia os índices sem reconstruí-los. Cada caminho tem um custo diferente de janela e de risco de collation, e essa comparação precisa ser feita antes de escolher.

EstratégiaO que acontece com os índicesJanelaRisco de collation
pg_dump e pg_restore no servidor novoConstruídos no SO novoProporcional ao tamanho do bancoNenhum
Replicação lógica para o servidor novoConstruídos no assinante, no SO novoMinutos, só na trocaNenhum
Réplica física (streaming) no SO novo e promoteCopiados byte a byteSegundosAlto: todos os índices de texto com libc
Atualizar o SO no mesmo servidorMantidosTempo do upgradeAlto
Snapshot do volume em máquina com outra imagemMantidosMinutosAlto
  • Se a janela permite, prefira replicação lógica ou dump e restore: os índices nascem no sistema novo e o problema não existe. É a mesma técnica usada para upgrades de versão major sem janela.
  • Se precisar de réplica física, inclua o REINDEX CONCURRENTLY dos índices afetados no plano, antes de liberar escrita, e meça o tempo num ambiente com o mesmo volume.
  • Nunca misture versões de glibc entre primário e réplicas físicas. Uma réplica de leitura num SO diferente responde consultas erradas mesmo sem failover.
  • Para colunas que são identificadores, como SKU, código externo, slug e chave de idempotência, use COLLATE "C": a ordenação linguística não serve para nada nelas e a comparação byte a byte é estável e mais rápida.
  • Em bancos novos, avalie o provedor builtin com C.UTF-8 (PostgreSQL 17+), que não depende da glibc, ou ICU, cuja versão o Postgres acompanha por collation.
  • Monitore o log do banco por collation version mismatch, junto com os outros WARNING, e faça a verificação de datcollversion parte do checklist de qualquer troca de máquina.

FAQ

Perguntas frequentes

Se o Postgres e os dados são os mesmos, por que a ordem muda?

Porque, em collations da libc, o Postgres não implementa a comparação de textos: ele chama strcoll da glibc. Quando a glibc muda as regras de ordenação, a mesma comparação passa a dar outro resultado, mas os índices já construídos continuam com as chaves na posição decidida pela regra antiga. A árvore fica inconsistente com o comparador que a percorre.

O REFRESH COLLATION VERSION resolve o problema?

Não. Ele só atualiza a versão registrada no catálogo para a versão atual, o que faz o aviso parar. Os índices continuam com a ordem antiga. O comando deve ser o último passo, depois de reconstruir todos os índices e demais objetos que dependem da collation, e nunca a primeira reação ao WARNING.

Como evitar isso em novos bancos?

Use COLLATE "C" nas colunas de texto que são identificadores, já que nelas a ordem linguística não importa. Para o padrão do banco, considere o provedor builtin com C.UTF-8 no PostgreSQL 17 ou ICU, cuja versão é rastreada por collation. E, em qualquer troca de sistema operacional, prefira estratégias que reconstroem os índices, como replicação lógica, ou inclua o REINDEX no plano.

O índice de texto carrega a versão da biblioteca que o construiu

Em collations da libc, a ordem de um índice B-tree de texto é decidida pela glibc instalada quando as linhas entraram. Trocar o sistema operacional por réplica física, snapshot ou upgrade no mesmo servidor mantém os índices e troca o comparador, e o resultado são buscas que não encontram linhas existentes e chaves únicas que aceitam duplicatas, sem nenhum erro. Verificar datcollversion, rodar o amcheck, reconstruir os índices afetados antes de liberar escrita e escolher estratégias que reconstroem os índices evita que uma migração de infraestrutura vire um problema de dados. Se você vai trocar sistema operacional, servidor ou imagem de um banco em produção, posso revisar o plano de migração, mapear os índices afetados e conduzir a troca com segurança.