Tools mentioned in this article
Open the browser-based tool while you read and try the workflow immediately.
“Where is this table connected again?”
“Which table does this user_id reference?” “Wait, is this table actually referenced from anywhere?” — tracing relationships by reading raw SQL is like assembling a puzzle in your head.
The SQL to ER Diagram Converter takes CREATE TABLE statements and instantly renders tables, columns, primary keys, and foreign keys as a Mermaid ER diagram. Everything runs in your browser — your SQL never leaves it.

This article explains how the DDL parser actually works under the hood, and — because of how it works — what you should know about its coverage.
Usage
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)
);
Paste that in, and you get this Mermaid erDiagram code:
erDiagram
users {
BIGINT id PK
VARCHAR name
}
orders {
BIGINT id PK
BIGINT user_id
INTEGER total_amount
}
orders }|--|| users : "user_id -> id"
Paste the generated code straight into a GitHub README or pull request and it renders automatically.
How the parser works: regex-based DDL decomposition
Rather than a full SQL parsing library, the tool uses a lightweight regex-based parser (SqlParser.parseDdl). It works in three stages.
1. Strip comments and split into statements
const cleanSql = sql
.replace(/--.*$/gm, '') // strip line comments
.replace(/\/\*[\s\S]*?\*\//g, '') // strip block comments
.trim();
const statements = cleanSql.split(';').map(s => s.trim()).filter(Boolean);
Because statements are split naively on ;, DDL containing a semicolon inside a default value won’t parse correctly — a case that essentially never comes up in practice.
2. Split column definitions on commas outside parentheses
Naively splitting a CREATE TABLE body on , would also break on commas inside type definitions like DECIMAL(10, 2). Instead, the parser tracks parenthesis depth and only treats a comma as a separator when depth is zero.
private static splitByCommaOutsideParens(text: string): string[] {
let depth = 0;
// '(' increments depth, ')' decrements it; only commas at depth === 0 are separators
for (let i = 0; i < text.length; i++) {
if (text[i] === '(') depth++;
else if (text[i] === ')') depth--;
if (text[i] === ',' && depth === 0) { /* split here */ }
}
}
This is the same idea used in the JSON⇔CSV converter’s CSV parser — a stateful character-by-character scan. SQL column definitions and quoted CSV fields look different on the surface, but share the property that “the delimiter becomes invalid under certain conditions.”
3. Classify each line as PRIMARY KEY, FOREIGN KEY, or a column
Each split line is pattern-matched into one of three categories.
// table-level primary key, including composite keys like PRIMARY KEY (id, tenant_id)
const pkMatch = trimmed.match(/PRIMARY KEY\s*\(([\s\w,`"]+)\)/i);
// table-level foreign key
const fkMatch = trimmed.match(
/FOREIGN KEY\s*\(([\s\w`"]+)\)\s*REFERENCES\s*(?:['\`"]?(\w+)['\`"]?\.)?['\`"]?(\w+)['\`"]?\s*\(([\s\w`"]+)\)/i
);
// column definition; also picks up an inline REFERENCES clause
const colMatch = trimmed.match(/^['`"]?(\w+)['`"]?\s+(\w+(?:\([\w\s,]+\))?)(.*)$/i);
The REFERENCES pattern matches both an inline foreign key at the end of a column definition and a table-level FOREIGN KEY clause. Composite primary keys are supported — a definition like PRIMARY KEY (id, tenant_id) marks both columns as PK.
Output: crow’s-foot notation
The relationship lines the tool generates use crow’s-foot notation:
orders }|--|| users : "user_id -> id"
The arrow goes from }| (many) to || (one) — “many orders belong to one user,” a one-to-many relationship. For a full guide to reading this notation, including one-to-one, many-to-many, and identifying vs. non-identifying relationships, see Mermaid ER Diagram Syntax Reference.
Note that Mermaid’s erDiagram syntax doesn’t allow parentheses in column types, so length specifiers are stripped automatically — VARCHAR(255) becomes VARCHAR (type.replace(/\([^)]*\)/g, '')).
DDL patterns the parser doesn’t support
Being a lightweight regex-based parser rather than a full SQL grammar — a deliberate trade-off to keep the bundle small and run fast in the browser — comes with limits:
| Pattern | Support |
|---|---|
PRIMARY KEY / FOREIGN KEY inside CREATE TABLE (table- or column-level) |
✅ Supported |
Composite primary key PRIMARY KEY (a, b) |
✅ Supported |
ALTER TABLE ... ADD [CONSTRAINT ...] FOREIGN KEY / ADD PRIMARY KEY (pg_dump style) |
✅ Supported |
CREATE TABLE IF NOT EXISTS |
✅ Supported |
Schema-qualified names schema.table_name |
✅ Supported (only the table name portion is extracted) |
-- line comments / /* */ block comments |
✅ Stripped before parsing |
Some migration tools and pg_dump add foreign keys via a separate ALTER TABLE statement (Rails’ ActiveRecord is a common example). ALTER TABLE statements that add foreign keys or primary keys are read and reflected in the relationships and keys. Other ALTER TABLE statements, such as adding or changing columns, are not reflected.
Checklist for reviewing a generated diagram
- Does every table have a primary key set?
- Are the foreign key directions what you intended?
- Are there any orphaned tables with no connections?
- Do junction tables correctly represent many-to-many relationships?
In pull request review, attaching an ER diagram communicates the blast radius of a schema change far better than the raw SQL diff alone. Since the output is plain text (Mermaid), you can paste it directly into a review comment.
Arranging the diagram by hand
Auto-laid-out diagrams get hard to read as tables multiply. In SQL to ER Diagram, paste CREATE TABLE statements and press “Draw ER diagram”: tables and foreign-key lines are laid out automatically and shown as a diagram whose tables you can drag.
- Lines route around other tables at right angles. They leave from the foreign key column’s row and enter at the referenced column’s row
- The line ends use crow’s foot notation: “many” on the foreign key side, “one” on the referenced side, and a circle on nullable columns
- You can edit in place: fix table names, columns (name, type, PK, NOT NULL, UNIQUE) and relation lines while looking at the diagram
- The “Mermaid” tab still shows the Mermaid code and image as before. Edits to the diagram are reflected there too
- You can export PNG / SVG / JSON and copy CREATE TABLE statements. Save as JSON to load and fix it when the schema changes
Three tips for readability: put parents (masters) on the left and children (transactions) on the right; put a many-to-many junction table between its two parents; and with many tables, split diagrams by feature and save each as JSON. Note that Mermaid output does not include position information.
Schema comparison, review, sample data and SQL Server output
Besides drawing diagrams, the SQL to ER Diagram Converter can use the pasted CREATE TABLE statements for more:
- Compare two schemas (migration SQL): paste the old and the new
CREATE TABLEstatements and it buildsALTER TABLEstatements from the differences in tables, columns, types, nullability,DEFAULT, primary keys and foreign keys (create → add / change → foreign keys → drop). It supports PostgreSQL, MySQL, SQLite and SQL Server. Dropping columns or tables (data is lost) and statements to check before running (addingNOT NULLwithout aDEFAULT, type changes, primary key changes, operations that need a constraint name, changes SQLite cannot do) are marked with a reason. It also warns about possible renames found from a drop + add pair; the migration drops and re-adds, which deletes the data if it was really a rename - Schema review: flags tables without a primary key,
xxx_idcolumns without a foreign key, foreign key columns without an index, mixedsnake_case/camelCase, tables over 30 columns, andVARCHARwithout a length - Index suggestions:
CREATE INDEXstatements for foreign key columns, so deleting a parent row or joining does not scan the whole table - Sample data:
INSERTstatements that respect foreign keys (parents first, sequential primary keys, values that fit the column name and type, reproducible with a seed, 1–100 rows) - SQL Server output: SQL Server is in the dialect list. Types become
INT,NVARCHAR,BIT,DATETIME2andUNIQUEIDENTIFIER, identifiers use[brackets], auto-increment becomesIDENTITY(1,1), andRESTRICTbecomesNO ACTIONbecause SQL Server has none
All of this only reads the SQL definitions. It never connects to a database and never sees your data. Always read the result before running it.
FAQ
Does it work with MySQL or PostgreSQL DDL?
Yes, for general CREATE TABLE-centric DDL. Dialect-specific types and options (like ENGINE=InnoDB) are simply ignored — they don’t affect table, column, or key extraction.
Does it still generate a diagram if there are no foreign keys?
Yes — you’ll get a table/column overview. But relationship lines are derived entirely from FOREIGN KEY / REFERENCES clauses, so include them in your DDL if you want relationships to appear.
Are foreign keys added via ALTER TABLE picked up?
Yes. ALTER TABLE ... ADD FOREIGN KEY and ADD PRIMARY KEY (also with ADD CONSTRAINT name) are read and reflected in the relationships and primary keys. Other ALTER TABLE statements, such as adding or changing columns, are not reflected.
Can I paste the generated diagram into documentation?
Yes. The Mermaid output renders natively in GitHub READMEs and most Markdown viewers, so you can manage your schema diagram alongside your code. See the Mermaid ER Diagram Syntax Reference for how to read (and hand-edit) the crow’s-foot notation.
Can I move the tables myself?
Yes. Drag tables in the “Diagram (editable)” tab. Arrow keys nudge them, and undo/redo is supported. “Auto-arrange” returns to the initial layout.
Can it generate ALTER TABLE from the difference between two schemas?
Yes, but it only compares definitions, so it cannot judge what happens to your data. Dropping a column or table is marked “data is lost”, and adding NOT NULL without a DEFAULT or changing a type is marked “check before running”. A column that was only renamed shows up as a drop plus an add, so it warns about pairs that may be renames. Always read the statements before running them.
Exporting as DBML and PlantUML
Below the ER editor, next to “Copy DDL”, there are “Copy DBML” and “Copy PlantUML” buttons. DBML can be pasted straight into dbdiagram.io, and PlantUML into a PlantUML editor or documentation tool.
Table orders {
id INT [pk]
customer_id INT [not null]
}
Ref: orders.customer_id > customers.id [delete: cascade]
- DBML: column settings are
pk,increment,not null,uniqueanddefault, and relationships areRef: child.column > parent.column(-for one-to-one). A composite primary key goes in anindexesblock instead of apkon each column. - PlantUML: tables are drawn with
entity, and primary keys carry*and<<PK>>above the divider line. Relationships areparent ||--o{ child(|o--o{when the foreign key allows NULL). - A foreign key’s
ON DELETE/ON UPDATEis read from the DDL and carried into the DDL export and DBML’s[delete: …, update: …].
Summary
- Parsing is a lightweight regex implementation; the key trick is splitting commas only outside parentheses
- Supports PRIMARY KEY and FOREIGN KEY at both table and column level, including composite primary keys
- Foreign keys and primary keys added later via
ALTER TABLEare supported; otherALTER TABLEstatements (adding or changing columns) are not reflected - Output uses Mermaid’s crow’s-foot notation; see the companion reference article for how to read it
Hand your SQL to the tool and see relationships you might have missed.
