Deje de dibujar diagramas ER a mano

Cuando dibuja un diagrama entidad-relación con una herramienta gráfica, cada tabla nueva significa volver a conectar líneas a mano, y tarde o temprano el dibujo se desincroniza del esquema real. Con erDiagram de Mermaid, el diagrama es texto plano: vive en su repositorio, aparece en los diffs y se renderiza automáticamente en READMEs de GitHub, pull requests, Notion y la mayoría de los visores de Markdown.

Este artículo es una referencia para consultar rápidamente: una chuleta de cardinalidad, la sintaxis de atributos, un ejemplo real completo y, al final, una forma de generar todo esto automáticamente a partir de SQL existente.

El ejemplo mínimo: empiece con tres líneas

erDiagram
    USERS ||--o{ POSTS : "has"

Esto ya renderiza “USERS a POSTS, uno a muchos (un usuario tiene cero o más publicaciones)”. La forma general es:

<entidad1> <cardinalidad-izq><línea><cardinalidad-der> <entidad2> : "etiqueta"

Algo que conviene saber de entrada: la etiqueta de relación después de los dos puntos es obligatoria. Si no quiere texto visible, escriba : "" — omitirla por completo es un error de sintaxis, y es el primer tropiezo más común.

Símbolos de cardinalidad: la chuleta

Las cardinalidades de erDiagram usan la notación de pata de gallo (crow’s foot). Los símbolos siempre apuntan hacia afuera, hacia su entidad.

Símbolo izquierdoSímbolo derechoSignificado
|oo|Cero o uno
||||Exactamente uno
}oo{Cero o más
}||{Uno o más

Las combinaciones concretas son la forma más rápida de memorizarlas:

SintaxisLectura
A ||--o{ BUn A, cero o más B (la relación uno a muchos más habitual)
A ||--|{ BUn A, al menos un B
A |o--o| BUno a uno opcional
A ||--|| BUno a uno estricto
A }o--o{ BMuchos a muchos (conceptual, antes de añadir una tabla intermedia)

Línea sólida frente a punteada: identificante frente a no identificante

El segmento de línea viene en dos variantes:

LíneaSignificadoUso típico
--Identificante (sólida)La clave primaria del hijo incluye la PK del padre (p. ej., líneas de un pedido)
..No identificante (punteada)El hijo referencia al padre mediante una FK ordinaria (p. ej., una publicación y su autor)
ORDERS ||--|{ ORDER_ITEMS : "contains"     %% identificante (sólida)
USERS  ||..o{ POSTS       : "writes"       %% no identificante (punteada)

%% inicia un comentario. Decida en equipo si va a distinguir relaciones identificantes o si estandariza en líneas sólidas — ambas opciones funcionan, pero la consistencia mantiene los diagramas legibles.

Definir atributos (columnas)

Añada un bloque {} a una entidad para renderizar sus columnas como una tabla:

erDiagram
    USERS {
        int id PK "autoincremental"
        varchar(255) email UK "ID de acceso"
        varchar(100) name
        datetime created_at
    }

Cada línea sigue el formato tipo nombre [clave] ["comentario"]:

  • Las claves son PK / FK / UK, y pueden combinarse separadas por comas (PK, FK) — esencial para tablas intermedias con claves compuestas
  • Los tipos pueden contener paréntesis, como varchar(255) o decimal(10)
  • Los comentarios van entre comillas dobles

Un ejemplo real: pedidos de comercio electrónico

Todo lo anterior en un diagrama completo y listo para copiar y pegar:

erDiagram
    USERS ||--o{ ORDERS : "places"
    ORDERS ||--|{ ORDER_ITEMS : "contains"
    PRODUCTS ||--o{ ORDER_ITEMS : "included in"

    USERS {
        int id PK
        varchar(255) email UK
        varchar(100) name
        datetime created_at
    }
    ORDERS {
        int id PK
        int user_id FK
        varchar(20) status
        datetime ordered_at
    }
    ORDER_ITEMS {
        int order_id PK, FK
        int product_id PK, FK
        int quantity
        decimal(10) unit_price
    }
    PRODUCTS {
        int id PK
        varchar(200) name
        decimal(10) price
    }

Lo interesante está en ORDER_ITEMS: la relación muchos a muchos entre pedidos y productos se resuelve en una tabla intermedia con clave primaria compuesta (dos columnas PK, FK), y la regla de negocio “un pedido siempre tiene al menos una línea” queda expresada mediante la cardinalidad ||--|{.

Trampas comunes y cómo evitarlas

  • La etiqueta de relación es obligatoria. Use : "" para ocultarla
  • Prefiera nombres de entidad en ASCII. El renderizado de nombres no-ASCII varía entre entornos; mantenga los nombres de tabla en inglés y ponga el idioma local en las etiquetas o comentarios
  • Muchos a muchos (}o--o{) es solo para diagramas conceptuales. Resuélvalo en una tabla intermedia antes de la implementación
  • ¿El diagrama no se renderiza en GitHub? Compruebe que el lenguaje del bloque de código sea exactamente ```mermaid

Generarlo a partir de sentencias CREATE TABLE

A partir de unas diez tablas, escribir esta sintaxis a mano se vuelve tedioso. Si ya tiene el DDL, péguelo en el conversor de SQL a diagrama ER — analiza claves primarias, claves foráneas y relaciones, y genera automáticamente un diagrama ER en Mermaid.

Generando un diagrama ER en Mermaid a partir de sentencias CREATE TABLE con la herramienta SQL a ER

Todo se ejecuta enteramente en su navegador, por lo que la información confidencial del esquema nunca sale de su equipo. Genere el diagrama base y luego ajústelo con la chuleta anterior. Para un recorrido por la herramienta en sí, consulte Cómo generar un diagrama ER desde SQL DDL.

Preguntas frecuentes

¿Cuál es la forma correcta de escribir una relación uno a muchos?

PADRE ||--o{ HIJO es la forma estándar (un padre, cero o más hijos). Use ||--|{ solo cuando “debe existir al menos un hijo” sea una regla de negocio real que quiera reflejar en el diagrama. En caso de duda, ||--o{ es la opción segura por defecto.

¿Puedo dibujar relaciones sin definir atributos?

Sí. erDiagram renderiza las entidades referenciadas en las líneas de relación aunque no tengan bloques {}. Un flujo de trabajo práctico es esbozar solo las relaciones durante el diseño inicial y añadir los bloques de atributos una vez que el esquema se estabilice.

¿Dónde se pueden renderizar los diagramas ER de Mermaid?

GitHub (READMEs, issues, pull requests), GitLab, Notion, VS Code (con extensiones), Obsidian y la mayoría de los entornos Markdown modernos renderizan de forma nativa los bloques de código Mermaid. Para cualquier otro caso, exporte a SVG/PNG con el editor en vivo de Mermaid.

¿Se puede implementar directamente una relación muchos a muchos?

No — A }o--o{ B es una notación conceptual. Las bases de datos relacionales requieren una tabla intermedia (clave primaria compuesta más dos claves foráneas), como se muestra en el ejemplo de comercio electrónico anterior. Escribir la forma resuelta en el diagrama desde el principio ahorra retrabajo en la implementación.