Melhores Práticas para Cenários de Defeitos
Alterações de esquema pós-mortem em regras de lint. Cada defeito de modelagem que se tornou um incidente deve deixar para trás uma verificação de CI ou um portão de revisão.
Como Usar Esta Lista
- Após cada incidente de dados, mapeie a causa raiz para um item da lista de verificação e automatize sempre que possível.
- Execute testes de detecção de órfãos e de fixtures de fan-out diariamente em snapshots de produção (sanitizados).
- Inclua links para cenários de defeitos no modelo de PR de revisão de esquema.
- Revise as regras quando atualizações de versão principal do PostgreSQL alterarem o comportamento do DDL.
A - Prevenção no Tempo de Design
- Exigir FK em cada
*_idque referencia outra tabela. Isenções precisam de comentário ADR na migração. - Modelar M:N com tabelas de junção antes de escrever consultas. Bloquear PRs que adicionam colunas
tag1,tag2. - Usar
timestamptzpara instantes absolutos. Banir novotimestamp without time zonepara eventos de usuário no linter. - Preferir
text+CHECKem vez de ENUM para estados em evolução. Enum apenas com conjunto fechado ADR. - Documentar o grão do fato para tabelas de relatórios. "Uma linha por item de pedido" no comentário da tabela.
B - Detecção em CI e Jobs
- Suite de consultas órfãs: zero linhas para cada relacionamento FK. Executar contra a atualização do staging diariamente.
- Teste de fixture de receita de fan-out com totais conhecidos. Afirmar que a SOMA corresponde ao valor calculado manualmente.
- Testes negativos entre inquilinos por tabela de inquilino. O Inquilino A nunca vê linhas do Inquilino B.
- Analisar migrações para
ADD VALUEem enums. Sinalizar para revisão do DBA e requisito de teste de carga. - Regressão de
EXPLAINpara as 10 principais consultas de relatórios. Explosão de contagem de linhas falha o CI.
C - Resposta Operacional
- O modelo de post-mortem inclui a categoria da causa raiz do esquema. Fan-out, órfão, enum, fuso horário, filtro de inquilino ausente.
- Converter itens de ação de post-mortem em regras de lint dentro de um sprint. Sem incidentes repetidos sem um novo portão.
- Dashboard de qualidade de dados para contagens de órfãos e determinantes duplicados. Tendência para cima = página de plantão.
- Congelar DDL destrutivo durante a recuperação de incidente de integridade. Corrigir dados antes de adicionar restrições.
- Registrar SQL de remediação no ticket de incidente. Torna-se runbook e fixture de teste.
D - Cultura e Revisão
- A revisão do esquema inclui a seção "como isso falha?". Referenciar páginas de cenário de defeito pelo nome.
- DBA assina alterações de tipo de coluna de caminho crítico. Especialmente
timestampvstimestamptze enum. - Camada semântica de BI de grão revisada pela engenharia de dados. Sem junção automática sem documentação de grão.
- Novos engenheiros leem os Fundamentos de Cenários de Defeitos na semana um de integração.
- Jogo diário trimestral: injetar linhas órfãs no staging, medir o tempo de detecção.
FAQs
Qual é a verificação automatizada de maior ROI?
Detecção de órfãos via LEFT JOIN ... WHERE parent IS NULL para cada par FK - captura FK ausente e bugs de aplicativo precocemente.
Como fazer lint de SQL em migrações?
Use sqlfluff, squawk ou scripts personalizados analisando CREATE TABLE para _id sem REFERENCES.
A produção deve ter jobs de integridade agendados?
Sim - consultas somente leitura diárias com alertas. Mais barato que incidentes de reconciliação financeira.
Como priorizar quais defeitos automatizar primeiro?
Ordenar por frequência e gravidade do incidente: vazamento entre inquilinos, receita de fan-out, órfãos, fuso horário, bloqueio de enum.
As regras de defeito podem desacelerar o desenvolvimento?
Isenções com expiração para protótipos. Caminhos de produção não têm isenção sem aprovação do VP.
O que vai em um ticket de lint pós-mortem?
Descrição da regra, SQL de exemplo com falha, SQL de exemplo com sucesso, proprietário, link para ID do incidente, nome do job de CI.
Como testar regras de fuso horário?
O CI define TimeZone para America/New_York e UTC; afirmar que as mesmas ordens de linha timestamptz consistentemente.
Os esquemas ORM precisam do mesmo lint?
Sim - gerar migrações do ORM ainda sujeitas a lint de SQL nos arquivos de saída.
Como os testes de fan-out diferem dos testes unitários?
Eles usam fixtures de várias tabelas com cardinalidades conhecidas - nível de integração, não repositórios mockados.
Quando posso pular uma verificação de defeito?
Nunca em caminhos de receita e autenticação de produção. Ferramentas de administração interna ainda precisam de verificações de isolamento de inquilino se forem multi-inquilino.
Relacionado
- Fundamentos de Cenários de Defeitos - padrões de incidentes
- Explosão de Junção Fan-Out - grão agregado
- Chaves Estrangeiras Ausentes - aplicação de FK
- Dor de Migração de Enum - risco de DDL de enum
- Bugs de Timestamp Sem Fuso Horário - padrão timestamptz
Versões de Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.