Estándares de Nomenclatura y Documentación
Una nomenclatura consistente y la documentación dentro de la base de datos reducen el tiempo de incorporación y previenen migraciones incompatibles entre equipos. Los diagramas ER en git se mantienen versionados con el esquema que describen.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
COMMENT ON TABLE orders IS 'Cabecera de compra del cliente; particionada por created_at trimestralmente.';
COMMENT ON COLUMN orders.status IS 'open|paid|shipped|closed; ver orders_status_enum.';
COMMENT ON COLUMN orders.legacy_total IS
'OBSOLETO 2026-03: usar total_cents. Eliminar después del release 4.2.';# Exportar diagrama de esquema en CI (ejemplo: schemaspy, dbml-cli)
dbml2sql schema.dbml -o docs/erd/orders.dbml.sql
git add docs/erd/orders.dbmlCuándo usar esto: Inicio de un nuevo servicio, integración de adquisición o mandato del consejo para cobertura de documentación.
Ejemplo de Trabajo
La nueva tabla subscriptions se envía con comentarios y PR de ERD.
CREATE TABLE subscriptions (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id uuid NOT NULL REFERENCES tenants(id),
plan_code text NOT NULL,
started_at timestamptz NOT NULL DEFAULT now(),
ends_at timestamptz
);
COMMENT ON TABLE subscriptions IS 'Suscripciones de facturación activas por inquilino.';
COMMENT ON COLUMN subscriptions.plan_code IS 'FK a plans.code; no uuid para herramientas de soporte humano.';// docs/erd/billing.dbml
Table subscriptions {
id uuid [pk]
tenant_id uuid [ref: > tenants.id]
plan_code text
}Lo que esto demuestra:
- Los comentarios explican por qué, no solo qué tipo de columna es.
- Fechas de obsolescencia en
COMMENT ON COLUMNpara el seguimiento de la fase de contrato. - DBML (o similar) en git para diffs de ERD revisables.
Análisis Profundo
Reglas de Nomenclatura
| Objeto | Convención | Ejemplo |
|---|---|---|
| Tabla | snake_case plural | invoice_line_items |
| Columna | snake_case | created_at |
| Índice | {tabla}_{columnas}_{sufijo} | orders_tenant_created_idx |
| Restricción | {tabla}_{desc}_{tipo} | orders_total_positive_chk |
| Tipo Enum | {dominio}_{campo}_enum | order_status_enum |
Evitar abreviaturas excepto id, url, uuid.
Documentación Requerida
- Cada tabla pública:
COMMENT ON TABLE. - Cada columna no obvia: significado de negocio o referencia a enum.
- Relaciones FK visibles en ERD y forzadas en DDL.
- Cambios disruptivos anotados en el comentario antes de eliminar.
Flujo de Trabajo de ERD en Git
1. Autor actualiza schema.dbml en la rama de características
2. El PR muestra la imagen del diff de ERD desde CI
3. Se genera SQL de migración o se sincroniza manualmente para que coincida
4. Orden de fusión: ADR (si es necesario) → ERD → migraciónTrampas
- Los comentarios se desvían de la realidad - Nadie actualiza después de renombrar. Solución: El PR de migración debe actualizar el comentario en el mismo commit.
- ERD solo en Lucidchart - No en revisión. Solución: DBML/Mermaid en el repositorio; enlace desde README.
- Notación húngara -
strCustomerNameen SQL. Solución: Lint en la lista de verificación de revisión de SQL. - Nombres genéricos - columnas
data,value,info. Solución: Requerir término de dominio en el nombre de la columna. - Enums sin documentar - Constantes solo en la aplicación. Solución:
ENUMde Postgres o restricción de verificación documentada en el comentario.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| ENUM de Postgres | Conjunto cerrado y estable | Los valores cambian semanalmente |
| Restricción de verificación | Validación flexible | Necesidad de exportar tipo a ORM |
| Catálogo de datos externo | Metadatos empresariales | Sobrecarga de equipo pequeño |
| Solo OpenAPI | Servicio API-first | La DB es un punto de integración |
Preguntas Frecuentes
¿Son visibles los comentarios para los ORM?
Algunas herramientas los leen; la audiencia principal son humanos y exportadores de catálogos de datos.
¿DBML vs pgModeler?
DBML se diferencia bien en git; elige la herramienta que exporte formato de texto.
¿Límite de longitud del comentario?
PostgreSQL permite cadenas largas; mantén menos de 500 caracteres para legibilidad.
¿Documentar vistas y Vistas Materializadas (MV)?
Sí; incluye el horario de actualización en el comentario para vistas materializadas.
¿Nombres de columna no en inglés?
Inglés canónico en el esquema; localizar en la capa de aplicación.
¿Generar comentarios automáticamente desde el ORM?
El significado de negocio escrito a mano sigue siendo necesario; la generación de código es insuficiente por sí sola.
¿Documentación de columnas sensibles?
Comentar "PII - sujeto a política de retención" sin valores de ejemplo.
¿Quién aprueba las excepciones de nomenclatura?
Consejo de base de datos con ADR para nombres de tabla no estándar.
¿Diff de esquema en PR?
Usar migra o atlas schema diff contra una instantánea de staging.
¿Qué debo leer a continuación?
Relacionado
- Conceptos Básicos de Gobernanza - resumen del programa
- Reglas de Nomenclatura y Estilo - reglas del equipo
- Plantilla ADR para Postgres - excepciones
- Conceptos Básicos de Git para Trabajo en Bases de Datos - esquema versionado
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+.