Plantilla de Documentación de Esquema de Base de Datos
Una plantilla para documentar esquemas de base de datos con relaciones entre entidades, definiciones de campos e historial de migraciones.
Nota para desarrolladores hispanohablantes: Esta guía incluye ejemplos y convenciones de nomenclatura adaptadas a equipos que trabajan en español. Cuando existen diferencias significativas en terminología técnica entre el inglés y el español, se indican explícitamente para facilitar la comunicación en equipos multiculturales.
Mejores Prácticas
- Documenta cada tabla y columna — Los desarrolladores futuros (incluyéndote) te lo agradecerán
- Explica el significado de negocio, no solo los tipos —
statuses obvio; por qué existemetadatano lo es - Incluye el “por qué” de los índices — Los índices tienen costo; documenta qué query sirven
- Versiona tus docs de esquema — Rastrea qué cambió y cuándo, como con el código
- Mantén el diagrama ER actualizado — La referencia visual es más rápida que leer SQL para entender relaciones
- Marca columnas deprecadas — No borres docs de columnas eliminadas inmediatamente; márquenlas como deprecated con fecha de remoción
Errores Comunes
- Documentar el esquema una vez y nunca actualizarlo — la documentación obsoleta es peor que ninguna
- Documentar solo tablas, ignorando índices y restricciones — los índices revelan patrones de query
- Usar nombres de columnas vagos sin explicación —
dataovalueno dicen nada - No documentar patrones de soft delete — los nuevos desarrolladores a menudo omiten filtros de
deleted_at - Olvidar documentar valores de enum — ¿qué significa
status = 3?
Preguntas Frecuentes
¿Debería auto-generar docs de esquema desde la base de datos?
Sí, para la línea base estructural. Herramientas como tbls, dbdocs, o comentarios de pg_dump son excelentes puntos de partida. Pero siempre agrega documentación narrativa — el “por qué” detrás de decisiones de diseño no puede extraerse del DDL.
¿Cómo mantengo los docs de esquema sincronizados con la base de datos?
Genera las partes estructurales automáticamente en CI. Reserva secciones manuales (significado de negocio, racional de indexación) para curación humana. Revisa los docs en el mismo PR que cambia el esquema.
¿Qué nivel de detalle es demasiado?
Documenta cualquier cosa que confundiría a un nuevo miembro del equipo o que ya has explicado más de dos veces en Slack. Omite nombres auto-documentables obvios como id en una primary key a menos que haya un default o regla de generación no obvia.