I used to groan when someone asked for an ERD. I diagrammed the same schema five ways, and now I won't anymore.
For most of my career, the words "can you send me an ER diagram of this?" made something in me deflate.
Not because diagrams aren't useful. They're super useful. I'm a very visual person, and when somebody is explaining a business process to me, an ERD often helps me wrap my head around it.
But the making of them was the problem. You either drew the thing by hand and it was out of date by Friday, or you fired up a heavyweight modeling tool, pointed it at the database, and spent the next hour dragging forty tables out of a pile where they'd all landed on top of each other.
Reverse-engineering a model into a readable picture, one you'd actually put in front of a client, was real work. So I groaned. (Quietly. Professionally. But I groaned.)
But that's changed now, and it changed more in the last year than in the previous ten.
I've been working on a few presentations lately, one of which means I've got a real schema sitting in front of me: eight tables, customers and orders and a conversation log and an audit trail, all wired together. Nothing crazy, totally manageable. I do want to share the data model, so this felt like the perfect excuse to try every way I know of to turn DDL into a diagram and see which ones are actually worth your time.
So I did. Here's what I found.
Before we start, I know some of you are drawing these in PowerPoint right now. A rectangle. Another rectangle. A connector line that detaches the instant you nudge anything. I see you, because I've been you. It's the diagramming equivalent of doing your taxes on paper: it works, it builds character, but friends... there is absolutely a better way. Five of them, actually.
The schema I'm working with
Quick context so the examples make sense. It's a returns copilot: a customer texts WhatsApp, an AI classifies what they want, n8n orchestrates, and Oracle APEX owns the data and the decisions. The data model is seven load-bearing tables — CUSTOMER, SALES_ORDER, SALES_ORDER_ITEM, RETURN_CASE, CONVERSATION, CONVERSATION_MESSAGE, and WORKFLOW_EVENT — plus a supporting address table I leave off the diagram because nobody needs it to understand the story.
That's my test subject. Now let's diagram it five ways.
Method 1 — Mermaid (the diagram is just text)
Mermaid is a little markup language. You describe entities and relationships in plain text, and it draws the picture. Here's the shape of it:
erDiagram
direction TB
CUSTOMER {
number customer_id PK ""
varchar customer_number UK ""
varchar first_name ""
varchar last_name ""
varchar email ""
varchar mobile_phone UK "E.164 - the WhatsApp key"
varchar status ""
}
SALES_ORDER {
number order_id PK ""
varchar order_number UK ""
number customer_id FK ""
date order_date ""
date delivery_date ""
varchar order_status ""
number order_total ""
}
RETURN_CASE {
number return_case_id PK ""
varchar rma_number UK "trigger-generated RMA-NNNNN"
number customer_id FK ""
number order_id FK "optional"
number conversation_id "soft link - no constraint"
varchar case_status ""
varchar reason_code ""
varchar requested_resolution ""
varchar final_resolution ""
varchar approval_required_flag ""
varchar approval_status ""
varchar idempotency_key UK ""
}
CONVERSATION {
number conversation_id PK ""
number customer_id FK "nullable until identified"
varchar customer_phone "denormalized for lookup"
varchar current_state "state machine"
number open_return_case_id FK ""
timestamp last_message_at ""
}
SALES_ORDER_ITEM {
number order_item_id PK ""
number order_id FK ""
varchar sku ""
varchar product_name ""
number qty ""
number unit_price ""
varchar returnable_flag "eligibility rule lives here"
number return_window_days ""
varchar delivered_flag ""
}
CONVERSATION_MESSAGE {
number message_id PK ""
number conversation_id FK ""
varchar direction "INBOUND / OUTBOUND"
varchar provider_message_id UK "Twilio MessageSid"
clob message_text ""
varchar media_flag ""
}
WORKFLOW_EVENT {
number workflow_event_id PK ""
varchar correlation_id "MessageSid / n8n exec id"
varchar related_entity_type "polymorphic"
number related_entity_id ""
varchar event_type ""
varchar event_source ""
varchar outcome_status "SUCCESS / FAILURE / PARTIAL / PENDING"
}
CUSTOMER||--o{SALES_ORDER:"places"
CUSTOMER||--o{RETURN_CASE:"files"
CUSTOMER|o--o{CONVERSATION:"starts (phone before identity)"
SALES_ORDER||--o{SALES_ORDER_ITEM:"contains"
SALES_ORDER|o--o{RETURN_CASE:"subject of (optional)"
CONVERSATION||--o{CONVERSATION_MESSAGE:"logs"
CONVERSATION|o--o|RETURN_CASE:"open case (soft link)"
You paste that into mermaid.live, or drop it straight into a GitHub README, a Notion page, or your docs (all of which render Mermaid natively) and there's your diagram.
Here are my results:
What I loved. It's text, which means it lives in version control next to the code. When the schema changes, you change two lines, not a whole canvas. It's free, there's nothing to install, and it renders in the tools my notes already live in. For documentation that has to stay current, this is the one.
The LLMs know the Mermaid format well. I had no errors or issues when I asked Claude Code to generate the Mermaid diagram from the DDL scripts.
Where it might bite you. You don't control the layout. Mermaid auto-arranges, and "auto" is not always "sensibly." My tables landed in an order that had nothing to do with the story the data tells. And it's a little weak on the fine print: it can't draw a dashed line for a soft foreign key, and it won't pinpoint exactly which column is the key the way a dedicated tool does. The crow's-feet are there; the nuance isn't.
Verdict: Best for living documentation. Worst for the slide you're presenting to a room, especially if your ERD has more than 7 tables, which, let's be honest, it probably does.
Method 2 — Describe it to an AI, then have AI render it
I've been having a lot of fun with Claude Design, so I was curious how it would handle this task.
Instead of asking a tool to mechanically draw my tables, I asked Claude to first write a spec, a careful description of the model: which tables, which columns matter, which keys, which relationships, how they should be grouped to tell a story, even which brand colors to use. Then I handed that spec to Claude Design tooling and asked it to render an actual, annotated image. Not a stock ERD: a designed one, with my palette, with little notes pointing at the interesting bits ("eligibility rule lives here"), with the tables grouped left-to-right to match the journey a message takes.
Here are my results:
What I loved. It's the only method on this list that produces something I'd put on a conference slide without further editing. The layout follows the narrative, not the alphabet. The annotations explain things a raw diagram can't. It's bespoke. For a presentation, a pitch, or a teaching moment, nothing else comes close.
Where it might bite you. It is not driven by the live database. The AI is rendering from a description, which means it can drift. A column named slightly wrong, a relationship inferred a touch generously. You have to check it against the real DDL, every time. It won't auto-update when your schema does. And it's a two-step dance (spec, then render) rather than one click. Let's call this one a communication tool, not a source-of-truth tool.
Verdict: Best for the diagram a human has to be persuaded by. Verify it against the schema before you trust it
Method 3 — Paste your SQL into an AI generator
There's a middle ground between "write it yourself" and "design it from scratch": Eraser's DiagramGPT lets you paste your raw CREATE TABLE statements and the AI infers the whole ERD — tables, columns, types, and the relationships hiding in your foreign keys. (ChartDB, in the next section, has a similar AI assistant, but it's a paid-tier add-on — its free path is the deterministic one-query import I'll get to in a second.)
What I loved. Speed. Paste the DDL, get a diagram in seconds, no syntax to learn. The AI reads SQL well, so the foreign-key relationships mostly come out right without you spelling them out. A genuinely lovely "I just need this now" option.
Where it might bite you. "Mostly right" is the catch. AI inference can misread an ambiguous schema, and you get less control over the final look than the design route gives you. The free tier is also capped. Eraser gives you a handful of files and AI generations, enough to try it, not enough to live in. And it's an online paste-your-schema step, which, if your DDL is sensitive, is a conversation to have with yourself first.
Verdict: Best for a fast first draft from real SQL. Trust, but verify the relationships.
Here are my results:
Method 4 — A free web tool that imports your schema
If you want a real diagram you can edit, the modern open-source web tools are excellent. ChartDB imports your whole schema from a single SQL query — Oracle included — auto-lays-out an editable ERD, and exports clean DDL, DBML, or an image. It's AGPL-3.0, so you self-host it or use the cloud version, and the core is genuinely free (the AI assistant is the bit that lives on the paid tiers). DrawDB is a fully free, no-account browser canvas: paste your CREATE TABLE script into Import → SQL and it reverse-engineers the tables and relationships, then you drag things into shape and export SQL, JSON, or an image.
What I loved. You get the auto-generation and the ability to nudge things by hand afterward. Export options are generous. No desktop install, no licence. For an editable, shareable diagram that stays close to the schema, this hits a sweet spot the other methods miss.
Where it bit me. It's another tool to keep track of, and the hand-tuned layout doesn't live in version control the way Mermaid does — so it can quietly go stale. Cross-database support is good but Oracle-specific quirks occasionally need a nudge.
Verdict: Best when you want auto-generated and editable, without paying for anything.
Method 5 — The Oracle-native route: reverse-engineer from the data dictionary
I'd be a fraud if I wrote this whole thing and skipped the tool a lot of us already have And this time I didn't just read about it, I ran it.
Oracle's reverse engineering reads the actual data dictionary: point it at your schema, pick your tables, and it builds a relational ERD straight from the database: keys, constraints, real relationships, zero inference. For years that meant the free desktop SQL Developer Data Modeler (File > Import > Data Dictionary). But Oracle has named the SQL Developer extension for VS Code as the future. The desktop tools are now bug-fix-only and will be deprecated once VS Code reaches parity, so that's where I went.
The VS Code extension picked up Schema Diagrams in its 25.3 release, and honestly? It did a really nice job.
Clean Oracle notation, primary / unique / foreign keys all marked, relationships drawn straight from my foreign keys. WORKFLOW_EVENT sits off on its own with no connectors, because it's polymorphic and has no real FK. The diagram told the truth about my schema without me typing a single word of it.
What I loved. It reads the actual data dictionary, so the relationships are real, not inferred, no AI guessing, no hand-typing. For a true, complete, accurate model of a real Oracle schema, nothing else on this list is as trustworthy. The output is clean and presentable. And it's free.
Where it might bite you. It is not one-click. I had to point and click each table, drag it onto the canvas, and then rearrange everything by hand until it fit. That's real effort the auto-import tools (ChartDB, DrawDB) simply don't ask of you. Something to note: if the data model changes, the picture doesn't update itself, and as best I can tell, you have to drop the entity off the diagram and bring it back in to pick up the change. Set that against the text tools, where you tweak a couple of lines and re-render, and for a schema that's still moving, this might be a heavier lift.
Verdict: Best for an accurate, schema-true model native to Oracle, and the VS Code version finally makes it look good too. The cost isn't ugliness anymore; it's the manual assembly, and a diagram that won't follow your schema when it changes.
The honest comparison
| Method | Ease of use | Driven by live schema? | Looks presentable? | Stays current? | Best for |
|---|---|---|---|---|---|
| Mermaid | Easy (learn a little syntax) | No (you write it) | OK | Yes — it's text in git | Living documentation |
| AI spec → rendered image | Medium (two steps) | No | Beautiful | No | Slides, teaching, persuasion |
| Paste SQL into AI | Very easy | Sort of (reads your DDL) | Decent | No | A fast first draft |
| Web import tool (ChartDB/DrawDB) | Easy | Yes (import or connect) | Good, editable | Manually | Editable, shareable diagrams |
| Oracle SQL Developer (VS Code) | Medium — manual assembly | Yes (data dictionary) | Clean (manual layout) | No — re-add tables to refresh | Accurate, schema-true Oracle models |
A few other paths worth a mention if none of these fit: dbdiagram.io (with its DBML language is a nicer text-as-code option than Mermaid for keys), SchemaSpy (generates browsable HTML docs with diagrams from schema metadata), DBeaver (ER diagrams as a side effect of a database client you might already use), and Azimutt (built for exploring genuinely huge, messy schemas).
So which do I actually reach for?
Before the tool-by-tool answer, here's a different question maybe: are you designing a model or documenting one?
When the model doesn't exist yet, and you're still arguing with yourself about whether the return hangs off the order or the order line, you want the diagram to be the source of truth: something you change in seconds and re-render. That's Mermaid (or DBML/dbdiagram.io, which handle keys better and can forward-generate the DDL once you're happy). Type, see, adjust, repeat. No database required, because the diagram is the model.
When the model already exists and you need the truth about it, the diagram is a reflection of a source that lives elsewhere (the data dictionary). That's the Oracle VS Code reverse-engineer route. You can't design in it; it only shows you what's already there. Which is exactly what you want when you're documenting a legacy schema you don't trust yet, and useless when you're still inventing one.
After that, it depends on who the diagram is for.
If it's for the codebase (docs that have to stay true as the schema moves) Mermaid. It's text, it's free, it lives where the code lives.
If it's for a human I need to persuade (a slide, a client, a teaching moment), the AI-spec-to-rendered-image route. It's the only one that produces something genuinely designed. I just never let myself forget to check it against the real DDL first.
If I need the truth about a big legacy Oracle schema I don't fully understand yet: back to the data dictionary, these days via the SQL Developer VS Code extension. Accurate beats pretty when you're still figuring out what's actually in there (and it happens to be pretty now too!)
How are you generating your ERDs these days? Still dragging boxes around a desktop app, or have you found a flow that doesn't make you groan?
