19. Documentación de bases de datos: modelo, tablas, restricciones, índices y migraciones
19.1 Introducción
La base de datos suele concentrar información crítica del sistema. Allí se almacenan usuarios, operaciones, estados, historial, configuraciones, relaciones y datos del negocio. Por eso, su documentación es esencial para desarrollo, pruebas, soporte, operación, seguridad y mantenimiento.
Documentar una base de datos no significa copiar todas las sentencias SQL sin explicación. Significa describir el modelo de datos, el significado de tablas y campos, las relaciones, restricciones, índices, migraciones, políticas de acceso y cuidados necesarios para modificar información.
Una base de datos mal documentada aumenta el riesgo de interpretar mal datos, romper integridad, duplicar información o ejecutar cambios peligrosos en producción.
19.2 Qué incluye la documentación de bases de datos
La documentación de bases de datos puede incluir modelo conceptual, modelo lógico, modelo físico, diccionario de datos, relaciones, claves, restricciones, índices, migraciones, datos sensibles, reglas de retención, respaldos y procedimientos de recuperación.
El nivel de detalle depende de la audiencia. Un analista puede necesitar entender entidades y relaciones del dominio. Un desarrollador necesita tablas, campos, restricciones y consultas relevantes. Operación necesita respaldos, restauración y crecimiento. Seguridad necesita datos sensibles y controles de acceso.
19.3 Elementos principales
La imagen muestra los elementos centrales de la documentación de bases de datos: modelo de datos, tablas, campos, relaciones, claves, restricciones, índices, migraciones, datos sensibles y respaldos. Cada elemento ayuda a comprender y mantener la información del sistema.
19.4 Modelo conceptual
El modelo conceptual describe conceptos del dominio y sus relaciones, sin entrar en detalles físicos de tablas, tipos de datos o índices. Es útil para alinear lenguaje entre negocio y equipo técnico.
En un sistema de turnos, el modelo conceptual puede incluir Paciente, Profesional, Especialidad, Agenda y Turno. Este modelo ayuda a comprender qué representa cada concepto y cómo se vincula con otros.
No debe confundirse con el esquema de base de datos. Puede haber diferencias entre conceptos del dominio y tablas físicas por motivos técnicos.
19.5 Modelo lógico y físico
El modelo lógico describe entidades, atributos y relaciones con mayor precisión. El modelo físico muestra cómo se implementan esos elementos en una base de datos concreta: tablas, columnas, tipos, claves, índices y restricciones.
Ambos niveles son útiles. El modelo lógico ayuda a razonar sobre datos sin depender de un motor específico. El modelo físico es necesario para implementar, optimizar y operar la base de datos real.
La documentación debe aclarar qué nivel está mostrando para evitar confusión.
19.6 Tablas
Cada tabla importante debería tener una descripción de propósito. No alcanza con listar su nombre. Debe explicarse qué información almacena, qué entidad o relación representa, quién la modifica y qué cuidados requiere.
Por ejemplo, una tabla turnos puede almacenar reservas de atención con paciente, profesional, fecha, hora, estado y marca de auditoría. Esa explicación ayuda a distinguirla de una tabla de disponibilidad o agenda.
19.7 Campos y diccionario de datos
Un diccionario de datos describe campos o columnas. Para cada campo conviene indicar nombre, tipo, obligatoriedad, descripción, valores permitidos, ejemplo, reglas asociadas y si contiene información sensible.
Esto evita interpretaciones incorrectas. Un campo llamado estado puede parecer evidente, pero es necesario saber qué valores acepta y qué significa cada uno. Un campo llamado fecha puede requerir aclarar si representa fecha de creación, fecha del turno o fecha de modificación.
19.8 Claves y relaciones
Las claves primarias identifican registros. Las claves foráneas relacionan tablas. Documentarlas permite entender dependencias entre datos y reglas de integridad.
En un sistema de turnos, un turno puede relacionarse con un paciente y un profesional. Si se elimina un profesional, hay que saber qué ocurre con sus turnos. Esa regla puede estar implementada como restricción, política de negocio o procedimiento administrativo.
19.9 Restricciones
Las restricciones protegen integridad de datos. Pueden indicar campos obligatorios, valores únicos, límites, relaciones válidas, estados permitidos o reglas de borrado.
Documentar restricciones ayuda a comprender qué errores puede devolver la base de datos y qué reglas no deben violarse desde la aplicación. También ayuda a pruebas y soporte cuando aparecen fallas por datos inválidos.
19.10 Índices
Los índices mejoran el rendimiento de consultas, pero también tienen costo de almacenamiento y escritura. La documentación de índices debe explicar por qué existen, qué consulta optimizan y qué columnas incluyen.
Un índice creado sin motivo claro puede quedar obsoleto. Un índice faltante puede generar lentitud. Documentar índices relevantes ayuda a revisar rendimiento y planificar cambios.
19.11 Migraciones
Las migraciones registran cambios en el esquema o datos de la base. Pueden crear tablas, agregar columnas, modificar restricciones, actualizar datos o crear índices. Documentarlas permite conocer la evolución del modelo.
Una buena documentación de migraciones debe indicar objetivo, impacto, orden de ejecución, compatibilidad con versiones de aplicación y riesgos. En producción, una migración mal planificada puede causar caída del sistema o pérdida de datos.
19.12 Datos sensibles
La documentación debe identificar datos sensibles: datos personales, credenciales, información médica, financiera, tokens, direcciones, documentos o cualquier dato protegido por políticas internas o regulaciones.
Además de identificar estos datos, conviene documentar controles: cifrado, anonimización, acceso por rol, auditoría, retención, eliminación y restricciones para ambientes de prueba.
No se deben incluir valores reales sensibles en documentación pública o compartida sin control.
19.13 Tabla de diccionario de datos
| Campo | Tipo | Descripción | Restricciones |
|---|---|---|---|
turno_id |
Número | Identificador único del turno. | Clave primaria. |
paciente_id |
Número | Paciente asociado a la reserva. | Obligatorio, clave foránea. |
fecha_hora |
Fecha y hora | Momento programado del turno. | Obligatorio. |
estado |
Texto | Estado actual del turno. | Disponible, reservado, cancelado, atendido o ausente. |
19.14 Auditoría e historial
Muchos sistemas necesitan saber quién creó, modificó o eliminó datos y cuándo ocurrió. La documentación debe explicar campos de auditoría, tablas históricas, bitácoras y reglas de conservación.
Esto es importante para soporte, seguridad, cumplimiento y análisis de incidentes. Si un turno fue cancelado, puede ser necesario saber quién lo canceló, cuándo y con qué motivo.
19.15 Respaldos y restauración
La documentación de bases de datos debe relacionarse con respaldos y restauración. No basta con tener respaldo; debe saberse con qué frecuencia se realiza, dónde se guarda, cómo se valida y cómo se restaura.
También conviene documentar objetivos de recuperación, ventanas de mantenimiento, responsables y procedimientos de prueba. Un respaldo que nunca se probó puede fallar cuando más se necesita.
19.16 Errores frecuentes
Al documentar bases de datos suelen aparecer estos errores:
- Listar tablas sin explicar qué representan.
- No documentar el significado de campos con nombres ambiguos.
- Omitir restricciones, claves e índices relevantes.
- No indicar qué datos son sensibles.
- No documentar impacto y orden de migraciones.
- Confundir modelo conceptual con esquema físico.
- No mantener la documentación sincronizada con cambios de esquema.
19.17 Qué debes recordar de este tema
- La documentación de bases de datos explica significado, estructura y restricciones de la información.
- Debe distinguir modelo conceptual, lógico y físico.
- Las tablas y campos importantes necesitan descripción clara.
- Claves, relaciones, restricciones e índices ayudan a comprender integridad y rendimiento.
- Las migraciones deben documentar objetivo, impacto y riesgos.
- Los datos sensibles requieren identificación y controles específicos.
- Respaldos y restauración forman parte de la documentación operativa de datos.
19.18 Conclusión
Documentar bases de datos permite entender y proteger uno de los activos más importantes del software: la información. Un modelo claro, un diccionario de datos preciso y una buena descripción de restricciones, índices y migraciones reducen errores de mantenimiento.
En el próximo tema estudiaremos la documentación de instalación y configuración del sistema.