Convert SQL to an ER diagram without hiding schema assumptions
Turn SQL table definitions into a Mermaid ER diagram, then verify foreign keys, nullability, and omitted statements before using it in documentation.
To convert SQL into a useful ER diagram, import table definitions, inspect the relationships, and compare the result with the source. Automatic conversion saves transcription time. The review is what makes the picture dependable.
Use a schema-only file when possible. A data dump adds noise and can include personal or confidential records that are unnecessary for understanding table structure.
Start with explicit constraints
This small schema describes customers and orders:
CREATE TABLE customers (
id INTEGER PRIMARY KEY,
email TEXT NOT NULL UNIQUE
);
CREATE TABLE orders (
id INTEGER PRIMARY KEY,
customer_id INTEGER NOT NULL REFERENCES customers(id),
status TEXT NOT NULL
);
The important relationship is declared through REFERENCES, not inferred from the column name. A field named customer_id without a constraint might be a relationship, but a converter should not silently treat the naming convention as proof.
For this simplified model, the relationship can be explained as:
erDiagram
CUSTOMERS ||--o{ ORDERS : places
CUSTOMERS {
int id PK
string email UK
}
ORDERS {
int id PK
int customer_id FK
string status
}This is an illustrative rendering: an importer may name entities and label relationships differently (Flowgraph Studio, for example, keeps table names as written and replaces characters Mermaid can't use with underscores). Read the resulting code before making it the team's reference.
Import and inspect in Flowgraph Studio
Open Flowgraph Studio, choose New diagram → Start from → From a SQL schema, and paste the DDL or drop a .sql file. The schema is read in your browser and nothing is uploaded. PostgreSQL works best, including pg_dump --schema-only output; common MySQL table syntax mostly works too.
The importer reads CREATE TABLE (columns, NOT NULL, primary keys, UNIQUE, REFERENCES, and table constraints), keys and foreign keys added later with ALTER TABLE … ADD, ALTER COLUMN … SET NOT NULL, and unique indexes on plain columns. Every other statement is skipped and listed with its line number, so one unfamiliar statement doesn't spoil the rest.
Read those reports. A schema containing functions, permission statements, vendor-specific constructs, or generated tables may not map completely to the diagram. SQL import is a documentation conversion, not execution of the SQL and not validation of an entire database dump.
Compare the number of expected tables with the rendered entities. Then inspect one relationship at a time: referenced table, referenced column, foreign-key field, and whether nullability permits the relationship to be absent. Composite keys deserve particular attention because several columns may define one relationship.
Add the information DDL cannot explain
The source may tell you that customer_id is required. It probably does not tell you why anonymous purchases are prohibited or whether a deleted customer is anonymized instead of removed.
Add a short accompanying note with those rules. Keep implementation facts separate from intended future changes. If the diagram represents a proposed migration, label it as a proposal rather than current production state.
Save a reproducible result
Keep the relevant schema or migration reference beside the exported Mermaid source. Include a review date and an owner. Regenerate after changes to tables, keys, or nullability; do not update only the picture while leaving the source behind.
Use the official Mermaid ER reference to check notation, and the Flowgraph documentation for editing and export options. The final deliverable should let a colleague trace a line in the diagram back to a real constraint or an explicitly documented assumption.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.