A correção do incidente teve duas partes. No banco, o índice novo com o predicado que a consulta realmente usa. Na aplicação, um teste de contrato que roda no CI contra um banco com o mesmo esquema e quebra se a consulta deixar de poder usar o índice esperado. O teste desliga o seq scan só dentro da transação: o objetivo não é medir custo, que numa base de teste pequena sempre favorece a varredura, e sim garantir que o índice continua elegível.
// fila-repositorio.js
import pg from 'pg';
export const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 10,
});
// Os estados cobertos pelo predicado do índice ficam como literal no SQL, nunca como $1.
// São constantes do código, não entrada do usuário: não há risco de injeção.
export const SQL_RESERVAR_TAREFAS = `
SELECT id, tipo, payload
FROM tarefas
WHERE status IN ('pendente', 'reprocessar')
AND agendada_para <= now()
ORDER BY agendada_para
LIMIT $1
FOR UPDATE SKIP LOCKED`;
export async function reservarTarefas(client, limite = 50) {
const { rows } = await client.query(SQL_RESERVAR_TAREFAS, [limite]);
return rows;
}
// Lista os índices que o plano da consulta usa, com os parâmetros reais.
// enable_seqscan = off mede elegibilidade, não custo: numa base de teste pequena o seq scan venceria.
export async function indicesDoPlano(client, sql, params = []) {
await client.query('BEGIN');
try {
await client.query('SET LOCAL enable_seqscan = off');
const { rows } = await client.query(`EXPLAIN (FORMAT JSON) ${sql}`, params);
const indices = new Set();
const visitar = (no) => {
if (no['Index Name']) indices.add(no['Index Name']);
(no.Plans || []).forEach(visitar);
};
visitar(rows[0]['QUERY PLAN'][0].Plan);
return [...indices];
} finally {
await client.query('ROLLBACK');
}
}
// fila-repositorio.test.js
import { test, after } from 'node:test';
import assert from 'node:assert/strict';
import { pool, SQL_RESERVAR_TAREFAS, indicesDoPlano } from './fila-repositorio.js';
after(() => pool.end());
// Teste de contrato: quebra no CI se a consulta deixar de poder usar o índice parcial.
test('reserva de tarefas usa tarefas_a_processar_idx', async () => {
const client = await pool.connect();
try {
const indices = await indicesDoPlano(client, SQL_RESERVAR_TAREFAS, [50]);
assert.ok(
indices.includes('tarefas_a_processar_idx'),
`plano usou: ${indices.join(', ') || 'nenhum índice'}`,
);
} finally {
client.release();
}
});
- Crie o índice novo antes do deploy que muda a consulta, nunca depois. CREATE INDEX CONCURRENTLY não bloqueia escrita, mas leva tempo numa tabela grande.
- Trate o predicado do índice e o WHERE da consulta como um contrato: quem muda um precisa mudar o outro no mesmo pull request.
- Prefira predicados com lista explícita, status IN ('pendente', 'reprocessar'), a negações como status <> 'concluida', que incluem qualquer estado novo e fazem o índice crescer sem ninguém perceber.
- Mantenha o auto_explain registrando planos acima de algumas centenas de milissegundos nas consultas da fila: a troca de Index Scan por Seq Scan aparece no log antes de virar incidente.
Com o índice tarefas_a_processar_idx no lugar, a reserva voltou a 0,5 ms, o índice ficou em 15 MB e a fila de 180 mil tarefas foi drenada em onze minutos pelos quatro workers originais. Duas semanas depois, o teste de plano pegou um pull request que adicionava o estado 'agendada_manual' ao IN sem mexer no índice.