Melhores Práticas de Banco de Dados e Acesso a Dados

Deadlines de contexto, dimensionamento de pool e observabilidade para consultas.

Aplique estas regras em revisões de código, templates de serviço e runbooks para que todo handler, repositório e worker trate SQL como um recurso compartilhado com propriedade clara e limites de cancelamento.

Como Usar Esta Lista

• Marque as regras conforme seu template de serviço as adota.
• Codifique os itens da Camada A em CI (lint de migração, proibição de Query sem Context) onde possível.
• Publique uma tabela de timeouts e pools ao lado do README do serviço.
• Revise ao adicionar réplicas, réplicas de leitura ou camadas de cache.

A - Pool de conexões e ciclo de vida

• Um pool *sql.DB por DSN por processo, configurado em main. Evite abrir bancos de dados de produção em init().
• Defina MaxOpenConns com base em cálculos de capacidade (db_max / replicas). Previne incidentes de too many connections (muitas conexões).
• Defina limites explícitos de conexões ociosas e de tempo de vida. Não confie em padrões ilimitados sob balanceadores de carga.
• Use PingContext na inicialização com timeout de boot. Falhe a implantação antes que o tráfego atinja DSNS ruins.
• Exporte db.Stats() para métricas (WaitCount, InUse, Idle). Alerte sobre o crescimento da espera no pool.

B - Contexto, timeouts e métodos SQL

• Use métodos de banco de dados *Context em todo caminho com escopo de requisição. Proíba Query/Exec sem Context em handlers.
• Derive timeouts de DB do ctx do handler ou RPC, não de Background(). Preserva o cancelamento do cliente.
• Publique uma tabela de orçamento de timeout por consulta ou por repositório. DB, cache e HTTP de saída recebem uma fatia cada.
• Emparelhe o contexto com statement_timeout do SQL quando os drivers demorarem. Defesa em profundidade para consultas descontroladas.
• Retorne ctx.Err() quando o cancelamento encerrar uma consulta. Mapeie para o status HTTP/gRPC correto na borda.

C - Limites de repositório e higiene SQL

• Mantenha o SQL em pacotes de repositório/armazenamento, não em handlers HTTP. Handlers permanecem finos em transporte.
• Use placeholders para todos os valores dinâmicos. Nunca concatene entrada do usuário em strings SQL.
• Mapeie sql.ErrNoRows para sentinelas de domínio ErrNotFound. Não vaze erros do driver para clientes de API.
• Nomeie consultas em logs/métricas (repo.GetOrder). Evite logar SQL completo com segredos em produção.
• Feche rows e stmt com defer em repositórios. Vazamentos esgotam o pool.

D - Transações e migrações

• Use defer tx.Rollback() imediatamente após BeginTx. Faça o Commit apenas no caminho de sucesso.
• Mantenha transações curtas; lógica de negócios fora da tx quando possível. Transações longas seguram locks e conexões do pool.
• Execute migrações de esquema no job de implantação ou container de inicialização, não por requisição. A tabela de versão é a fonte da verdade.
• Exija down ou irreversibilidade documentada na revisão de migração. CI aplica up em DBs efêmeros.
• Nunca edite arquivos de migração já aplicados. Correções somente para frente em novos arquivos.

E - ORM, cache e assíncrono (quando usado)

• Se estiver usando GORM/sqlx, ainda ajuste o pool *sql.DB subjacente. ORM não remove o trabalho de operações.
• Logue ou trace SQL do ORM em staging para capturar N+1 antes da produção. Revisão de Preload em caminhos críticos.
• Cache-aside: TTL mais invalidação em escritas. Redis não é autoritativo para invariantes relacionais.
• Publique trabalho assíncrono após o commit SQL (padrão outbox ou transacional). Consumidores não devem ler linhas não commitadas.
• Passe ctx para handlers Redis/NATS/Kafka. O desligamento drena workers cooperativamente.

F - Segurança, testes e observabilidade

• Separe o usuário DDL de migração do usuário de runtime da aplicação. Menor privilégio em roles de produção.
• Testes de integração atingem SQL real (sqlite, testcontainers) para repositórios. sqlmock apenas para pontas de unidade.
• Rastreie histogramas de latência de consulta marcados pelo nome da operação. Dashboards SLO por dependência.
• Execute -race em código que compartilha repositórios entre goroutines. Captura estado compartilhado inseguro acima do SQL.
• Documente o runbook de consultas lentas: estatísticas do pool, consultas ativas, caminhos de cancelamento. On-call lê uma página.

FAQs

Relacionado

• Acesso a Dados em Go: database/sql como Fundação - âncora conceitual
• Pooling de Conexões e Timeouts do database/sql - detalhe de ajuste de pool
• Transações, Prepared Statements & sql.Tx - disciplina de tx
• Migrações com golang-migrate & goose - jobs de migração CI
• contexto em database/sql & gRPC - ligação de cancelamento

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos da placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).