Deadlock em produção: quando duas transações corretas se travam uma na outra

Um deadlock é uma espera circular: a transação A segura um lock que B precisa e B segura um lock que A precisa. Nenhuma das duas pode avançar, e esperar mais não resolve nada. Não é lentidão nem falta de recurso, é um impasse lógico entre transações que fazem exatamente o que deveriam fazer. Por isso ele não aparece em teste unitário, em ambiente de desenvolvimento nem com tráfego baixo: depende de duas transações sobrepostas no tempo, tocando as mesmas linhas em ordens diferentes.

Tempo  Transacao A (Ana paga Bia)           Transacao B (Bia paga Ana)
t1     UPDATE contas ... WHERE id = 1
       (trava a linha da Ana)
t2                                          UPDATE contas ... WHERE id = 2
                                            (trava a linha da Bia)
t3     UPDATE contas ... WHERE id = 2
       (espera B soltar a linha da Bia)
t4                                          UPDATE contas ... WHERE id = 1
                                            (espera A soltar a linha da Ana)
t5     Ninguem avanca: A espera B e B espera A.
       Apos deadlock_timeout (1s) o Postgres aborta uma delas:
       ERROR: deadlock detected (SQLSTATE 40P01)
       A outra transacao termina normalmente.

O PostgreSQL não impede o deadlock, ele o detecta. Quando uma transação espera um lock por mais de deadlock_timeout, que por padrão é 1 segundo, o banco percorre o grafo de quem espera quem. Se encontra um ciclo, aborta uma das transações do ciclo com o erro 40P01 e deixa as outras seguirem. Duas consequências práticas: o usuário da transação escolhida como vítima espera pelo menos um segundo antes de receber o erro, e a transação vítima desfaz todo o trabalho já feito, inclusive o que não tinha relação com o conflito. O MySQL com InnoDB faz o equivalente, detecta o ciclo e devolve o erro 1213, e o SQL Server escolhe uma vítima e devolve o erro 1205.

O código abaixo é o que a maioria das equipes escreve, e ele está certo para qualquer execução isolada. Ana paga Bia e, no mesmo instante, Bia paga Ana. A transação A trava a linha da Ana e depois pede a da Bia. A transação B trava a linha da Bia e depois pede a da Ana. É exatamente a linha do tempo do diagrama.

// Versao que trava: cada transacao bloqueia as contas na ordem em que chegam
export async function transferir(pool, de, para, valor) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query('UPDATE contas SET saldo = saldo - $1 WHERE id = $2', [valor, de]);
    await client.query('UPDATE contas SET saldo = saldo + $1 WHERE id = $2', [valor, para]);
    await client.query('COMMIT');
  } catch (erro) {
    await client.query('ROLLBACK');
    throw erro; // com duas transferencias cruzadas, uma chega aqui com erro.code === '40P01'
  } finally {
    client.release();
  }
}

A ordem em que os locks são adquiridos é decidida pelos parâmetros da chamada, ou seja, pelo usuário. Cada transferência impõe uma ordem diferente, e o banco não tem como saber que as duas deveriam concordar. É a mesma natureza da condição de corrida do estoque negativo: o defeito é de coordenação, não de lógica de negócio, e só se manifesta com concorrência real.

Se todas as transações que precisam das contas 1 e 2 travarem primeiro a 1 e depois a 2, uma espera circular é impossível: quem chega depois simplesmente espera quem chegou antes. O critério de ordenação pode ser qualquer um, desde que seja total e igual para todos, e o id da linha é o mais simples. O código a seguir faz isso com um único SELECT ... ORDER BY id FOR UPDATE, que adquire os locks na ordem do ORDER BY, e depois aplica as alterações com as duas linhas já protegidas.

const RETENTAVEIS = new Set(['40P01', '40001']); // deadlock_detected, serialization_failure

// Executa a funcao inteira em uma transacao e repete a transacao INTEIRA
// quando o banco a escolhe como vitima. Nada com efeito externo roda aqui dentro.
export async function comTransacao(pool, trabalho, { tentativas = 4 } = {}) {
  for (let n = 1; ; n++) {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      const resultado = await trabalho(client);
      await client.query('COMMIT');
      return resultado;
    } catch (erro) {
      await client.query('ROLLBACK').catch(() => {});
      if (!RETENTAVEIS.has(erro.code) || n >= tentativas) throw erro;
    } finally {
      client.release(); // devolve a conexao antes de esperar
    }
    // backoff exponencial com jitter: as vitimas nao voltam todas no mesmo instante
    await new Promise((resolver) => setTimeout(resolver, Math.random() * 25 * 2 ** n));
  }
}

export function transferir(pool, de, para, valor) {
  if (de === para) throw new Error('contas_iguais');
  return comTransacao(pool, async (client) => {
    // Regra de ouro: toda transacao trava as mesmas linhas na mesma ordem (id crescente),
    // nao importa quem paga quem. Um laco de espera circular deixa de ser possivel.
    const { rows } = await client.query(
      'SELECT id, saldo FROM contas WHERE id = ANY($1) ORDER BY id FOR UPDATE',
      [[de, para]],
    );
    if (rows.length !== 2) throw new Error('conta_inexistente');
    const origem = rows.find((linha) => linha.id === de);
    if (Number(origem.saldo) < valor) throw new Error('saldo_insuficiente');

    // As duas linhas ja estao travadas por esta transacao: a ordem dos UPDATEs nao importa mais.
    await client.query('UPDATE contas SET saldo = saldo - $1 WHERE id = $2', [valor, de]);
    await client.query('UPDATE contas SET saldo = saldo + $1 WHERE id = $2', [valor, para]);
  });
}

• O ORDER BY no SELECT FOR UPDATE é o que define a ordem dos locks. Um UPDATE de várias linhas sem esse cuidado trava na ordem em que o plano de execução varre a tabela, que não é garantida e pode mudar com um novo índice ou com estatísticas atualizadas.
• Travar todas as linhas necessárias no início da transação, antes de qualquer decisão, reduz a janela em que outra transação consegue entrar no meio, e o saldo lido já é o saldo travado, o que também elimina a corrida de leitura seguida de escrita.
• A ordenação precisa valer para todos os caminhos de código que tocam essas tabelas: a API, o job de repasses, o estorno, o script de correção. Um único caminho que trave em outra ordem reabre o problema.
• Quando a transação toca tabelas diferentes, a regra se estende: escolha uma ordem global entre tabelas, por exemplo sempre pedidos antes de itens e itens antes de estoque, e documente.

O exemplo da transferência é o mais didático, mas em sistemas reais o ciclo costuma estar escondido em construções que parecem inocentes. As quatro abaixo explicam a maior parte dos deadlocks que chegam ao log.

A última linha da tabela é a mais traiçoeira porque não é um problema de ordem, é de duração. Todo deadlock precisa que duas transações coexistam segurando locks, e quanto mais tempo cada uma segura, maior a probabilidade. Encurtar a transação, fazendo só o que precisa ser atômico dentro dela, reduz a frequência de todos os tipos de deadlock ao mesmo tempo, inclusive os que você ainda não descobriu.

Mesmo com a ordem correta, ainda é possível ter um deadlock raro vindo de um caminho que você não controla, como um gatilho, uma extensão ou uma consulta de relatório. Os erros 40P01 e 40001 têm a propriedade de que a transação inteira foi desfeita e não deixou efeito algum, então repeti-la é seguro. O ponto essencial é repetir a transação inteira, desde o BEGIN, e não apenas o comando que falhou: depois do erro, a transação está em estado abortado e as leituras anteriores podem já não ser válidas. A função comTransacao do código acima faz exatamente isso, com no máximo quatro tentativas, backoff exponencial e jitter para que as vítimas não voltem todas no mesmo instante e formem um novo ciclo.

• Nada com efeito externo dentro da função repetida: e-mail, chamada de API, publicação em fila ou escrita em cache rodam depois do COMMIT. Uma transação repetida três vezes que enviou três e-mails não é segura de repetir.
• Repita apenas os códigos que significam conflito de concorrência, 40P01 e 40001. Violação de unicidade, saldo insuficiente e erro de sintaxe voltariam a falhar do mesmo jeito e só escondem o defeito.
• Limite as tentativas e deixe o erro subir depois delas. Retry sem limite transforma um problema de ordem de locks em uma tempestade de repetições que piora a carga que o causou.
• Meça a taxa de retry como métrica. Um retry que funciona em silêncio esconde um deadlock que deveria ter sido corrigido: o número de repetições por minuto precisa ser baixo e estável, e um aumento é um alerta.

Deadlock sem observabilidade vira um erro 500 sem explicação. Com log_lock_waits ligado, o Postgres registra no log quem esperou lock além do deadlock_timeout, e a mensagem de deadlock lista os processos, as consultas e os locks do ciclo, o que normalmente aponta direto para as duas linhas de código culpadas. O contador deadlocks de pg_stat_database é um acumulado por banco: exporte-o como métrica e alerte sobre a derivada, não sobre o valor absoluto. O lock_timeout por transação complementa a defesa, porque limita a espera por uma linha mesmo quando não há ciclo, o caso de uma transação esquecida aberta.

-- postgresql.conf (ou ALTER SYSTEM): grava no log quem esperou lock por mais de deadlock_timeout
log_lock_waits = on
deadlock_timeout = 1s

-- Por transacao: falha rapido em vez de esperar indefinidamente por uma linha
SET LOCAL lock_timeout = '5s';

-- Agora: quem esta bloqueado, por quem e ha quanto tempo
SELECT a.pid,
       pg_blocking_pids(a.pid)          AS bloqueado_por,
       a.wait_event_type,
       now() - a.xact_start             AS idade_da_transacao,
       left(a.query, 80)                AS consulta
FROM pg_stat_activity a
WHERE cardinality(pg_blocking_pids(a.pid)) > 0;

-- Acumulado: quantos deadlocks este banco ja detectou (exponha como metrica e alerte na derivada)
SELECT datname, deadlocks FROM pg_stat_database WHERE datname = current_database();

Para provar que a correção funciona, o teste precisa produzir a concorrência que o ambiente de desenvolvimento nunca produz. O teste abaixo dispara 200 transferências cruzadas ao mesmo tempo contra um banco real e exige que nenhuma falhe e que a soma dos saldos continue igual. Com a versão ingênua do início do artigo, ele falha de forma consistente com o código 40P01, o que também serve para provar que o teste realmente reproduz o defeito. Rode-o contra um Postgres de verdade, em contêiner, e não contra um banco em memória: o comportamento de locks é justamente o que muda entre eles.

import test from 'node:test';
import assert from 'node:assert/strict';
import pg from 'pg';
import { transferir } from './transferir.js';

test('transferencias cruzadas em paralelo terminam sem erro e sem perder dinheiro', async () => {
  const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 20 });
  await pool.query('TRUNCATE contas');
  await pool.query('INSERT INTO contas (id, saldo) VALUES (1, 100000), (2, 100000)');

  // 200 transferencias, metade em cada sentido, todas disparadas ao mesmo tempo
  const disparos = Array.from({ length: 200 }, (_, i) =>
    i % 2 === 0 ? transferir(pool, 1, 2, 10) : transferir(pool, 2, 1, 10),
  );
  const resultados = await Promise.allSettled(disparos);

  const falhas = resultados.filter((r) => r.status === 'rejected');
  assert.equal(falhas.length, 0, falhas.map((f) => f.reason.code).join(','));

  const { rows } = await pool.query('SELECT sum(saldo)::int AS total FROM contas');
  assert.equal(rows[0].total, 200000); // o total nunca muda em transferencia entre contas
  await pool.end();
});