Mejores Prácticas para Reglas de PostgreSQL

Cómo hacer que las reglas del proyecto Postgres se apliquen: automatiza el linting, integra comprobaciones en CI y mantén la revisión humana para lo que las máquinas no pueden juzgar.

Cómo Usar Esta Lista

• Empieza con la automatización (sección A) antes de escribir más reglas de texto.
• Alinea las plantillas de PR con los elementos de la lista de verificación de la sección B.
• Audita la deriva de las reglas trimestralmente usando la sección C.

A - Automatización

• SQLFluff (o sql-lint) en db/migrations/** en CI. Falla el PR en violaciones de análisis y formato.
• Lint personalizado: requiere SET lock_timeout en archivos de migración. Comprobación de expresiones regulares o AST en el pipeline.
• Scripts de humo pgTAP o psql post-migración. Asertos de esquema automatizados.
• Convenciones de nomenclatura de SQLFluff que coinciden con ADR. snake_case, prefijo de índice idx_.
• Hook de pre-commit localmente refleja CI. Los desarrolladores ven los fallos antes de hacer push.

B - Puertas de Revisión

• Casilla de verificación de la plantilla de PR: EXPLAIN adjunto para nuevas consultas de ruta crítica. Enlace a la salida de EXPLAIN (ANALYZE, BUFFERS).
• Revisión de DBA requerida para tablas con > 10M de filas o DDL ACCESS EXCLUSIVE. CODEOWNERS en la carpeta de migraciones.
• Revisión de seguridad cuando se tocan RLS, BYPASSRLS o SECURITY DEFINER. Sin sello de goma en cambios de política.
• ADR archivado para cambios de topología, multi-inquilino o motor. No para cada adición de columna.
• Alternativas rechazadas anotadas en ADR. Los equipos futuros entienden las compensaciones.

C - Estándares Vivos

• Ejecución trimestral de la Lista de Verificación de Reglas del Proyecto Postgres. Seguimiento de la tendencia de aprobados/fallidos.
• Actualización post-incidente de las reglas dentro de los 5 días hábiles. Los incidentes enseñan lo que las listas de verificación se perdieron.
• El documento de incorporación enlaza reglas + conceptos básicos de psql + mínimo privilegio. Un camino para nuevos ingenieros.
• Aumento de versión de las reglas del documento al actualizar PostgreSQL a una versión mayor. Cambios de comportamiento (DDL, planificador) requieren una actualización de las reglas.
• Retirar reglas que la automatización impone. Reemplaza las viñetas manuales con IDs de reglas del linter en los documentos.

D - Ejemplos de Herramientas

# Ejemplo de SQLFluff CI
sqlfluff lint db/migrations --dialect postgres
 
# Comprobación personalizada de cabecera de migración
grep -L "lock_timeout" db/migrations/V*.sql && exit 1 || true

# Extracto de CODEOWNERS
/db/migrations/  @data-platform-team
/docs/adr/       @staff-engineers @dba-team

• Fija la versión de SQLFluff en CI para obtener resultados de lint reproducibles.
• Documenta las supresiones con -- noqa: RULE y justificación de PR solamente.

E - Cultura

• Las reglas son barreras de protección, no burocracia - explica por qué en una línea cada una. Mejora la retención en la incorporación.
• Horas de oficina de SME para preguntas sobre reglas. Reduce las soluciones alternativas de TI en la sombra.
• Celebra las detecciones atrapadas en CI. Refuerza la inversión en automatización.
• Ninguna excepción en producción sin enmienda de ADR con tiempo limitado. Las excepciones se pudren y se convierten en valores predeterminados.
• Sincroniza las reglas con los IDs de control de seguridad/cumplimiento. Los auditores SOC2 mapean las comprobaciones a la evidencia.

Preguntas Frecuentes

Relacionados

• Lista de Verificación de Reglas del Proyecto Postgres - 25 elementos de auditoría
• Reglas de Nomenclatura y Estilo - Entrada de configuración de SQLFluff
• Conceptos Básicos de Git para Trabajo con Bases de Datos - Flujo de trabajo de PR

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.