Volver a todas las guías
Diseño de bases de datos··3 min de lectura

Documentación de bases de datos: explica tu esquema SQL con diagramas ERD

Documente esquemas de base de datos con ERD, ejemplos SQL, notas de relación y contexto de migración para que los equipos puedan entender los modelos de Datos más rápido.

Un diagrama de cliente a pedido junto a notas que explican la clave foránea y la regla de negocio
En esta guía
  1. ¿Por qué falla la documentación de la base de datos?
  2. Qué incluir en la documentación del esquema
  3. Bloque de documentación de ejemplo
  4. Un flujo de trabajo de documentación práctico
  5. Referencias y lecturas adicionales

Los ejemplos de SQL utilizan PostgreSQL a menos que se mencione otro dialecto. Los fragmentos cortos asumen que las tablas a las que se hace referencia ya existen. Valide el DDL en su base de datos de destino antes de aplicarlo.

¿Por qué falla la documentación de la base de datos?

La documentación de la base de datos a menudo queda desactualizada porque se escribe por separado del esquema. Alguien crea un diagrama durante el primer sprint de diseño, la base de datos cambia durante seis meses y la documentación silenciosamente se vuelve engañosa.

Un mejor enfoque es mantener la documentación cerca de la fuente SQL. Genere diagramas a partir de DDL, añada explicaciones breves para tablas y relaciones, y actualice los documentos cada vez que cambie el esquema.

Esquema SQL, diagrama ERD, notas de relación y contexto de migración combinados en documentación
Una documentación de base de datos sólida combina la fuente SQL con un ERD y notas breves sobre las relaciones, para que los documentos sigan siendo prácticos.

Qué incluir en la documentación del esquema

La documentación útil de la base de datos responde a las preguntas que los desarrolladores realmente hacen mientras crean funciones y depuran datos de producción.

  • Un ERD. Muestra tablas, claves primarias, claves foráneas y las rutas principales de relación.
  • Notas sobre el propósito de la tabla. Explique por qué existe cada tabla principal y qué funcionalidad la posee.
  • Reglas de relación. Resalte la cardinalidad, las relaciones opcionales y las acciones en cascada.
  • Restricciones importantes. Documente claves únicas, comprobaciones, valores de enumeración y reglas de negocio aplicadas por SQL.
  • Contexto de migración. Vincule los cambios de esquema a la característica, corrección de errores o motivo operativo detrás de ellos.

Bloque de documentación de ejemplo

Una entrada de documentación ligera puede emparejar SQL con notas en lenguaje sencillo:

CREATE TABLE accounts (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL
);

CREATE TABLE invoices (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    account_id  BIGINT NOT NULL REFERENCES accounts (id),
    status      VARCHAR(30) NOT NULL DEFAULT 'draft',
    total       NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
    due_date    DATE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE invoice_payments (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    invoice_id  BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
    amount      NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
    paid_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

Las notas de documentación podrían decir: una cuenta tiene muchas facturas, las facturas tienen muchos registros de pago, y las filas de pago se eliminan si se elimina una factura de prueba. En sistemas de producción con requisitos de auditoría, podría reemplazar las eliminaciones en cascada con eliminaciones restringidas y registros de archivo.

Un flujo de trabajo de documentación práctico

Aquí hay un flujo de trabajo que mantiene los documentos útiles sin convertir la documentación en un trabajo de tiempo completo.

  • Comienza con el esquema SQL y genera un ERD en el Editor de Erd Go.
  • Exportar el diagrama o iniciar sesión, guardarlo y compartir un enlace público de solo lectura cuando el esquema sea apropiado para el acceso público. Use exportaciones de imágenes para documentación privada.
  • Añade un párrafo corto para cada grupo de tablas importante: auth, billing, orders, content, audit o reporting.
  • Regenere el ERD a partir del SQL actualizado durante las migraciones para que la documentación refleje lo que cambió.
  • Mantenga los ejemplos de sintaxis sincronizados con el Documentación DDL de Erd Go para que futuros colaboradores puedan reproducir el diagrama.

El objetivo no es una enciclopedia perfecta. El objetivo es un mapa vivo que ayude a las personas a entender la base de datos rápidamente y a confiar en lo que están leyendo.

Referencias y lecturas adicionales

Más publicaciones