Resumen de las Reglas de PostgreSQL

Esta sección se lee como una lista de instrucciones arbitrarias: usa snake_case, ejecuta EXPLAIN antes de fusionar, establece lock_timeout en las migraciones, nunca conectes la aplicación como superusuario.

Cada una es en realidad el residuo comprimido de algo que ya salió mal una vez, generalizado en una instrucción lo suficientemente barata de seguir sin tener que re-aprender el incidente original.

Resumen

• Una regla de PostgreSQL es un modo de fallo específico y previamente aprendido, convertido en una instrucción que el próximo ingeniero puede seguir sin redescubrir el problema de primera mano.
• Por Qué Importa: Tratar cada regla como igualmente arbitraria o igualmente obligatoria pierde la pregunta real, que es cuánto cuesta realmente una violación específica si ocurre.
• Conceptos Clave: regla vs. preferencia, nivel de aplicación, verificabilidad, ADR (Registro de Decisiones de Arquitectura), degradación de reglas.
• Cuándo Usar: Decidir si una nueva convención merece una regla escrita, elegir cuán estrictamente aplicar una, o evaluar si una regla antigua todavía merece su lugar.
• Limitaciones / Compensaciones: Las reglas intercambian el juicio individual por la consistencia, y un documento de reglas que solo crece y nunca se revisa se convierte en fricción en lugar de protección.
• Temas Relacionados: convenciones de nomenclatura y estilo, seguridad de migraciones, estándares de índices y consultas, endurecimiento de la seguridad.

Fundamentos

Cada regla duradera en esta sección comienza desde el mismo lugar: una consulta derribó una tabla, una migración se quedó bloqueada por un bloqueo, o un esquema alcanzó una ambigüedad que nadie había resuelto de antemano.

La instrucción que sigue, "ejecuta EXPLAIN antes de fusionar una nueva consulta" o "establece lock_timeout en cada migración", es más barata de decir y seguir que el incidente que costó vivir, que es el propósito de escribir reglas.

Ese marco separa una regla de una preferencia de estilo, incluso si ambas pueden vivir en el mismo documento y parecer igualmente concisas en la página.

Una preferencia de estilo, como nombres de tabla en singular versus plural, no tiene ningún modo de fallo detrás; nada se rompe de ninguna manera, por lo que el único costo de la inconsistencia es la legibilidad y la fricción de búsqueda en la base de código.

Una regla, en el sentido que esta sección usa la palabra, existe porque equivocarse tiene un costo real y descriptible, una interrupción, una brecha de seguridad o una migración de varias horas que debería haber tomado segundos.

Una analogía útil: un documento de reglas es el tejido cicatricial de una base de código hecho legible, cada cicatriz marca un lugar donde el equipo fue realmente herido, protegiendo aún contra una repetición mucho después de que el corte original se olvide.

Mecánicas e Interacciones

No todas las reglas merecen la misma fuerza de aplicación, y emparejar la aplicación con el costo real es la mayor parte de lo que separa un documento de reglas útil de una lista que nadie lee.

Las reglas en esta sección se encuentran en un espectro aproximado, desde convención documentada, esperada en revisión pero no verificada mecánicamente, hasta aplicada en revisión de código, donde se espera que un humano la detecte, hasta aplicada en CI, donde una regla de lint o una prueba falla automáticamente la compilación.

sucede un incidente
      │
      ▼
lección escrita          ── convención documentada
      │  (el patrón se repite, es verificable)
      ▼
los revisores la vigilan   ── aplicada en revisión de código
      │  (una herramienta puede expresarla)
      ▼
la puerta mecánica la bloquea ── aplicada en CI

Una regla generalmente comienza en la parte superior de esa cadena, porque alguien acaba de aprender la lección y la escribió, y se gana su camino hacia una puerta de CI solo una vez que el equipo confirma dos cosas: el patrón realmente se repite y es el tipo de cosa que una verificación mecánica puede detectar de manera confiable.

Forzar una regla dependiente del juicio directamente en una puerta de CI antes de que sea verificable de manera confiable produce falsos positivos, y los falsos positivos enseñan a los ingenieros a evitar la puerta en lugar de confiar en ella.

La Lista de Verificación de Reglas del Proyecto Postgres es la versión concreta y escalonada de esta idea aplicada a escala de proyecto: sus 25 elementos se agrupan por cuán bloqueantes para el lanzamiento son, lo cual es en sí mismo una aplicación de "no todas las reglas merecen la misma urgencia".

Consideraciones Avanzadas y Aplicaciones

Un proceso de excepciones es lo que evita que una regla aplicada mecánicamente se convierta en burocracia frágil la primera vez que se encuentra con un caso límite legítimo que no anticipó.

Sin uno, un equipo rompe la regla en silencio, socavándola para todos los que confiaron en la puerta, o bloquea un cambio genuinamente válido, socavando la confianza en el propio proceso.

La Plantilla ADR para Postgres existe precisamente para esta situación: un Registro de Decisiones de Arquitectura hace que una desviación de la regla predeterminada sea visible y deliberada en lugar de invisible.

Las reglas también acumulan un tipo específico de decadencia que vale la pena nombrar directamente, degradación de reglas, donde una instrucción sigue siendo aplicada mucho después de que la situación que la justificó ha cambiado.

Una regla de uso de índices revisada manualmente antes de que pg_stat_statements fuera estándar en todos los entornos podría ya no valer la pena una vez que la revisión automatizada de consultas se ejecute en cada PR, no porque la regla fuera incorrecta, sino porque herramientas mejores ahora cubren el mismo objetivo subyacente.

Las reglas que nombran el fallo específico que previenen envejecen mejor que las reglas declaradas como instrucción pura, porque un equipo que revisa "por qué hacemos esto" puede juzgar realmente si ese fallo sigue siendo un riesgo activo antes de decidir mantener, relajar o automatizar aún más la regla.

Conceptos Erróneos Comunes

• "Las reglas de esta sección son solo preferencias de estilo con pasos adicionales." Una elección de estilo como nombres de tabla en plural no tiene un modo de fallo; una regla como "no rol de aplicación de superusuario" existe específicamente porque violarla tiene un costo real y descriptible.
• "Escribir una regla es lo mismo que aplicarla." Una regla no aplicada solo dura mientras cada ingeniero la recuerde y elija seguirla, que es precisamente la brecha que los niveles de aplicación existen para cerrar.
• "Cada regla en esta sección debería eventualmente convertirse en una puerta de CI." Solo los patrones genuinamente verificables pertenecen allí; una regla dependiente del juicio forzada a una puerta mecánica produce falsos positivos que enseñan a los ingenieros a evitarla o desconfiar de ella.
• "Una regla sin excepciones es una regla más fuerte." Una regla absoluta sin una salida de emergencia solo reubica la excepción de "visible y deliberada" a "violada silenciosamente", lo cual es peor para cualquiera que audite el esquema más tarde.
• "Las reglas antiguas en esta lista siempre siguen valiendo la pena seguirlas exactamente como están escritas." Una regla puede sobrevivir a la situación que la justificó, especialmente una vez que mejores herramientas la reemplazan, por lo que la revisión periódica pertenece al mismo proceso que creó la regla.

Preguntas Frecuentes

Relacionado

• Lista de Verificación de Reglas del Proyecto Postgres - la auditoría concreta y escalonada de 25 reglas en la que se basa este modelo
• Reglas de Nomenclatura y Estilo - donde se cruzan las preferencias de estilo y las reglas
• Reglas de Índices y Consultas - un conjunto de reglas concreto y de alta aplicación
• Reglas de Seguridad de Migraciones - convenciones de tiempo de espera de bloqueo y sentencia
• Plantilla ADR para Postgres - cómo se registran deliberadamente las excepciones a una regla

Versiones de Stack: Esta página es conceptual y no está vinculada a una versión específica de stack.