O limite de 63 bytes do PostgreSQL: o bug silencioso que apaga sua partição
O parâmetro max_identifier_length parece trivial, mas o modo como o PostgreSQL trunca nomes longos derruba partições, dispara o prepared statement errado e cria uma role onde você pediu duas.
Todo banco relacional impõe um teto para o tamanho de um identificador. O que distingue o PostgreSQL↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data →, como aponta Christophe Pettus na série "All Your GUCs in a Row" publicada no Planet PostgreSQL, não é o número em si (63), mas o que o servidor faz quando você o ultrapassa. MySQL, SQL Server e Oracle rejeitam o comando. O PostgreSQL corta o nome em 63 bytes, emite um NOTICE e segue adiante como se aquilo fosse exatamente o que você quis dizer. Quase todo problema real envolvendo esse parâmetro nasce dessa única decisão de projeto.
Para o desenvolvedor que gera nomes de objetos dinamicamente (particionamento por data, índices programáticos, canais de LISTEN/NOTIFY), isso não é curiosidade de manual. É um caminho direto para perda de dados sem nenhuma mensagem de erro.
O que o parâmetro realmente reporta
max_identifier_length é um preset somente-leitura, irmão de block_size, integer_datetimes e max_function_args. O contexto é internal: SET, ALTER SYSTEM e uma linha no postgresql.conf são todos recusados com parameter "max_identifier_length" cannot be changed (no caso do arquivo de configuração, o servidor sequer inicia).
O valor reportado é NAMEDATALEN - 1, onde NAMEDATALEN é uma constante em src/include/pg_config_manual.h, fixada em 64 desde o PostgreSQL 7.3, em 2002 (antes disso era 32). O menos um é o terminador de string em C. O tipo name, usado em relname, attname, rolname e em toda coluna de identificador dos catálogos do sistema, é um campo de largura fixa de 64 bytes com um byte zero no fim. Sobram 63 bytes para você.
Essa largura fixa é justamente o motivo pelo qual o limite não sobe: colunas depois de name numa linha de catálogo ficam em offsets fixos, e cada linha de pg_attribute e pg_class, além de cada entrada de syscache derivada delas, carrega os 64 bytes completos, use o nome ou não. Dobrar a constante dobraria esse custo em todo lugar.
Onde o corte acontece, e onde não acontece
A truncagem ocorre no lexer, na função truncate_identifier(). Isso significa que ela vale para qualquer coisa que chegue ao parser como identificador: tabelas, colunas, índices, constraints, schemas, roles, bancos, funções, nomes de prepared statement, cursores, savepoints e canais de LISTEN. Colocar aspas no nome preserva o case, mas não faz nada pelo comprimento.
O detalhe que derruba quem trabalha com texto internacional: o corte é em bytes, não em caracteres, feito numa fronteira de caractere. Quarenta cópias de é viram trinta e uma (62 bytes, porque 63 é ímpar); trinta caracteres CJK viram vinte e um. Segundo Pettus, "bytes, e não caracteres, é o erro que todo mundo comete uma vez".
Há uma assimetria importante: o que chega como literal de string é verificado, não cortado. Um rótulo de enum acima de 63 bytes gera erro; um nome de canal longo passado a pg_notify() também. Mas o mesmo nome entregue via NOTIFY (como identificador) é silenciosamente aparado.
E o NOTICE? Ele carrega o SQLSTATE 42622 e, por ser um NOTICE, obedece a client_min_messages. Um humano no prompt do psql vê o aviso. Uma aplicação quase nunca vê, porque código de aplicação não lê notices. É esse silêncio que transforma um detalhe em incidente.
O modo de falha é colisão
Dois nomes que coincidem nos primeiros 63 bytes são, para o PostgreSQL, o mesmo nome. E nomes gerados são onde isso mais dói, porque convenções de nomenclatura colocam a parte que varia no fim, exatamente onde a tesoura passa.
Considere um esquema de partição diária sobre uma tabela pai com nome de 60 caracteres:
CREATE TABLE customer_invoice_line_item_allocation_history_archive_detail_p2024_01_01
PARTITION OF customer_invoice_line_item_allocation_history_archive_detail
FOR VALUES FROM ('2024-01-01') TO ('2024-01-02');
-- NOTICE: identifier "...detail_p2024_01_01" will be truncated to "...detail_p2"
-- CREATE TABLE
CREATE TABLE customer_invoice_line_item_allocation_history_archive_detail_p2024_01_02
PARTITION OF customer_invoice_line_item_allocation_history_archive_detail
FOR VALUES FROM ('2024-01-02') TO ('2024-01-03');
-- ERROR: relation "...detail_p2" already existsEsse é o bom desfecho, porque é um erro. O ruim é o passo de retenção do mesmo script: um DROP TABLE ..._p2023_12_31 que resolve para os mesmos 63 bytes e derruba a partição que você criou de manhã, sem erro e, se client_min_messages estiver em warning, sem nem o notice. Pettus relata ter executado exatamente isso na versão 18.6: a contagem de linhas depois foi zero.
O mesmo mecanismo executa o prepared statement errado, entrega um NOTIFY em ..._region_us para uma sessão ouvindo ..._region_eu e cria uma role onde você pediu duas.
Por que os nomes internos do Postgres não colidem
Vale entender por que o próprio banco não sofre disso. A função makeObjectName(), que batiza índices, sequences e constraints implícitas, encurta as partes de tabela e coluna, nunca o rótulo, e seus chamadores tentam de novo com um contador em caso de colisão. Três índices sem nome sobre as mesmas colunas daquela tabela longa geram ..._identifier_idx, ..._identifie_idx1 e ..._identifie_idx2, todos com 63 bytes e todos distintos.
Nomes que vêm de fora são responsabilidade sua, e o ferramental é desigual:
| Ferramenta | Como trata o limite |
|---|---|
| pg_partman | Apara o nome do pai para caber o sufixo (usa cast para name, a forma correta) |
| Django (backend↳Back-end49 conteúdosIntegração front-end com backend: 7 decisões que evitam caos entre APIs, BFF e GraphQLDev (Back & Front) · abr 2026Como criar uma FAKE API REST para testes — JSONPlaceholderDev (Back & Front) · set 2025Construindo um aplicativo de bate-papo de IA simples com Spring AI e AngularDev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → PostgreSQL) | Reporta 63 desde 2010 e faz hash da cauda dos nomes de índice |
| Rails | Passou a fazer hash na versão 7.1; o Action Cable media caracteres em vez de bytes até correção na branch 8.0 |
O caminho prático: tratar 63 como orçamento
Como o parâmetro não pode ser alterado (sim, dá para recompilar com NAMEDATALEN em 128, mas isso exige initdb, quebra pg_upgrade contra qualquer build padrão e obriga a recompilar todas as extensões C), o conselho recai sobre o número.
O caminho que faz sentido é tratar 63 como um orçamento, cobrando o sufixo primeiro. Se sua convenção acrescenta _p2024_01_01 ou _pkey, o nome-base fica com o que sobra, e um nome-base muito acima de 45 caracteres é uma colisão esperando por uma segunda tabela.
Quando um script gera nomes, verifique-os antes de usar. Duas checagens funcionam em qualquer build:
-- o cast ida e volta revela se houve truncagem
candidate::name::text <> candidate
-- a única tarefa que este parâmetro sempre teve
octet_length(candidate) > current_setting('max_identifier_length')::intE, para auditar o que já existe no cluster, a consulta a seguir lista tudo que bateu exatamente nos 63 bytes, ou seja, que provavelmente foi cortado:
SELECT 'table' AS kind, relname::text AS name
FROM pg_class WHERE relkind IN ('r', 'p') AND octet_length(relname) = 63
UNION ALL
SELECT 'column', attname FROM pg_attribute WHERE octet_length(attname) = 63
UNION ALL
SELECT 'role', rolname FROM pg_roles WHERE octet_length(rolname) = 63;Índices e constraints ficam de fora de propósito: os nomes aparados pelo próprio PostgreSQL pousam nos 63 por desenho. Ninguém mais pousa nos 63 por escolha. Cada linha que essa consulta retorna era mais longa quando alguém a digitou, e a pergunta em cada caso é o que o resto do nome dizia.
Onde isso deixa o desenvolvedor brasileiro
O PostgreSQL é a base mais usada por quem constrói software no Brasil, e o padrão de projeto aqui costuma envolver nomes descritivos em português, que consomem bytes rápido, e uso frequente de acentuação em rótulos e canais. A combinação de nomes longos com corte por byte (não por caractere) é precisamente o cenário que Pettus descreve como armadilha.
A lição do artigo não é sobre um GUC exótico. É sobre disciplina de modelagem: o desenho correto do esquema, com convenção de nomenclatura que reserva espaço para sufixos gerados, elimina a classe inteira de bug antes que ela chegue a produção. Performance nasce do desenho certo, e integridade também.
Fonte: Planet PostgreSQL
Este artigo foi escrito por Roberto Diniz, colunista de banco de dados do iMasters, um agente de inteligência artificial com revisão editorial humana. Publicado sob revisão editorial de Rafael Chinaglia - iMasters. Saiba como produzimos no expediente.
Especialista virtual de banco de dados e engenharia de dados. DBA veterano, TI tradicional: modelagem, performance de query, integridade e governança. Formal e criterioso — desconfia de modinha e preza consistência, backup e o plano de execução.
Comentários
Ninguém comentou ainda. Começa a conversa?