Mejores Prácticas para Bases de Datos y Acceso a Datos

Plazos de contexto, dimensionamiento de pools y observabilidad para consultas.

Aplica estas reglas en la revisión de código, plantillas de servicios y runbooks para que cada manejador, repositorio y trabajador trate el SQL como un recurso compartido con propiedad clara y límites de cancelación.

Cómo Usar Esta Lista

• Marca las reglas a medida que tu plantilla de servicio las adopte.
• Codifica los elementos de Nivel A en CI (lint de migraciones, Query sin Context prohibido) donde sea posible.
• Publica una tabla de tiempos de espera y pools junto al README del servicio.
• Revisa al añadir réplicas, réplicas de lectura o capas de caché.

A - Pool y ciclo de vida de la conexión

• Un pool de *sql.DB por DSN por proceso, cableado en main. Evita que init() abra bases de datos de producción.
• Establece MaxOpenConns a partir de cálculos de capacidad (db_max / réplicas). Previene incidentes de too many connections.
• Establece límites de inactividad y vida útil explícitamente. No confíes en los valores predeterminados ilimitados bajo balanceadores de carga.
• PingContext al inicio con tiempo de espera de arranque. Falla el despliegue antes de que el tráfico llegue a DSNs incorrectos.
• Exporta db.Stats() a métricas (WaitCount, InUse, Idle). Alerta sobre el crecimiento de la espera del pool.

B - Contexto, tiempos de espera y métodos SQL

• Usa métodos de base de datos *Context en cada ruta con ámbito de solicitud. Prohíbe Query/Exec sin Context en manejadores.
• Deriva los tiempos de espera de la base de datos del ctx del manejador o RPC, no de Background(). Preserva la cancelación del cliente.
• Publica un presupuesto de tiempo de espera por consulta o por repositorio. La base de datos, la caché y las llamadas HTTP salientes obtienen una porción.
• Empareja el contexto con statement_timeout de SQL cuando los drivers se retrasan. Defensa en profundidad para consultas descontroladas.
• Devuelve ctx.Err() cuando la cancelación termina una consulta. Mapea al estado HTTP/gRPC correcto en el borde.

C - Límites del repositorio y saneamiento de SQL

• Mantén el SQL en paquetes de repositorio/almacenamiento, no en manejadores HTTP. Los manejadores permanecen delgados en cuanto al transporte.
• Usa marcadores de posición para todos los valores dinámicos. Nunca concatenes la entrada del usuario en cadenas SQL.
• Mapea sql.ErrNoRows a centinelas de dominio ErrNotFound. No expongas errores del driver a los clientes de la API.
• Nombra las consultas en logs/métricas (repo.GetOrder). Evita registrar SQL completo con secretos en producción.
• Cierra rows y stmt con defer en los repositorios. Las fugas agotan el pool.

D - Transacciones y migraciones

• defer tx.Rollback() inmediatamente después de BeginTx. Confirma solo en la ruta de éxito.
• Mantén las transacciones cortas; lógica de negocio fuera de tx cuando sea posible. Las transacciones largas retienen bloqueos y conexiones del pool.
• Ejecuta migraciones de esquema en el trabajo de despliegue o contenedor de inicialización, no por solicitud. La tabla de versiones es la fuente de verdad.
• Requiere down o irreversibilidad documentada en la revisión de migraciones. CI aplica up en una base de datos efímera.
• Nunca edites archivos de migración ya aplicados. Correcciones solo hacia adelante en nuevos archivos.

E - ORM, caché y asíncrono (cuando se usa)

• Si usas GORM/sqlx, aún ajusta el pool subyacente de *sql.DB. El ORM no elimina el trabajo de operaciones.
• Registra o rastrea el SQL del ORM en staging para detectar N+1 antes de producción. Revisión de Preload en rutas activas.
• Patrón Cache-Aside: TTL más invalidación en escrituras. Redis no es autoritativo para invariantes relacionales.
• Publica trabajo asíncrono después del commit de SQL (patrón outbox o transaccional). Los consumidores no deben leer filas no confirmadas.
• Pasa ctx a los manejadores de Redis/NATS/Kafka. El apagado vacía los trabajadores de forma cooperativa.

F - Seguridad, pruebas y observabilidad

• Separa el usuario DDL de migración del usuario de aplicación en tiempo de ejecución. Mínimo privilegio en roles de producción.
• Las pruebas de integración acceden a SQL real (sqlite, testcontainers) para repositorios. sqlmock solo para los bordes de las unidades.
• Rastrea histogramas de latencia de consultas etiquetados por nombre de operación. Dashboards de SLO por dependencia.
• Ejecuta -race en código que comparte repositorios entre goroutines. Detecta estado compartido inseguro por encima de SQL.
• Documenta el runbook de consultas lentas: estadísticas del pool, consultas activas, rutas de cancelación. El personal de guardia lee una página.

Preguntas Frecuentes

Relacionado

• Acceso a Datos en Go: database/sql como Fundación - ancla conceptual
• Pooling de Conexiones y Tiempos de Espera de database/sql - detalle de ajuste de pool
• Transacciones, Sentencias Preparadas y sql.Tx - disciplina de tx
• Migraciones con golang-migrate & goose - trabajos de migración CI
• context en database/sql & gRPC - cableado de cancelación

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).