Blog

Coluna grande que deixa o SELECT * lento: TOAST, jsonb e text gigantes lidos sem necessidade

Uma plataforma de atendimento por WhatsApp passou a guardar a conversa inteira numa coluna jsonb da tabela conversas, para alimentar o resumo gerado por IA. Seis semanas depois, a tela de listagem, que mostra só contato, status e última mensagem, saiu de 40 ms para 2,8 segundos de p95, o Node ficou com CPU em 90% e o volume diário de WAL ficou seis vezes maior. A consulta não tinha mudado, o índice estava sendo usado e o EXPLAIN ANALYZE dizia 3,1 ms. O custo estava em outro lugar: o SELECT * trazia, para cada uma das 50 linhas da página, 380 KB de histórico que ninguém exibia, guardados fora da linha pelo TOAST e descomprimidos a cada requisição. Este artigo mostra como o TOAST funciona, por que esse custo não aparece no EXPLAIN ANALYZE, como medir o peso de cada coluna e como corrigir a leitura e a escrita sem reescrever a aplicação inteira.

2026-11-16 / Arquitetura / 13 min

01

A listagem que ficou 70 vezes mais lenta sem mudar a consulta

O incidente demorou a ser entendido porque todos os sinais clássicos estavam bons. A tabela principal tinha praticamente o mesmo tamanho, o plano usava o índice composto de tenant e data, não havia lock nem consulta nova no pg_stat_statements. O que cresceu foi uma tabela que quase ninguém olha: a tabela TOAST associada a conversas, que saiu de zero para 61 GB.

S0  conversas: 4,2 milhões de linhas, tabela de 2,1 GB, listagem com p95 de 40 ms
S1  deploy: coluna historico jsonb guarda a conversa inteira para o resumo por IA
    cada mensagem nova faz UPDATE anexando ao array
S3  historico médio: 380 KB como texto, 96 KB armazenado comprimido no TOAST
S6  640 mil conversas com historico: pg_toast_418204 com 61 GB
    a tabela principal continua com 2,3 GB, e o monitoramento de tamanho não acusa nada
S6  GET /conversas?limit=50: p95 de 2,8 s, CPU do Node em 90%, WAL diário 6 vezes maior
S6  EXPLAIN ANALYZE da mesma consulta: 3,1 ms
S6  hotfix com colunas explícitas na listagem: p95 de volta a 38 ms
S8  mensagens migradas para tabela própria: WAL diário volta ao patamar anterior

A causa tinha duas metades. Na leitura, a listagem usava SELECT * herdado de quando a tabela só tinha colunas pequenas, e passou a carregar 19 MB por página. Na escrita, cada mensagem nova reescrevia o histórico inteiro, gerando WAL e lixo no TOAST proporcionais ao tamanho da conversa, não ao tamanho da mensagem. A primeira metade se resolve em uma hora; a segunda pede mudança de modelo.

02

Como o TOAST guarda valores grandes e quando ele é lido

Uma linha do Postgres precisa caber numa página de 8 kB. Quando uma linha passa de cerca de 2 kB (TOAST_TUPLE_THRESHOLD), o Postgres primeiro tenta comprimir os maiores valores de tamanho variável e, se a linha ainda não couber abaixo de toast_tuple_target (também cerca de 2 kB por padrão), move esses valores para a tabela TOAST, quebrados em pedaços de aproximadamente 2 kB. Na linha principal fica só um ponteiro de 18 bytes. Por isso a tabela conversas continuou com 2,3 GB enquanto o histórico ocupava 61 GB em pg_toast.pg_toast_418204.

O ponto que importa para desempenho: o valor fora da linha só é buscado e descomprimido quando a consulta precisa dele. Uma consulta que não referencia historico nunca toca a tabela TOAST. Uma consulta que devolve historico ao cliente, filtra por uma chave dele ou calcula algo sobre ele paga a leitura dos chunks, a descompressão e, no caso do jsonb, o valor inteiro, porque não existe leitura parcial de jsonb comprimido: para ler payload->>'status' de um documento de 380 KB, o Postgres descomprime os 380 KB.

Estratégia de STORAGEComprimeVai para o TOASTPadrão de
PLAINNãoNãoTipos de tamanho fixo: integer, bigint, timestamptz
MAINSimSó em último casonumeric
EXTERNALNãoSimNenhum tipo; útil para text e bytea lidos com substring
EXTENDEDSimSimtext, varchar, jsonb, bytea
  • SELECT * em tabela com coluna grande lê o TOAST de toda linha devolvida, mesmo que a tela use três campos.
  • Filtrar ou ordenar por uma chave de dentro do jsonb descomprime o documento inteiro em cada linha avaliada.
  • UPDATE que não mexe na coluna grande reaproveita o ponteiro: o valor no TOAST não é regravado.
  • UPDATE que muda qualquer parte do jsonb grava um valor novo inteiro no TOAST e deixa o antigo para o vacuum.

03

Por que o EXPLAIN ANALYZE diz 3 ms e a API leva 2,8 s

O EXPLAIN ANALYZE executa a consulta, mas descarta as linhas em vez de enviá-las. Como os valores TOAST só são buscados quando alguém precisa do conteúdo, e nesse caso ninguém precisa, o plano mede o acesso ao índice e à linha principal e para por aí. A consulta parece perfeita. A partir do PostgreSQL 17, a opção SERIALIZE converte cada linha para o formato que seria enviado ao cliente, o que inclui buscar e descomprimir os valores TOAST, e mostra esse custo separado.

-- A consulta da listagem, exatamente como a API envia.
-- O EXPLAIN ANALYZE descarta as linhas sem convertê-las: o TOAST nunca é lido aqui.
EXPLAIN (ANALYZE, BUFFERS)
SELECT *
  FROM conversas
 WHERE tenant_id = 42
 ORDER BY atualizado_em DESC
 LIMIT 50;

Limit  (rows=50) (actual time=0.052..3.044 rows=50 loops=1)
  Buffers: shared hit=58
  ->  Index Scan Backward using conversas_tenant_atualizado_idx on conversas
        (rows=187400) (actual time=0.050..3.021 rows=50 loops=1)
        Index Cond: (tenant_id = 42)
        Buffers: shared hit=58
Planning Time: 0.211 ms
Execution Time: 3.102 ms

-- PostgreSQL 17: SERIALIZE converte cada linha para o formato de saída, com detoast.
EXPLAIN (ANALYZE, BUFFERS, SERIALIZE)
SELECT *
  FROM conversas
 WHERE tenant_id = 42
 ORDER BY atualizado_em DESC
 LIMIT 50;

...
Planning Time: 0.198 ms
Serialization: time=186.420 ms  output=19034kB  format=text
  Buffers: shared hit=97 read=611
Execution Time: 189.611 ms
-- 19 MB de saída para 50 linhas, quase tudo de historico.

-- Só as colunas que a tela mostra: o TOAST não é tocado.
EXPLAIN (ANALYZE, BUFFERS, SERIALIZE)
SELECT id, contato_nome, status, ultima_mensagem, atualizado_em
  FROM conversas
 WHERE tenant_id = 42
 ORDER BY atualizado_em DESC
 LIMIT 50;

...
Serialization: time=0.091 ms  output=9kB  format=text
Execution Time: 3.188 ms

Os 186 ms de serialização são só a parte do banco. Depois deles vêm 19 MB atravessando a rede, o driver node-postgres montando strings e chamando JSON.parse em cada jsonb, e tudo isso acontecendo na thread principal do Node. Com 30 atendentes abrindo a listagem ao mesmo tempo, o event loop enfileira esses parses e o p95 chega a 2,8 s, enquanto o banco parece ocioso.

Etapa por página de 50 linhasSELECT *Colunas explícitas
Execução no banco (índice e linha principal)3,1 ms3,1 ms
Detoast e serialização186 ms, 611 páginas lidas do disco0,09 ms
Bytes transferidos19 MB9 kB
JSON.parse no Node, bloqueando o event loopcerca de 150 msnenhum
p95 da API com 30 requisições simultâneas2,8 s38 ms

04

Medir o que cada coluna pesa

pg_relation_size da tabela mede só a linha principal. Para saber quanto está fora dela, é preciso olhar reltoastrelid. E para saber o peso por linha, pg_column_size devolve o tamanho armazenado, já comprimido, enquanto octet_length do valor convertido em texto mostra o que de fato trafega até a aplicação. A diferença entre os dois é o quanto a compressão está escondendo.

-- Quanto da tabela mora fora da linha principal.
SELECT c.relname,
       pg_size_pretty(pg_relation_size(c.oid))           AS heap,
       pg_size_pretty(pg_relation_size(c.reltoastrelid)) AS toast,
       pg_size_pretty(pg_indexes_size(c.oid))            AS indices,
       t.relname                                         AS tabela_toast
  FROM pg_class c
  JOIN pg_class t ON t.oid = c.reltoastrelid
 WHERE c.oid = 'public.conversas'::regclass;
-- conversas | 2338 MB | 61 GB | 912 MB | pg_toast_418204

-- Peso médio e máximo das colunas grandes, numa amostra de 1% das páginas.
-- A amostra ainda descomprime esses valores: rode fora do pico ou numa réplica.
SELECT count(*)                                  AS linhas_amostra,
       avg(pg_column_size(historico))::int       AS historico_armazenado,
       avg(octet_length(historico::text))::int   AS historico_em_texto,
       max(pg_column_size(historico))            AS historico_maior,
       avg(pg_column_size(resumo_ia))::int       AS resumo_armazenado
  FROM conversas TABLESAMPLE SYSTEM (1)
 WHERE historico IS NOT NULL;
-- 6412 | 98304 | 389120 | 2911840 | 1730

-- Algoritmo de compressão dos valores gravados (PostgreSQL 14 ou superior).
SELECT pg_column_compression(historico) AS algoritmo, count(*)
  FROM conversas TABLESAMPLE SYSTEM (1)
 WHERE historico IS NOT NULL
 GROUP BY 1;
-- pglz | 6412
  • Toast muito maior que o heap é o sinal de que existe coluna grande que merece revisão de leitura.
  • Média armazenada de 96 kB e texto de 380 kB significam que cada linha devolvida custa 380 kB de rede e de parse.
  • O máximo importa tanto quanto a média: uma conversa de 2,9 MB numa página de listagem já estoura o orçamento de memória de um worker pequeno.
  • pg_stats.avg_width não serve aqui: para valores fora da linha, ele mede o ponteiro, não o conteúdo.
  • Alerte também sobre o tamanho do TOAST, não só da tabela: era ali que o crescimento estava.

05

Corrigir a leitura: colunas explícitas, tabela própria e colunas derivadas

O hotfix do mesmo dia foi trocar SELECT * por uma lista de colunas na listagem. Isso resolveu o p95, mas deixava a armadilha armada para a próxima consulta escrita com pressa ou para o ORM que seleciona todos os campos por padrão. A correção definitiva tirou o histórico da linha principal: as mensagens viraram linhas de uma tabela própria, e o que a listagem precisa, como última mensagem e total de mensagens, virou coluna pequena mantida na escrita.

// conversas-repositorio.js
import pg from 'pg';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// Listagem: só as colunas da tela, nenhuma delas vai para o TOAST.
export async function listarConversas(tenantId, { antesDe = null, limite = 50 } = {}) {
  const { rows } = await pool.query(
    `SELECT id, contato_nome, status, ultima_mensagem, total_mensagens, atualizado_em
       FROM conversas
      WHERE tenant_id = $1
        AND ($2::timestamptz IS NULL OR atualizado_em < $2::timestamptz)
      ORDER BY atualizado_em DESC
      LIMIT $3`,
    [tenantId, antesDe, limite],
  );
  return rows;
}

// Detalhe: as mensagens vêm paginadas da tabela própria, nunca a conversa inteira.
export async function listarMensagens(tenantId, conversaId, { limite = 100 } = {}) {
  const { rows } = await pool.query(
    `SELECT m.id, m.autor, m.texto, m.enviada_em
       FROM mensagens m
       JOIN conversas c ON c.id = m.conversa_id
      WHERE c.tenant_id = $1
        AND m.conversa_id = $2
      ORDER BY m.enviada_em DESC, m.id DESC
      LIMIT $3`,
    [tenantId, conversaId, limite],
  );
  return rows.reverse();
}

// Escrita: uma linha nova por mensagem e colunas derivadas atualizadas na mesma transação.
export async function registrarMensagem(conversaId, { autor, texto, enviadaEm, metadados = {} }) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');

    // Trava a linha da conversa: duas mensagens simultâneas não perdem incremento.
    const atualizada = await client.query(
      `UPDATE conversas
          SET total_mensagens = total_mensagens + 1,
              ultima_mensagem = left($2, 280),
              atualizado_em   = greatest(atualizado_em, $3::timestamptz)
        WHERE id = $1`,
      [conversaId, texto, enviadaEm],
    );
    if (atualizada.rowCount === 0) {
      throw new Error('conversa inexistente: ' + conversaId);
    }

    const { rows } = await client.query(
      `INSERT INTO mensagens (conversa_id, autor, texto, enviada_em, metadados)
       VALUES ($1, $2, $3, $4, $5)
       RETURNING id`,
      [conversaId, autor, texto, enviadaEm, metadados],
    );

    await client.query('COMMIT');
    return rows[0].id;
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

A migração não precisa de janela. A tabela nova é criada vazia, a aplicação passa a gravar mensagens novas só nela e a tela de detalhe lê das duas fontes enquanto o backfill não termina. O backfill anda por faixas de id, e cada lote copia, soma ao contador e anula o historico no mesmo comando, o que o torna seguro para rodar de novo depois de uma falha.

-- Mensagens viram linhas: cada escrita grava só a mensagem nova.
CREATE TABLE mensagens (
  id          bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  conversa_id bigint      NOT NULL REFERENCES conversas (id) ON DELETE CASCADE,
  autor       text        NOT NULL,
  texto       text        NOT NULL,
  enviada_em  timestamptz NOT NULL,
  metadados   jsonb       NOT NULL DEFAULT '{}'
);
CREATE INDEX mensagens_conversa_enviada_idx ON mensagens (conversa_id, enviada_em, id);

-- Instantâneo desde o PostgreSQL 11: não reescreve a tabela.
ALTER TABLE conversas ADD COLUMN total_mensagens integer NOT NULL DEFAULT 0;

-- Backfill por faixa de id, uma transação por lote. Repita avançando 20 mil ids por vez.
-- Copia, soma ao contador e anula o historico no mesmo comando: rodar de novo não duplica.
WITH lote AS (
  SELECT id, historico
    FROM conversas
   WHERE id > 0 AND id <= 20000
     AND historico IS NOT NULL
     FOR UPDATE
), copiadas AS (
  INSERT INTO mensagens (conversa_id, autor, texto, enviada_em, metadados)
  SELECT l.id,
         coalesce(m->>'autor', 'desconhecido'),
         coalesce(m->>'texto', ''),
         (m->>'enviada_em')::timestamptz,
         m - 'autor' - 'texto' - 'enviada_em'
    FROM lote l
    CROSS JOIN LATERAL jsonb_array_elements(l.historico->'mensagens') AS m
)
UPDATE conversas c
   SET total_mensagens = c.total_mensagens + jsonb_array_length(l.historico->'mensagens'),
       historico = NULL
  FROM lote l
 WHERE c.id = l.id;

-- Depois de todos os lotes: o vacuum torna o espaço do TOAST reutilizável.
VACUUM (VERBOSE) conversas;

-- DROP COLUMN é só metadado e não devolve espaço ao sistema operacional;
-- para encolher os arquivos, pg_repack ou VACUUM FULL numa janela de manutenção.
ALTER TABLE conversas DROP COLUMN historico;
OpçãoGanho na leituraCustoQuando usar
Lista explícita de colunasImediato nas consultas corrigidasDisciplina em todo código novo; o ORM precisa de select ou omitSempre, como primeiro passo
Tabela 1:1 para a coluna grandeSELECT * volta a ser baratoJoin quando o conteúdo é necessárioDocumento grande lido raramente e escrito inteiro
Tabela 1:N no lugar de array jsonbLeitura paginada do detalheMigração de dados e mais linhasLista que cresce com o tempo: mensagens, eventos, anexos
Coluna derivada mantida na escritaListagem sem tocar no documentoCódigo de escrita precisa manter a colunaCampos que a listagem mostra ou filtra
Coluna gerada STORED a partir do jsonbIgual à derivada, sem código na aplicaçãoADD COLUMN reescreve a tabela com lock exclusivoTabelas pequenas ou criadas já com a coluna

06

A escrita também paga: jsonb que cresce a cada mensagem

A segunda metade do incidente era o WAL. Anexar um elemento a um array jsonb parece uma operação pequena, mas o Postgres não altera um valor TOAST no lugar: ele lê o valor inteiro, descomprime, monta o documento novo, comprime de novo, grava todos os chunks e marca os antigos como mortos. Numa conversa de 380 KB, uma mensagem de 240 bytes gerava cerca de 100 kB de WAL, que também ia para as réplicas e para o backup contínuo.

-- O padrão que reescreve tudo: anexar uma mensagem ao array.
-- Cada execução descomprime o valor inteiro, grava uma versão nova no TOAST e deixa a antiga como lixo.
UPDATE conversas
   SET historico = jsonb_set(historico, '{mensagens}', (historico->'mensagens') || $2::jsonb),
       atualizado_em = now()
 WHERE id = $1;

-- Quanto WAL uma única mensagem gera (psql, numa sessão sem outras escritas).
SELECT pg_current_wal_lsn() AS antes \gset
UPDATE conversas
   SET historico = jsonb_set(historico, '{mensagens}',
         (historico->'mensagens') || '[{"autor":"cliente","texto":"ok, obrigado"}]'::jsonb)
 WHERE id = 3918022;
SELECT pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), :'antes'));
-- 101 kB de WAL para uma mensagem de 240 bytes

-- lz4 descomprime bem mais rápido que pglz; vale só para valores gravados daqui em diante.
ALTER TABLE conversas ALTER COLUMN resumo_ia SET COMPRESSION lz4;

-- Texto grande lido em pedaços com substring: sem compressão, o Postgres busca só os chunks necessários.
ALTER TABLE anexos ALTER COLUMN conteudo_texto SET STORAGE EXTERNAL;
  • O custo de escrita cresce com o tamanho do documento, então piora justamente nas conversas mais ativas.
  • Os chunks mortos incham a tabela TOAST e dependem do autovacuum, que é disparado pelas contagens da tabela TOAST, não da principal.
  • Duas escritas concorrentes no mesmo documento disputam a mesma linha e uma espera a outra pelo tempo de reescrever 380 KB.
  • Trocar pglz por lz4 reduz o custo de CPU da compressão e da descompressão, mas não muda o fato de que o valor inteiro é reescrito.
  • SET STORAGE EXTERNAL só compensa para texto ou bytea lidos em pedaços com substring; para jsonb, que é lido inteiro, ele só aumenta o espaço.

A regra prática que saiu do incidente: jsonb é ótimo para um documento que é gravado de uma vez e lido de uma vez, como o payload original de um webhook ou a configuração de uma integração. Para algo que cresce item a item, como mensagens, eventos ou anotações, o modelo certo é uma linha por item. E qualquer coluna que pode passar de alguns kB fica fora das consultas de listagem por padrão, não por exceção.

FAQ

Perguntas frequentes

SELECT * é sempre ruim?

Não. Numa tabela só com colunas pequenas, o custo de trazer todas é desprezível, e em consultas ad hoc ele é prático. O problema aparece quando a tabela ganha uma coluna text, jsonb ou bytea que pode passar de alguns kB: a partir daí, todo SELECT * passa a ler o TOAST de cada linha devolvida. Em código de produção, a lista explícita de colunas protege a consulta de mudanças futuras no esquema, o que vale mais do que a economia de digitação.

Comprimir com lz4 resolve a lentidão?

Ajuda na CPU, porque lz4 comprime e descomprime bem mais rápido que pglz, mas não reduz o volume que trafega até a aplicação nem o parse do JSON, que eram a maior parte dos 2,8 s. Também só vale para valores gravados depois do ALTER TABLE ... SET COMPRESSION lz4, e o servidor precisa ter sido compilado com suporte a lz4. É um ajuste complementar; a correção é não ler a coluna quando ela não é necessária.

Como descobrir se o meu ORM está trazendo colunas grandes?

Ative o log das consultas geradas em ambiente de teste e procure SELECT com todas as colunas da tabela, ou use EXPLAIN (ANALYZE, SERIALIZE) no PostgreSQL 17 com a consulta capturada para ver o output em kB. Nas versões recentes do Prisma, omit exclui campos por padrão; em TypeORM e Sequelize, select e attributes resolvem por consulta, e uma coluna marcada para não ser selecionada por padrão resolve para todas.

A coluna que ninguém mostra também tem custo

Uma consulta que usa o índice certo pode ficar lenta porque traz dados que a tela não usa. O TOAST esconde o tamanho real da tabela, o EXPLAIN ANALYZE não mede o detoast e o custo aparece na rede, no parse e no event loop da aplicação. A correção começa com colunas explícitas nas consultas de listagem e termina no modelo: documento grande em tabela própria, lista que cresce virando linhas e campos de listagem mantidos como colunas pequenas. Se a sua aplicação ficou lenta depois de começar a guardar payloads, transcrições ou históricos no banco, eu posso revisar o modelo de dados, as consultas e a migração.