0006 — UNIQUE em checksum_sha256

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06 · Decidido em: 2026-04-01

Contexto

O mesmo arquivo pode ser reenviado — por retry do cliente, por duplicidade num lote, ou por duas requisições concorrentes com o mesmo conteúdo. Reprocessar o mesmo .xlsx é desperdício e, pior, duas threads processando o mesmo arquivo ao mesmo tempo podem gerar corrida na escrita.

Decisão

Identificar cada arquivo pelo SHA-256 do conteúdo binário e impor UNIQUE em checksum_sha256 na tabela xls_processamento. É a segunda linha de defesa: a primeira é a checagem lógica antes de enfileirar; o índice único garante que, mesmo sob corrida, só uma requisição vence e a outra colide no banco.

Consequências

• Reenvio do mesmo conteúdo é barato e seguro — a colisão no índice evita processamento duplicado, sem depender só de checagem em código.
• Junto com o upsert diff-aware (ver 0009), um arquivo cujo conteúdo já bate com o banco gera zero linhas efetivas e zero churn no PowerSync.
• A chave content-addressed do storage (ver 0005) reusa o mesmo checksum.

Alternativas consideradas

• Só checagem em código (SELECT antes de inserir): sujeito a race entre a checagem e o insert. O índice único fecha essa janela. Descartado como única defesa.
• Dedup por nome de arquivo: nome não identifica conteúdo (dois arquivos diferentes com o mesmo nome, ou o mesmo conteúdo com nomes diferentes). Descartado.