“¿Dónde estaba conectada esta tabla?”

“¿A qué tabla hace referencia este user_id?” “Un momento, ¿esta tabla no la referencia nadie?” — rastrear relaciones leyendo SQL en bruto es como armar un rompecabezas mentalmente.

El conversor de SQL a diagrama ER toma sentencias CREATE TABLE y renderiza al instante las tablas, columnas, claves primarias y foráneas como un diagrama ER de Mermaid. Todo se ejecuta en su navegador — su SQL nunca sale de él.

Generar diagramas ER desde SQL DDL: cómo funciona el análisis de CREATE TABLE

Este artículo explica cómo funciona realmente el analizador de DDL por dentro y, debido a cómo funciona, qué debería saber sobre su cobertura.

Uso

CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  name VARCHAR(255) NOT NULL
);

CREATE TABLE orders (
  id BIGINT PRIMARY KEY,
  user_id BIGINT NOT NULL,
  total_amount INTEGER NOT NULL,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

Al pegar esto, obtiene este código Mermaid erDiagram:

erDiagram
    users {
        BIGINT id PK
        VARCHAR name
    }
    orders {
        BIGINT id PK
        BIGINT user_id
        INTEGER total_amount
    }

    orders }|--|| users : "user_id -> id"

Pegue el código generado directamente en un README de GitHub o en un pull request y se renderiza automáticamente.

Cómo funciona el analizador: descomposición del DDL con expresiones regulares

En lugar de una biblioteca completa de análisis SQL, la herramienta usa un analizador ligero basado en expresiones regulares (SqlParser.parseDdl). Funciona en tres etapas.

1. Eliminar comentarios y dividir en sentencias

const cleanSql = sql
    .replace(/--.*$/gm, '')           // elimina comentarios de línea
    .replace(/\/\*[\s\S]*?\*\//g, '') // elimina comentarios de bloque
    .trim();

const statements = cleanSql.split(';').map(s => s.trim()).filter(Boolean);

Como las sentencias se dividen ingenuamente por ;, un DDL con un punto y coma dentro de un valor por defecto no se analizará correctamente — un caso que en la práctica prácticamente nunca ocurre.

2. Dividir las definiciones de columna por comas fuera de paréntesis

Dividir ingenuamente el cuerpo de un CREATE TABLE por , también rompería en las comas dentro de definiciones de tipo como DECIMAL(10, 2). En su lugar, el analizador rastrea la profundidad de paréntesis y solo trata una coma como separador cuando la profundidad es cero.

private static splitByCommaOutsideParens(text: string): string[] {
    let depth = 0;
    // '(' incrementa depth, ')' lo decrementa; solo las comas en depth === 0 son separadores
    for (let i = 0; i < text.length; i++) {
        if (text[i] === '(') depth++;
        else if (text[i] === ')') depth--;
        if (text[i] === ',' && depth === 0) { /* dividir aquí */ }
    }
}

Es la misma idea que usa el analizador de CSV del conversor JSON⇔CSV — un recorrido carácter a carácter con estado. Las definiciones de columna SQL y los campos CSV entrecomillados se ven distintos en la superficie, pero comparten la propiedad de que “el delimitador deja de ser válido bajo ciertas condiciones”.

3. Clasificar cada línea como PRIMARY KEY, FOREIGN KEY o columna

Cada línea dividida se compara con patrones de expresión regular para clasificarla en una de tres categorías.

// clave primaria a nivel de tabla, incluyendo claves compuestas como PRIMARY KEY (id, tenant_id)
const pkMatch = trimmed.match(/PRIMARY KEY\s*\(([\s\w,`"]+)\)/i);

// clave foránea a nivel de tabla
const fkMatch = trimmed.match(
    /FOREIGN KEY\s*\(([\s\w`"]+)\)\s*REFERENCES\s*(?:['\`"]?(\w+)['\`"]?\.)?['\`"]?(\w+)['\`"]?\s*\(([\s\w`"]+)\)/i
);

// definición de columna; también captura una cláusula REFERENCES en línea
const colMatch = trimmed.match(/^['`"]?(\w+)['`"]?\s+(\w+(?:\([\w\s,]+\))?)(.*)$/i);

El patrón REFERENCES coincide tanto con una clave foránea en línea al final de una definición de columna como con una cláusula FOREIGN KEY a nivel de tabla. Se admiten claves primarias compuestas — una definición como PRIMARY KEY (id, tenant_id) marca ambas columnas como PK.

Salida: notación de pata de gallo

Las líneas de relación que genera la herramienta usan notación de pata de gallo:

orders }|--|| users : "user_id -> id"

La flecha va de }| (muchos) a || (uno) — “muchos pedidos pertenecen a un usuario”, una relación uno a muchos. Para una guía completa de esta notación, incluyendo uno a uno, muchos a muchos y relaciones identificantes frente a no identificantes, consulte la Referencia de sintaxis de diagramas ER en Mermaid.

Tenga en cuenta que la sintaxis erDiagram de Mermaid no permite paréntesis en los tipos de columna, así que los especificadores de longitud se eliminan automáticamente — VARCHAR(255) se convierte en VARCHAR (type.replace(/\([^)]*\)/g, '')).

Patrones de DDL que el analizador no admite

Ser un analizador ligero basado en expresiones regulares en lugar de una gramática SQL completa — una decisión deliberada para mantener el paquete pequeño y rápido en el navegador — tiene límites:

Patrón Soporte
PRIMARY KEY / FOREIGN KEY dentro de CREATE TABLE (a nivel de tabla o de columna) ✅ Compatible
Clave primaria compuesta PRIMARY KEY (a, b) ✅ Compatible
ALTER TABLE ... ADD [CONSTRAINT ...] FOREIGN KEY / ADD PRIMARY KEY (formato de pg_dump) ✅ Compatible
CREATE TABLE IF NOT EXISTS ✅ Compatible
Nombres calificados con esquema schema.table_name ✅ Compatible (solo se extrae la parte del nombre de tabla)
Comentarios de línea -- / de bloque /* */ ✅ Se eliminan antes de analizar

Algunas herramientas de migración y pg_dump añaden claves foráneas mediante una sentencia ALTER TABLE separada (ActiveRecord de Rails es un ejemplo común). Las sentencias ALTER TABLE que añaden claves foráneas o primarias se leen y se reflejan en las relaciones y las claves. Las demás sentencias ALTER TABLE, como añadir o cambiar columnas, no se reflejan.

Lista de verificación para revisar un diagrama generado

  • ¿Tiene cada tabla una clave primaria configurada?
  • ¿Son las direcciones de las claves foráneas las que pretendía?
  • ¿Hay tablas huérfanas sin conexiones?
  • ¿Representan correctamente las tablas intermedias las relaciones muchos a muchos?

En la revisión de pull requests, adjuntar un diagrama ER comunica el alcance de un cambio de esquema mucho mejor que el diff SQL en bruto por sí solo. Como la salida es texto plano (Mermaid), puede pegarla directamente en un comentario de revisión.

Colocar el diagrama a mano

Los diagramas con disposición automática se vuelven difíciles de leer a medida que aumentan las tablas. En SQL a diagrama ER, pega sentencias CREATE TABLE y pulsa «Dibujar diagrama ER»: las tablas y las líneas de clave foránea se colocan automáticamente y se muestran como un diagrama cuyas tablas puedes arrastrar.

  • Las líneas rodean otras tablas en ángulo recto. Salen de la fila de la columna de la clave foránea y entran en la fila de la columna referenciada
  • Los extremos usan la notación de pata de gallo: «muchos» en el lado de la clave foránea, «uno» en el lado referenciado y un círculo en las columnas que admiten NULL
  • Puedes editar en el sitio: corrige nombres de tabla, columnas (nombre, tipo, PK, NOT NULL, UNIQUE) y líneas de relación mirando el diagrama
  • La pestaña «Mermaid» sigue mostrando el código Mermaid y la imagen como antes. Los cambios del diagrama también se reflejan allí
  • Puedes exportar PNG / SVG / JSON y copiar sentencias CREATE TABLE. Guarda como JSON para cargarlo y corregirlo cuando cambie el esquema

Tres consejos de legibilidad: pon los padres (maestras) a la izquierda y los hijos (transacciones) a la derecha; coloca la tabla intermedia de muchos a muchos entre sus dos padres; y con muchas tablas, divide los diagramas por funcionalidad y guarda cada uno como JSON. La salida Mermaid no incluye la información de posición.

Comparar esquemas, revisarlos, datos de ejemplo y salida para SQL Server

Además de dibujar diagramas, el conversor de SQL a diagrama ER puede usar los CREATE TABLE pegados para más cosas:

  • Comparar dos esquemas (SQL de migración): pega el CREATE TABLE antiguo y el nuevo y genera ALTER TABLE a partir de las diferencias en tablas, columnas, tipos, nulabilidad, DEFAULT, claves primarias y foráneas (crear → añadir / cambiar → claves foráneas → eliminar). Admite PostgreSQL, MySQL, SQLite y SQL Server. Eliminar columnas o tablas (se pierden datos) y las sentencias que conviene revisar antes de ejecutar (añadir NOT NULL sin DEFAULT, cambios de tipo, cambios de clave primaria, operaciones que requieren el nombre de una restricción, cambios que SQLite no puede hacer) llevan una marca con su motivo. También avisa de posibles cambios de nombre a partir de un par eliminar + añadir; la migración elimina y vuelve a crear, lo que borra los datos si en realidad era un cambio de nombre
  • Revisión del esquema: señala tablas sin clave primaria, columnas xxx_id sin clave foránea, columnas de clave foránea sin índice, mezcla de snake_case y camelCase, tablas de más de 30 columnas y VARCHAR sin longitud
  • Sugerencias de índices: CREATE INDEX para las columnas de clave foránea, para que borrar una fila padre o hacer un join no recorra toda la tabla
  • Datos de ejemplo: INSERT que respetan las claves foráneas (primero los padres, claves primarias secuenciales, valores acordes con el nombre y el tipo de la columna, reproducibles con una seed, de 1 a 100 filas)
  • Salida para SQL Server: SQL Server está en la lista de dialectos. Los tipos pasan a INT, NVARCHAR, BIT, DATETIME2 y UNIQUEIDENTIFIER, los identificadores usan [corchetes], el autoincremento pasa a IDENTITY(1,1) y RESTRICT pasa a NO ACTION, porque SQL Server no lo tiene

Todo esto solo lee las definiciones SQL. Nunca se conecta a una base de datos ni ve tus datos. Lee siempre el resultado antes de ejecutarlo.

Preguntas frecuentes

¿Funciona con DDL de MySQL o PostgreSQL?

Sí, para DDL general centrado en CREATE TABLE. Los tipos y opciones específicos del dialecto (como ENGINE=InnoDB) simplemente se ignoran — no afectan la extracción de tablas, columnas ni claves.

¿Genera un diagrama aunque no haya claves foráneas?

Sí — obtendrá una lista de tablas y columnas. Pero las líneas de relación se derivan enteramente de las cláusulas FOREIGN KEY / REFERENCES, así que inclúyalas en su DDL si quiere que aparezcan relaciones.

¿Se detectan las claves foráneas añadidas mediante ALTER TABLE?

Sí. ALTER TABLE ... ADD FOREIGN KEY y ADD PRIMARY KEY (también con ADD CONSTRAINT nombre) se leen y se reflejan en las relaciones y las claves primarias. Las demás sentencias ALTER TABLE, como añadir o cambiar columnas, no se reflejan.

¿Puedo pegar el diagrama generado en documentación?

Sí. La salida de Mermaid se renderiza de forma nativa en READMEs de GitHub y en la mayoría de los visores de Markdown, así que puede gestionar su diagrama de esquema junto con su código. Consulte la Referencia de sintaxis de diagramas ER en Mermaid para saber cómo leer (y editar a mano) la notación de pata de gallo.

¿Puedo mover las tablas yo mismo?

Sí. Arrastra las tablas en la pestaña «Diagrama (editable)». Las flechas permiten ajustar, y se admite deshacer/rehacer. «Ordenar automáticamente» vuelve a la disposición inicial.

¿Puede generar ALTER TABLE a partir de la diferencia entre dos esquemas?

Sí, pero solo compara definiciones, así que no puede juzgar qué pasa con tus datos. Eliminar una columna o una tabla se marca como «se pierden datos», y añadir NOT NULL sin DEFAULT o cambiar un tipo se marca como «revisar antes de ejecutar». Una columna que solo cambió de nombre aparece como eliminar + añadir, por lo que avisa de los pares que pueden ser cambios de nombre. Lee siempre las sentencias antes de ejecutarlas.

Exportar también como DBML y PlantUML

Debajo del editor ER, junto a «Copiar DDL», hay botones «Copiar DBML» y «Copiar PlantUML». El DBML se puede pegar directamente en dbdiagram.io y el PlantUML en un editor de PlantUML o en una herramienta de documentación.

Table orders {
  id INT [pk]
  customer_id INT [not null]
}

Ref: orders.customer_id > customers.id [delete: cascade]
  • DBML: los ajustes de columna son pk, increment, not null, unique y default, y las relaciones son Ref: hija.columna > padre.columna (- para uno a uno). Una clave primaria compuesta va en un bloque indexes en lugar de un pk en cada columna.
  • PlantUML: las tablas se dibujan con entity y las claves primarias llevan * y <<PK>> sobre la línea de separación. Las relaciones son padre ||--o{ hija (|o--o{ cuando la clave foránea admite NULL).
  • El ON DELETE / ON UPDATE de una clave foránea se lee del DDL y pasa a la exportación de DDL y al [delete: …, update: …] de DBML.

Resumen

  • El análisis es una implementación ligera basada en expresiones regulares; el truco clave es dividir las comas solo fuera de los paréntesis
  • Admite PRIMARY KEY y FOREIGN KEY tanto a nivel de tabla como de columna, incluyendo claves primarias compuestas
  • Las claves foráneas y primarias añadidas después mediante ALTER TABLE son compatibles; las demás sentencias ALTER TABLE (añadir o cambiar columnas) no se reflejan
  • La salida usa la notación de pata de gallo de Mermaid; consulte el artículo de referencia complementario para saber cómo leerla

Entregue su SQL a la herramienta y vea relaciones que quizá se le habían pasado por alto.