DEV Community: Son Tran

You Cannot Tell Which of Your ERD Files Are Under Version Control

Son Tran — Tue, 04 Aug 2026 17:55:53 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: A diagram stored as a file is only version controlled if its folder happens to sit inside a Git repository, and nothing in the tool tells you whether it does - so the safest-feeling diagrams are often the untracked ones. Schemity now shows a Git branch icon beside every workspace that lives inside a repository, detected by walking up the directory tree so a workspace nested deep inside a project counts too, and marks imported workspaces with their own icon so the ones you deliberately placed inside a repo are distinguishable from the ones the app created for you.

A diagram is not under version control because you meant it to be. It is under version control if, and only if, the folder holding it sits inside a Git repository - and until now nothing in Schemity told you which of your workspaces did. Now every workspace that lives inside a repo carries a Git branch icon in the workspace list.

That sounds like a small thing. It is small the way a fuel gauge is small.

The assumption you never actually check

Storing diagrams as plain files is the whole argument for a Git-native ERD tool: text on disk, diffed in pull requests, restored from history. The ERD belongs in your Git repo rather than as a PNG rotting in a wiki. But that argument quietly depends on a fact nobody verifies: that this particular diagram, the one open right now, is inside a repository.

Six months in, that is genuinely hard to know. You created a workspace for the client project and put it in their repo. You created another for a spike and let it default to ~/schemity. You imported a third from a folder you no longer remember choosing. Every one of them looks identical in the list. They open the same, save the same, and produce the same JSON. The only difference is that three of them are recoverable and one is a file on a laptop.

This is not a niche confusion, and the proof is that developers have industrialized it. An entire category of command line tools exists purely to answer "which of my folders are Git repositories, and what state are they in" - gita, at 1.9k GitHub stars, exists to "manage many git repos with sanity" by printing their status side by side, and mgitstatus scans a whole directory tree looking for .git dirs "up to DEPTH directories deep" to report uncommitted, untracked and unpushed changes. Nobody writes and maintains a tool for a problem they do not have. Developers lose track of which folders are tracked, routinely enough to build instruments for it.

The failure mode is specific and quiet. Nothing breaks. No error appears. The diagram saves perfectly every time. You find out the day you need the version from before the refactor, and there is no history to go back to.

How do I know which of my database diagrams are under version control?

Look at the workspace list. Any workspace whose folder resolves to somewhere inside a Git repository shows a branch icon beside its name.

Five workspaces, four different situations, readable in one glance. demo, default and work sit inside repositories. erd was imported from elsewhere on the machine but is not in one, so it is a single copy on this laptop. suberd was imported and is inside a repository, which is the arrangement you want for a diagram that belongs to a project.

There is no configuration and no connection step. Schemity checks the workspace folder's location on disk and reports what it finds. A workspace under version control looks different from one that is not, at the moment you are choosing which to open, which is the only moment the information is useful. The check is about the folder, not about your commits - the icon tells you the diagram can be tracked, not that you have remembered to commit it.

This closes a real gap in the version control workflow. The JSON storage format made diagrams diffable, and creating a workspace put them in a folder you control. What was missing was any way to confirm the arrangement had actually happened for a given workspace, rather than being something you intended in March.

What the two workspace icons mean

Workspaces now carry up to two independent markers, and reading them together tells you where a diagram lives and whether it is safe:

Icons shown	What it means	Recoverable from history?
None	Created by Schemity in the default `~/schemity` folder, not inside any repository	No
Git branch	The folder sits inside a Git repository	Yes
Imported	Stored somewhere else on your machine, outside `~/schemity`	Not by itself
Imported + Git branch	Deliberately placed inside a project's own repository	Yes

The last row is the one worth aiming for. It is the arrangement where the ERD travels with the code it describes: same repo, same branch, same pull request, same history. A schema change and the diagram change land in one commit, and a reviewer sees both.

The first row is the one worth auditing. A workspace with no icons is not wrong - a scratch diagram belongs nowhere near a repo - but it should be a choice rather than a discovery.

Why detection has to walk up the directory tree

The obvious implementation checks whether the workspace folder is a repository root. That would be wrong most of the time, because almost nobody puts an ERD at the top level of a project.

A diagram lives in docs/schema/, or db/erd/, or design/. It sits several levels down inside a repository whose root is somewhere above it. So Schemity walks up the directory tree from the workspace folder and reports a match wherever it finds the repository, however deep the workspace is nested. A workspace at ~/work/acme-api/docs/database/ is correctly marked as tracked because ~/work/acme-api/ is the repo.

This matters more than it sounds, because the root-only version of this feature would mislabel exactly the workspaces that are set up correctly. The engineer who did the right thing - filed the diagram in a sensible subdirectory of the project - would see no icon, and the feature would be worse than not having it. A signal that is wrong in the well-organized case teaches you to ignore the signal.

The point is the audit, not the icon

Open the workspace list and read it once. Every workspace with a branch icon is one you can recover, review, and blame. Every workspace without one is a single copy of a design that can simply disappear, and you now know which ones those are rather than assuming the answer.

For the ones that should be tracked and are not, the fix is the same as it has always been: keep the workspace inside a Git repository by moving its folder into the repo where it belongs, or import a fresh workspace from a folder inside the project. What changes is that you can now tell there is something to fix.

That is the whole feature. An ERD tool built for software engineers should not ask you to take version control on faith, any more than your editor asks you to guess which branch you are on.

Why Schemity Has No Zoom: Fuzzy Search and a Minimap Instead

Son Tran — Tue, 04 Aug 2026 17:54:57 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Zoom looks free but is not: each zoom changes the diagram's geography so you have to rebuild your sense of where things are, it fights the mouse wheel you need for scrolling, and it leaves you managing a zoom percentage you now have to reset. Schemity has no zoom control at all. The jobs zoom was doing - finding a distant entity, spotting tables a migration added outside the app, seeing where imported entities landed, and getting a first overview of a reverse-engineered schema - are handled by realtime fuzzy search and a minimap that shows where things are without pretending to be a smaller copy of the diagram.

Schemity has no zoom control, and that is a decision rather than an omission. Zoom is one of those features that looks free because every canvas app ships it, but it charges the designer on every single use, and once the jobs it was doing are handled properly there is nothing left for it to pay for.

The question we asked was not "should we add zoom?" It was: what problems does zoom solve, and what problems does it introduce?

What zoom actually costs

It resets your spatial memory. A large ERD is something you navigate by remembering where things are. Orders live down and to the right, identity is up near the top left, the audit tables hang off the bottom. That memory is the thing that makes a big diagram workable at all. Every zoom changes the geography: distances between entities change, what is on screen changes, the shape you had memorized is replaced by a different one. You then spend a few seconds re-establishing where you are. Individually trivial, and paid every single time.

It fights the input it needs. The default binding for zoom on a canvas is the mouse wheel, and the mouse wheel is what you want for scrolling. So a tool either takes the wheel away from scrolling, or it puts zoom behind a modifier - space, control, command plus wheel. Panning around a schema is a constant, high-frequency action. Putting a modifier on either half of that pair taxes something you do hundreds of times an hour.

It creates state you have to manage. Once zoom exists, the diagram has a zoom percentage, and the percentage becomes something you track. Am I at 80% or 60%? Why does this entity look smaller than it did yesterday? How do I get back to 100%? That is a new category of question that had nothing to do with designing a database.

None of this is peculiar to ERDs. It is a known cost of infinite canvases, and even the tools built entirely around zoom run into its edges. A Figma user asked the forum why they could no longer zoom out to see all their content - "is there any reason why i now can not zoom out to see all the content?" - because they wanted to overview the file before zooming into sections. The thread, 105 views and 3 replies, ended with the answer that the file had grown to 100,000px wide and hit Figma's zoom limit. The overview they wanted was not available at any zoom level. Muse's 2020 memo on the infinite canvas made the sharper version of the point: arbitrary zooming lets you pull out to see the landscape and pull back in for detail work, "but this adds another layer of confusion because there is no consistent sense of scale."

What zoom was supposed to solve

The costs only matter if the benefits can be delivered another way, so here are the real jobs, stated fairly. On a large ERD, designers zoom out because they need to:

Reach an area far outside the viewport. The entity you want is somewhere off screen and panning to it is slow.
Spot tables a migration added outside the app. You ran an ORM migration, new tables now exist, and after a re-sync they are placed somewhere on a large canvas. You do not know where.
Find entities you just imported into a context view. They landed somewhere and now need arranging.
Get a first overview of a reverse-engineered database. A freshly imported schema arrives in a default layout, and before arranging anything you need to see the whole shape to reason about it.
Keep track of new entities you created in several places. You have been working across the diagram and want to see what you added.

Every one of those is a genuine need. Notice what they have in common: not one of them is a request to make the diagram smaller. They are all requests to locate something. Zoom is a way of answering a location question by shrinking everything until the answer happens to be on screen, which is a very indirect way to answer it.

How do I navigate a large ER diagram without zooming out?

Two features, split by whether you know what you are looking for.

If you know the name, search. Realtime fuzzy search across entity and field names takes whatever fragment you remember - not necessarily the start, not necessarily contiguous - and updates as you type.

Typing cndtio into a 59-entity schema returns the filter_conditions entity and every filter_condition_id field that references it, across three different tables - even though not one of those names contains the literal string cndtio. Arrow down, hit enter, and the viewport is on it. That is the "reach a distant area" job, done in a keystroke instead of a zoom-pan-zoom cycle.

If you do not know the name, use the minimap. A toggleable minimap sits at the bottom right of the canvas showing every legend and entity in miniature, with a rectangle marking the part the viewport currently covers. Click anywhere on it to jump there, or drag the rectangle to pan continuously. The main view and each context view carry their own minimap, so switching views switches the map with it.

And for the three jobs that are really "where did the new things land?", the minimap answers directly. An entity the database has not confirmed yet is drawn with a dashed border on the canvas, and on the minimap it is drawn in orange - the one case where the minimap uses color at all. In the schema above, the entity count has gone from 59 to 60 and the single orange block tells you exactly where the new table went. So when a re-sync pulls new tables in from the live database after an out-of-app migration, or when entities are imported into a context view, you can see where they landed without hunting for them.

The job	What zoom does	What Schemity does
Reach a distant entity you can name	Zoom out, find it, zoom back in	Fuzzy search, one keystroke to the entity
Find tables a migration added	Zoom out and scan for unfamiliar shapes	Dashed entities visible on the minimap
Locate entities imported into a context view	Zoom out and scan	Dashed on the minimap, exactly where they landed
Get a first overview of a reverse-engineered schema	Zoom out until it fits, if it fits	Minimap shows the whole shape at a fixed size
Move to another part of the diagram	Zoom out, pan, zoom in	Click the minimap, or drag its viewport rectangle

Why the minimap deliberately shows less

The obvious way to build a minimap is to render the diagram smaller. That reproduces the exact problem zoom has, because a shrunken copy of a dense ERD is an unreadable smudge.

So the minimap is not a small diagram. It draws only legends and entities, never relationships, and it ignores the custom colors you assigned to legends and entities on the canvas. It is a map of where things are, not a second copy of the diagram, which is why it stays readable no matter how dense or how colorful the ERD gets. The orange draft marker is the deliberate exception: the map spends its one color on the single question you cannot answer by looking, which is where the new thing went. Dropping the relationship lines is what keeps it legible at minimap size, and the information you lose is information you were not going to be able to read anyway.

That is the whole trade. Zoom offers a continuous range of scales, all of which change the geography and none of which is guaranteed to answer your question. A fixed-size map plus a name search answers the question directly and leaves the diagram exactly where you left it.

The general principle

Every feature that ships has to justify what it costs the people using it, and interaction costs are the easiest kind to overlook because each instance is small. A feature used a hundred times a day at two seconds of re-orientation is not a small feature.

The useful discipline is to write down the jobs a feature is really being asked to do, then ask whether something more direct can do them. For zoom on an ERD, the jobs were all location questions, and location questions have better answers than scale changes. That is also why you do not need a diagram of all 800 tables in the first place: the instinct to see everything at once is usually a navigation problem wearing a layout costume.

Database Views in Your ERD: Read-Only Entities, Not Fake Tables

Son Tran — Sun, 02 Aug 2026 03:02:00 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Database views carry real responsibilities - reporting layers, security boundaries, API surfaces - but ERD tools either leave them out entirely (DBML has no view support despite requests since 2022) or draw them as if they were ordinary tables. Schemity displays views and materialized views as read-only entities with italic names and a bold view or mview token in the entity footer, so derived relations are distinguishable from base tables at a glance, and they can be imported into context views like any other entity.

A database view belongs in your ERD, but not disguised as a table: it is a derived, read-only relation, and the diagram should say so at a glance. Schemity draws views and materialized views as read-only entities with italic names - present on the canvas, visually distinct from the base tables they are built on.

That sentence would be unremarkable if the rest of the tooling world agreed with it. Mostly, it does not. In most ERD tools your views are simply absent, and in the rest they are dressed up as something they are not.

The reporting layer your diagram pretends does not exist

Views are not decoration. They are where schemas put their public face: the reporting layer that joins five tables into one readable relation, the security boundary that exposes a subset of columns to an application role, the compatibility shim that survives a refactor. On Supabase, views are how you shape what PostgREST exposes as an API. A materialized view may be the single most performance-critical object in an analytics schema. Whoever reads your diagram to understand the system needs to see them.

Yet the diagram usually cannot show them. DBML - the schema language behind dbdiagram.io - has no syntax for views at all: a user proposed designing views with join definitions in December 2022, others were still upvoting the request in July 2024, and there has been no official reply. SSMS database diagrams accept tables only. And ChartDB, the most active cloud schema visualizer, shipped view support only in v1.15 in August 2025 - a year into the product's life - having earlier demonstrated the opposite failure mode: before views were modeled properly, you could draw a foreign key pointing into a view, which is exactly the kind of nonsense a diagram produces when it cannot tell a derived relation from a base table.

So the designer documenting a real schema gets a choice: leave the views out and hand readers a diagram that hides the reporting layer, or smuggle them in as fake tables and hand readers a diagram that lies about what is editable.

Tool	Database views in the diagram
dbdiagram.io (DBML)	Not supported - requested since Dec 2022, no official reply
SSMS database diagrams	Tables only
ChartDB	Added Aug 2025 (v1.15); earlier versions allowed a foreign key into a view
MySQL Workbench	Supported in EER models
Schemity	Read-only entities with italic names; importable into context views

A view drawn like a table is a small lie

The absence is bad; the disguise is worse. A view rendered as an ordinary table invites every wrong conclusion a reader can draw. It implies you could add a column to it the way you would to a table. It implies a foreign key could land on it. It implies its rows live somewhere, when they are a query executed on demand. Materialized views sharpen the trap: they do hold physical rows and can carry indexes, so they look even more like tables - but their columns are still derived, and the way to change one is to change its defining query, not to edit fields in a dialog.

The diagram should encode that difference, not rely on a naming convention (v_ prefixes are a workaround, not a design) or on the reader's memory of which boxes are real. Schemity uses three signals: views and materialized views are read-only on the canvas, so there is no field editing to be misled by; their names render in italics; and the entity footer says it outright, opening with a bold view or mview token ahead of the usual field and index counts, so nobody is left inferring the kind of relation from a naming convention. The distinction survives at any zoom level and in any export.

The same philosophy as the bold crow's foot for ON DELETE CASCADE: a structural fact about the schema deserves a visual channel of its own, one that cannot go stale.

How do I show database views in an ERD?

Open a diagram backed by your database in Schemity - version 2.9.0 or later - and the views are on the canvas alongside the tables - a desktop ERD tool reading the schema from the live database rather than from a hand-maintained model, so the derived layer is documented from the same source of truth as everything else. You arrange them, color them, and group them under legends exactly like base tables; you just cannot edit what is not editable.

The naming collision is worth untangling here, because Schemity also has a feature called context views, and the two are unrelated the way database view and point of view are unrelated. A context view is a focused sub-diagram that displays a chosen subset of the main diagram while the main view remains the single source of truth. Database views - the SQL kind - are entities inside your diagrams, and they can be imported into a context view like any other entity.

That combination is where the feature earns its keep. The reporting layer is usually its own bounded concern: a handful of views over a dozen base tables, consumed by dashboards and exports. Pull those views and their source tables into one context view and you have the reporting layer as a diagram - what feeds what, which base tables are load-bearing, where a refactor will ripple. The same works for a security-boundary story: one context view showing exactly which relations an application role can see, readable by the auditor who asked without a single query.

Views exist because base tables alone do not tell the whole story of a schema. A diagram that omits them - or forges them - tells even less of it. Put them on the canvas, in italics, where they belong.

SSMS Database Diagrams: Your ERD Is Trapped Inside the Database It Documents

Son Tran — Sun, 02 Aug 2026 03:01:21 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: SSMS keeps every database diagram as a binary blob in the sysdiagrams system table of the database it describes, so it cannot be saved to a file, versioned in Git, or opened without a server connection - and the feature itself was removed in SSMS 18.0 and restored in 18.1 only after user outcry. Schemity, a desktop ERD tool with SQL Server support, reverse engineers the same schema into a plain local JSON file that diffs in pull requests, exports to SVG and Mermaid, and re-syncs from the live database without losing your layout.

The database diagram you built in SSMS is not a file - it is a row of binary data in a system table called sysdiagrams, inside the very database it documents. That is why you cannot attach it to a design doc, review it in a pull request, or open it after the server is gone. Getting a SQL Server ERD you can actually keep means reverse engineering the schema into a tool that treats the diagram as a document you own.

Most people discover this the day they try to share the diagram. You spent an hour dragging tables into place, the picture finally explains the schema, and a teammate asks for a copy. There is no Save As. One user asked Microsoft directly how to save an SSMS ER diagram to a file so the team could open it, and the accepted workarounds were copy it to the clipboard as an image, or print it to PDF - a screenshot with extra steps. The diagram itself stays where it was born: inside the database, invisible to Git, unreachable without a connection.

A diagram stored as a binary row cannot be shared, diffed, or kept

sysdiagrams has a definition column of type varbinary(max), and your entire diagram - every table position, every annotation - is one opaque value in it. Every consequence follows from that storage decision. Copy the database with a script and the diagram is gone, because schema scripts do not carry system-table contents. Restore an old backup and you get the old diagram, with no way to see what changed. Two DBAs cannot work on the picture without overwriting each other. And nothing about the diagram can be reviewed, because there is nothing readable to review.

The feature's own history says how much weight it can bear. Microsoft removed database diagrams outright in SSMS 18.0 in 2019, brought them back in 18.1 after users pushed back, and only fixed the lingering breakage in 18.6. Even then the designer stayed coupled to the tooling version: connect SSMS 18.12.1 to SQL Server 2022 and it refuses with "This backend version is not supported to design database diagrams or tables" until you upgrade SSMS again. A diagram you cannot export, produced by a designer that has been removed once and version-locked ever since, is not documentation. It is a screensaver for one machine.

There is one more trap worth naming: the SSMS diagram designer doubles as a table designer. Saving a diagram can save table changes with it, so an absent-minded edit inside what you thought was a picture becomes a real ALTER against the database. A diagram should never have that power by accident.

How do I export a database diagram from SSMS to a file?

The honest answer is that you cannot - not as a diagram. The clipboard-image and print-to-PDF workarounds produce pictures that no tool can reopen, and the deeper trick of copying sysdiagrams rows between databases just relocates the blob without ever making it readable. Whatever you produce is frozen at export time and dead to version control.

So the useful move is to stop trying to get the picture out and instead get the schema out - which SQL Server hands to any client that asks the catalog. A desktop ERD tool that speaks SQL Server can connect to the database and reverse engineer the whole schema into a diagram in one step: tables, foreign keys, unique constraints, the lot. Schemity is built for exactly this - an offline, local ERD tool where SQL Server sits alongside PostgreSQL, MySQL, MariaDB, and SQLite as a first-class connection, over a direct connection or an SSH tunnel.

The difference is not the drawing. It is where the drawing lives.

	SSMS database diagram	Schemity diagram
Stored as	Binary row in `sysdiagrams`, inside the database	Plain JSON file in a local folder you choose
Version control	No - binary blob, nothing to diff	Yes - line-by-line diffs in Git and pull requests
Open without the server	No - requires a live connection	Yes - it is a local file
Survives tooling upgrades	Designer version-locked to the engine	File format independent of any server version
Export	Clipboard image or print to PDF	SVG, PNG, JPG, Mermaid, SQL DDL
Schema changes	Saving the diagram can silently alter tables	Nothing applies without a reviewed migration SQL diff

The diagram becomes a file: local JSON, versioned in Git

When Schemity reverse engineers your SQL Server database, the result is a plain JSON file in a workspace folder on your machine - ERD tool JSON storage in the most literal sense. Put that folder in a repository and you have a Git-native ERD: the afternoon you spend arranging tables into domains is committed, branched, and recoverable, and a schema change shows up in review as readable lines instead of an unexplained binary. This is how you version control a database diagram in Git without fighting the format.

Staying current stops being a rewrite, too. Re-sync pulls the latest schema from the live database every time you reopen the diagram - the live database stays the source of truth, new tables arrive ready to place, dropped ones vanish, and every entity you already arranged keeps its position. The layout work survives, which is precisely the work dashboard-style visualizers throw away.

And sharing finally works the way documents work. A teammate opens the diagram file in read-only mode with no access to the connection behind it. The picture leaves as a sharp SVG instead of a blurry clipboard bitmap, or as a Mermaid file that GitHub and Notion render natively, or as the SQL DDL itself when that is the real question. None of it requires the reader to have SSMS, credentials, or a matching tooling version.

Documentation should not live inside the thing it documents

The sysdiagrams design gets one thing exactly backwards: it makes the documentation depend on the system being documented. If the server is down, migrated, restored, or retired, the explanation of the schema goes with it - which is the moment you need the explanation most. The same failure wears other costumes: cloud tools that can lose a diagram outright because it is a row in someone else's database, and dashboards that regenerate the picture from scratch on every visit. The cure is the same each time - make the diagram a local file that outlives every server and every tool version, sitting in your repo next to the code that uses the schema.

Your SQL Server schema deserves a diagram with a path, not a diagram with a connection string. Take it out of the database.

Supabase Schema Diagram: Get an ERD You Can Keep, Not a Dashboard View

Son Tran — Sat, 01 Aug 2026 11:32:04 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: The Schema Visualizer built into Supabase Studio is a viewer, not a document - it renders one schema at a time, saves your dragged layout only to that browser's localStorage, and exports at most a flat image. The durable way to get a Supabase schema diagram is to connect an ERD tool to the underlying Postgres over the session-mode connection string (port 5432) and reverse engineer it. Schemity treats Supabase as a first-class connection, pulls the schema with every foreign key and constraint intact, keeps your layout across re-syncs, and stores the diagram as a plain JSON file in Git.

To get a Supabase schema diagram you can keep, connect an ERD tool to the project's underlying Postgres database - session mode, port 5432 - and reverse engineer it. The Schema Visualizer inside Supabase Studio will not get you there: it is a viewer bolted onto the dashboard - the layout you make lives in one browser, and the most it can hand you is a flat image.

That distinction takes about a week of real use to feel. The visualizer demos beautifully - open the dashboard, click Database, click Schema Visualizer, and your tables appear with lines between them. Then you try to use it as documentation and the seams show.

What the built-in Schema Visualizer actually gives you

The Schema Visualizer arrived in Supabase Studio 3.0 as an answer to one of the platform's oldest feature requests, and it is genuinely useful for a first glance. But three limits surface quickly.

It shows one schema at a time. A Supabase project is never just public - there are auth, storage, and graphql_public at minimum, and the visualizer renders each in isolation. The picture of how your application tables relate to the platform's is a picture nobody can draw in the dashboard. The gap is real enough that a community member built a separate tool to generate an ERD across all schemas - the "because Visualizer can't" is in the project's own tagline.

The layout lives in your browser, not in the project. Early versions opened vertically stretched and dropped your repositioning entirely; Supabase has since fixed the persistence half, so a dragged table now keeps its position across refreshes. But it keeps it in exactly one place: that browser's localStorage, keyed to the project and schema. Nothing syncs to the project itself - a teammate opening the same visualizer gets the auto-layout, a new laptop starts from zero, clearing site data erases the arrangement, and the relationship lines cannot be reshaped at all. An arrangement only one browser can see is a preference, not documentation.

What leaves is a picture, not a document. The visualizer can download the current view as an SVG or PNG, and each table's three-dot menu will copy that single table's definition as SQL or Markdown - genuinely handy for a quick paste. What it cannot produce is a diagram document: a file another tool can reopen, a layout a teammate inherits, anything Git can diff in a pull request. Even the SVG is not what the extension promises - it is the dashboard's HTML wrapped in a single foreignObject tag with the browser's computed styles inlined on every element. Exporting the same database both ways: 6.4 MB from the visualizer, with no SVG text elements and blank output in vector editors, against 99 KB of true vector from Schemity. The export is a flat image of one schema, frozen at the moment you clicked.

None of this is a flaw in Supabase - the dashboard's job is administering the project, not holding your data model. The mistake is asking a dashboard widget to be the schema diagram your team keeps, a job it was never built for.

How do I get an ER diagram of my Supabase database?

Underneath every Supabase project is a plain PostgreSQL database, and that is the door to walk through. Any tool that can reverse engineer Postgres can diagram a Supabase project - the only Supabase-specific part is picking the right connection string.

Open Connect in the dashboard and you will find three strings. They are not interchangeable for a schema tool:

Connection	Port	Built for	Works for an ERD tool?
Direct connection	5432	Long-lived servers	Yes, but resolves to IPv6 unless you have the IPv4 add-on
Session pooler (Supavisor)	5432	Long-lived connections over IPv4	Yes - the safe default
Transaction pooler	6543	Serverless / edge functions	No - connections are reclaimed after each query and session features are restricted

The session-mode string on port 5432 is the one to use: a schema tool wants exactly one ordinary, long-lived Postgres connection, and session mode provides it over IPv4 from anywhere. The transaction pooler on 6543 exists for a different problem - thousands of short-lived serverless invocations - and its restrictions are noise you do not need.

In Schemity, Supabase is a first-class connection type alongside PostgreSQL, MySQL, MariaDB, SQL Server and SQLite: paste the session string, test the connection before saving it, and the password goes into your operating system's keychain rather than any config file. Tag the connection with its environment - Local, Staging, Production - so the list stays scannable as projects accumulate. Then reverse engineer the schema into an ERD: every table arrives with its foreign keys drawn as crow's foot relationships, and the detail the dashboard never shows is on the entity itself - unique constraints as underlined badges, IN check constraints marking enum-like fields, defaults and nullability printed next to each column.

Because this is a desktop ERD tool reading your database directly, the workflow also survives the situations the dashboard cannot: the diagram opens offline on a flight, and the schema of a client's project never transits any third-party diagram cloud on the way to being documented.

The layout you arrange is the part you own

Reverse engineering gives you the truth; arranging it gives you the understanding. Drag the auth-adjacent tables together, group each domain under a colored legend, route the lines until the picture reads top to bottom - this is analysis work, and in the Studio visualizer it stays locked inside one browser's localStorage.

Schemity persists it structurally. The diagram is a plain JSON file in a folder on your machine, which means the ERD can live in your Git repository and the layout is versioned along with the model. When the schema changes - and on a Supabase project it changes every time you run a migration or click through the Table Editor - re-sync pulls the fresh schema on reopen while every entity you arranged keeps its position. New tables appear ready to drag into place; dropped ones vanish. The live database stays the source of truth for structure, and you stay the source of truth for the picture.

One diagram also does not have to carry everything. A context view is a focused sub-diagram that displays a chosen subset of the main diagram while the main view remains the single source of truth. Carve one per domain - orders, billing, content - and an orange dot on any entity signals a relationship pointing outside the view, so the focused picture never silently lies about coupling. For a project whose public schema has grown past what one canvas can say, that is the difference between a diagram people open and a wall poster people avoid.

Getting the diagram back out

The last thing a dashboard viewer cannot do is hand the picture to someone else, and it is where an owned file pays off repeatedly. Schemity exports the main view or any context view as SVG - sharp at every zoom level - as well as PNG and JPG for chat threads, and full SQL DDL when the question is really about the statements. It also exports a Mermaid erDiagram, which GitHub, GitLab, Notion and Obsidian render natively: the Supabase schema diagram in your README becomes text that renders as a diagram, reviewable in the same pull request as the migration that changed it.

The dashboard visualizer answers "what does the schema look like right now, while I am logged in." A reverse-engineered, re-synced, Git-versioned ERD answers the better question - "what is our data model, and how has it changed" - and answers it for the whole team, indefinitely. Point the tool at the database once, arrange the picture once, and the diagram stops being a second job without ever going stale.

ON DELETE CASCADE Is Invisible in Your ERD and in Your Database Logs

Son Tran — Thu, 30 Jul 2026 11:38:06 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: A cascading delete can travel through several tables, and neither a typical diagram nor MySQL's binlog will tell you how far it went - InnoDB runs cascades inside the storage engine, so child deletions never reach the SQL layer. Schemity stores ON DELETE and ON UPDATE on every relationship, draws a bold crow's foot at the child end of any relationship set to CASCADE, and surfaces a change to that action in the migration SQL diff before it runs, so the reach of a delete is readable on the canvas instead of buried in DDL.

The reach of a DELETE is decided by a property that most diagram tools never store and one major database never logs. That property is the referential action - CASCADE, RESTRICT, SET NULL - and it lives on the foreign key constraint, which means it belongs in the ERD every bit as much as the crow's foot does.

Ask a team what happens when a customer row is deleted and you get confident answers. Ask them to point at where that behavior is written down and the confidence drains. It is not in the diagram on the wiki, because the diagram draws a line between customers and orders and stops there. It is not in the ORM, or at least not reliably - the ORM has its own cascade setting, which may or may not agree with the database's. It is in the DDL of a constraint someone wrote three years ago, and the only way to know is to go read it.

What actually goes wrong with cascading deletes

The failure mode is not subtle when it happens. In a long-running SQL Server Central thread on whether to use cascade delete, one practitioner explains that he never uses cascade deletes after an experience with "a root delete cascading to an empty database" - a single statement at the top of a dependency tree that emptied everything below it. Another calls the feature "at least as dangerous as it is powerful," and recommends having proven recovery processes in place before turning it on rather than banning it outright. A third names the real problem precisely: cascade is hidden functionality. The row that disappeared was not named in any statement anyone ran.

The strongest defense in that same thread is also correct - cascades exist because before the standard had them, people implemented the same logic in triggers, inconsistently, and broke referential integrity doing it. Cascade is the right tool for rows that are a logical extension of their parent. Order lines have no meaning without the order. The problem is not the feature. The problem is that the decision to use it is invisible everywhere except the DDL.

And on MySQL, invisible is close to literal. A February 2026 analysis of InnoDB's cascade blind spot walks through the consequence: InnoDB handles cascade enforcement entirely inside the storage engine, so the child deletions never surface at the SQL layer. In row-based binlog with full image, only the parent deletion is recorded - the child table deletions are nowhere to be found. Audit plugins, including MySQL Enterprise Audit and the Percona Audit Log, miss them for the same reason. Triggers on the child table do not fire; the MySQL manual says so outright, and it has been tracked as bug #11472 since 2005. The article notes MySQL 9.6, released in January 2026, finally moves cascade handling to the SQL layer - which is welcome, and does nothing for the 8.x server you are running today.

So on the most widely deployed configuration of one of the most widely deployed databases, a cascading delete is a set of rows that vanish without appearing in the binlog, the audit log, or any trigger. The only place that behavior is declared is the schema. Which is exactly the artifact your ERD is supposed to be a readable rendering of.

How do I see what ON DELETE CASCADE will actually delete?

You trace the foreign keys outward from the table you are deleting from, following every child relationship whose action is CASCADE, and then follow the children's children. That traversal is the answer, and it is the thing an entity-relationship diagram is uniquely good at showing - if the diagram carries the actions. In Schemity it does, and it draws them: any relationship set to ON DELETE CASCADE gets a bold crow's foot at the child end, so the cascading edges of a table stand out from the ordinary ones without opening a single dialog.

This is why referential actions are not a detail to leave in the DDL. Cardinality tells you whether a customer can have many orders. The referential action tells you what happens to those orders when the customer is gone. Both are facts about the same foreign key constraint, and a diagram that renders one while dropping the other is doing half of its job:

Question about a foreign key	Where the answer lives	Typical diagram	Schemity
One or many on each side?	Whether the key is unique	Crow's foot notation	Crow's foot notation
Optional or mandatory?	Whether the key column is nullable	Usually an optionality circle	Optionality circle
What happens when the parent row is deleted?	`ON DELETE` on the constraint	Rarely shown - dropped on import	Bold crow's foot when set to `CASCADE`
What happens when the parent key changes?	`ON UPDATE` on the constraint	Rarely shown - same	Set and read on the relationship

The third and fourth rows are where diagrams quietly lose information. A tool that imports a foreign key as "source column, target column, done" has already discarded the deletion semantics of the schema, and no amount of re-arranging the picture brings them back. It is the same class of loss as drawing a 1:1 relationship as 1:N because the unique constraint was ignored: the tool read the key and skipped the constraint's properties.

Referential actions belong on the relationship, not in a text file

In Schemity, ON DELETE and ON UPDATE are set in the relation dialog alongside the relation type, with the full set of actions available - CASCADE, SET NULL, RESTRICT, NO ACTION, SET DEFAULT. They are properties of the relationship itself, stored in the diagram's JSON file next to the cardinality, which means they survive every round trip the diagram makes.

That matters in both directions. When you reverse engineer a live PostgreSQL, MySQL, or SQL Server schema, the foreign keys arrive with their referential actions attached, so the diagram you get back describes deletion behavior your production database already has - including the cascades nobody remembers adding. And when you change one, Schemity generates the migration SQL diff for you to read before anything runs, so switching a relationship from RESTRICT to CASCADE shows up as a reviewable statement rather than a checkbox someone ticked. Since the diagram is a plain JSON file, the same change also shows up as a line in a pull request diff, which is the second place a teammate can catch it.

Stored is necessary but not sufficient - a property you have to open a dialog to read is still effectively hidden in a diagram of eighty tables. So a relationship whose ON DELETE is CASCADE is drawn with a bold crow's foot at the child end. Ordinary relationships keep the normal weight; the cascading ones thicken. Scanning a table's outbound edges tells you immediately which of them will take rows with them.

Read that audit legend and the deletion story tells itself. All three tables - id_token_logs, pwd_histories, member_logs - hang off parents that live outside this group, and every one of those incoming relationships ends in a bold crow's foot. Deleting a member takes their password history and their event log with it, by design, and the diagram says so before anyone opens a constraint definition. It also shows how easily a cascade leaves its neighborhood - nothing inside the audit group is deleted directly, since the trigger for all three is a DELETE somewhere else entirely.

The signal is weight rather than color, and that is deliberate. Red would read as an error, and an error is something a designer feels obliged to fix - which is wrong here, because ON DELETE CASCADE on order lines under an order is a correct, considered decision. Bold says this one needs special care, not this one is broken. If you have already decided the cascade is right, you leave it, and the bold end remains as a note to the next person reading the diagram that a delete here is not local.

Tracing a cascade chain is then an ordinary reading task on the canvas. Click a relationship and Schemity highlights the whole line together with the foreign key field on the child and the primary key field on the parent, so which line goes where is never a guess even in a dense diagram. Set a color on the parent entity and every relationship originating from it inherits that color, so the outbound edges of the table you are about to delete from are visually grouped. When you want the exact text, right-click an entity or a legend to export its SQL and read the constraint definitions directly - no information_schema query, no clicking through five property dialogs.

Cascade chains cross bounded contexts, and that is where they get expensive

A cascade that stays inside one subject area is usually the intended kind. The dangerous kind leaves the neighborhood - a delete in the tenancy area that reaches into billing, or an identity cleanup that silently removes audit rows in a completely different module. Those are precisely the chains nobody traces, because nobody has the whole dependency structure in view at once.

A context view is a focused subset of the main diagram that shows one part of the model without the rest of the schema around it. When you are inspecting the deletion behavior of a table inside a context view, an orange dot on an entity tells you it still has at least one relationship to an entity that was not imported into this view - which is to say, this table's cascades may have effects you cannot see from here. A view that quietly hid those edges would let you conclude a delete is contained when it is not, which is the whole argument for why a view owes you back the context it removes.

One level up, the Context Map renders each context view as a node and draws an arrow for every dependency between contexts, with a badge showing how many foreign keys flow in that direction. Because the arrows are derived from real foreign keys, they are the routes a cascade can travel. Double-click an arrow and a panel lists the exact relations behind it - source field, target entity, constraint name - so "billing depends on tenancy through 7 foreign keys" becomes seven named constraints you can go and check the ON DELETE of. Arrow shape encodes health too: a straight arrow is a one-way dependency, a curved one means the two contexts depend on each other, and mutual dependency is where cascade reasoning stops being local. As with the rest of deriving your context map from the foreign keys you already have, none of this is hand-maintained - it is the schema, read at a different zoom level.

Soft deletion does not remove the problem, it moves it

The usual reaction to cascade anxiety is to stop deleting rows: add deleted_at, filter every query, keep everything. It is a legitimate choice, and it comes with its own bill. In a widely discussed argument that soft deletion probably is not worth it, the author - who worked at Heroku and Stripe - reports that in ten plus years, never once did anyone at any of those places actually use soft deletion to undelete something, while every SELECT in the codebase grew a deleted_at IS NULL predicate that is dangerous to forget. And when a real hard-deletion requirement arrives, the query that implements it is described as five times longer than the illustrated version and spanning a full 30 separate tables - the same cascade traversal as before, now written by hand in application code.

Soft deletion also changes what your constraints mean. A parent marked deleted still satisfies every foreign key pointing at it, so the database now believes in relationships the application considers dead. Uniqueness inverts too: UNIQUE (email) counts soft-deleted rows, so a user who deletes their account cannot sign up again with the same address unless the rule becomes unique-among-live-rows. That is a composite unique constraint or a partial unique index, not a single-column one, and it is exactly the kind of rule that deserves a named, colored badge on the diagram rather than a comment in a migration file - the same reason check constraints belong in the ERD instead of hiding your domain model.

The point is not that soft deletion is wrong. It is that hard delete and soft delete are two different sets of rules about what happens when a row dies, and both of them are expressed in constraints. Whichever you choose, the choice should be legible in the model.

Deletion semantics are part of the model

An ERD is supposed to be the single source of truth for the schema - one artifact that answers structural questions without anyone having to open a SQL console. That promise only holds if the diagram carries the facts the schema carries. Cardinality without referential actions leaves the most consequential property of a foreign key sitting in DDL nobody reads, on an engine that will not log it when it fires.

A desktop ERD tool that reads referential actions out of the live database, keeps them on the relationship, draws the cascading ones so they stand out, writes changes back through a reviewed migration, and stores the whole thing as JSON in your Git repository turns "what does this delete take with it" into something you can answer by looking - and something a reviewer can catch before it ships. That is a lower bar than it sounds like, and most tools still do not clear it.

Lucidchart ERD Alternative: A Desktop ERD Tool That Connects to Your Database

Son Tran — Sat, 25 Jul 2026 04:03:09 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Lucidchart draws entity relationship diagrams on a general-purpose canvas, so the schema has to be carried in by hand: run a query, export a CSV, upload it, then drag tables onto the canvas one at a time. Schemity is the offline desktop alternative that connects to PostgreSQL, Supabase, MySQL, MariaDB, SQL Server or SQLite directly, reverse engineers the whole schema with its relationships intact, and stores every diagram as a plain JSON file in your Git repo for $129 once.

If you want an ERD tool that reads your database instead of a file you exported from it, Lucidchart is the wrong shape of tool and Schemity is a direct answer: a native desktop app that opens a real connection, pulls the schema, and draws the diagram with foreign keys already wired. Lucidchart can absolutely render an ERD - but every path into it starts with you doing the extraction by hand.

That is not a bug in Lucidchart. It is what happens when a database diagram is one shape library inside a general-purpose diagramming canvas that also draws org charts, flowcharts, and network topologies. The canvas is excellent. It just does not know what a foreign key is until you tell it, and it has no way to go and ask.

The Honest Summary

Lucidchart is a browser-based visual collaboration suite with an Entity Relationship shape library. Multiplayer editing, comments, presentation mode, Confluence and Jira integrations, thousands of templates - all of it applies to your ERD the same way it applies to any other diagram. It is priced per seat, from a free tier through roughly $9 per user per month for Individual and up from there, and the free tier caps you at 3 editable documents with 60 shapes per document.

Schemity is an offline ERD tool for software engineers: a native desktop app that connects to PostgreSQL, Supabase, MySQL, MariaDB, SQL Server, and SQLite, reverse engineers the live schema into a diagram, generates the SQL migration diff when you change the model, and stores everything as plain JSON files you keep in Git. One $129 purchase, no account, no seats.

The distinction that matters is not cloud versus desktop. It is whether your diagram tool has a connection to the thing it is diagramming.

Lucidchart Cannot Connect to Your Database

The clearest statement of this comes from Lucid's own community forum. Asked whether there is a way to connect to a DB via ODBC/JDBC to reverse-engineer a schema into a Lucid ERD, the answer was that the database in question is not supported for ERD import, followed by the standing workaround: you could write a custom query and run it in your database if you'd like.

Read that as a workflow and it is a chore with several failure points. You write a query against information_schema in the exact shape Lucid's importer expects. You run it. You export the result as TSV or CSV. You upload the file. If anything about the output is off, you get a parse error and start again. Lucid has expanded the list of engines its importer understands - MySQL, PostgreSQL, Oracle, SQL Server, plus newer additions like Snowflake, Redshift, BigQuery and Azure SQL - but the mechanism underneath is still file upload. There is no connection to test, no credentials to store, nothing that can be re-run tomorrow when the schema has moved.

Schemity starts at the other end. You create a connection, directly or through an SSH tunnel, test it before saving, and Schemity reverse engineers the schema into an ERD - tables, fields, types, defaults, constraints, and the foreign keys as actual crow's foot relationships. Passwords go into the operating system keychain, never a config file. Connections carry an environment tag - Local, Staging, Production - so the production connection is visually distinct in the list before you click it. Nothing about pointing a diagram tool at a real database has to be an act of faith.

And because the connection persists, the diagram is not a one-time snapshot. Re-opening it pulls the current schema again: existing entities keep the positions you gave them, dropped tables disappear, new ones arrive ready to place. Keeping the ERD current stops being a separate job you keep postponing.

Why Relationships Disappear When You Import an ERD Into Lucidchart

The second symptom follows from the first. When schema arrives as a spreadsheet, the relationships arrive as columns in that spreadsheet, and whether they become lines on the canvas depends on the importer agreeing with your file. A Lucid community thread captures the experience exactly: I got my .csv file to import into LucidChart. I can see all of the tables. I clicked on the tables one at a time and no relationships were drawn. The documented behavior is that dragging related tables onto the canvas draws the relationship lines automatically when primary and foreign keys are set up correctly - which leaves the user debugging their CSV against an importer's expectations rather than looking at their schema.

In a tool built around a database connection, this class of problem does not exist, because relationships are never re-derived from an intermediate file. Schemity reads the foreign key constraints themselves, and it reads their properties: cardinality comes from whether the foreign key is unique, so a 1:1 stays a 1:1 instead of being flattened into a 1:N on the way in. ON DELETE and ON UPDATE behavior is configurable per relationship. Draw a new N:N by dragging between two entities and the junction table is created for you, with both foreign keys and a composite primary key already in place.

The reverse direction is closed too. Change the model on the canvas and Schemity generates the SQL migration diff for you to read - it runs against the database only when you decide to apply it. If you would rather not connect at all, importing a SQL dump or a set of CREATE TABLE statements produces the same entities and relationships, and DBML import brings over schemas from dbdiagram.io and the wider DBML toolchain.

Side-by-Side

	Lucidchart	Schemity
What it is	Visual collaboration suite; ERD is one shape library	Focused offline ERD tool for relational schemas
Platform	Browser, cloud account required	Native desktop app (macOS, Windows, Linux)
Getting schema in	Run a custom query, export TSV/CSV, upload the file	Direct connection or SSH tunnel; test before saving
Databases	Importer supports a fixed list; others via custom query	PostgreSQL, Supabase, MySQL, MariaDB, SQL Server, SQLite
Relationships	Derived from the imported file; must match the expected format	Read from the actual foreign key constraints
Keeping it current	Re-export and re-import	Re-sync on open; layout preserved, drift applied
Applying changes	Export SQL and run it yourself	Reviewed migration SQL diff, applied only on your approval
Where diagrams live	Documents in Lucid's cloud	Plain JSON files in a folder you choose
Collaboration	Real-time multiplayer editing, comments, presentations	Single-designer by design; review happens in Git
Pricing	Per seat, ongoing; free tier limited to 3 documents / 60 shapes	$129 one-time, unlimited diagrams

Placing 199 Tables by Hand

A third complaint in the same forum is the one that scales worst. A user importing a real database asked whether there is an easy way to add all tables, because adding one at a time for 199 tables is tedious and liable to errors as scrolling is terrible. The suggested fix is to drag the whole imported database onto the canvas at once - which solves the dragging and immediately produces the other problem, a single canvas holding 199 tables that nobody can read.

This is where a general canvas and a database tool genuinely diverge, because the answer is not a better auto-layout. It is that one diagram of every table was never the deliverable. Schemity reverse engineers the whole schema into a main view, gives you two predefined layouts to get past the initial pile, and then provides the tools that make a large schema navigable:

Fuzzy search across entity and field names. Type any fragment you remember - not necessarily contiguous - and jump straight to the entity or field.
Legends group related entities into named, colored regions on the canvas, so a 199-table diagram reads as a dozen domains.
Context views carve the schema into focused sub-diagrams. A context view is a focused subset of the main diagram that you arrange freely while the schema itself stays untouched, so the main view remains the single source of truth.
The Context Map then renders each context as a single node with arrows for the foreign keys flowing between them - the architecture view your schema already contains.

background, slides > background_color, training_templates > background and training_templates > background_color" width="800" height="556">

Instead of one canvas nobody can read, the schema splits into a list of named context views - each a bounded subject area you can open on its own.

And the Context Map draws the dependencies between those contexts from the actual foreign keys, with a count on every arrow.

Nine readable diagrams beat one wall poster, and a tool that models perspectives natively gets you there without duplicating a single entity.

Where Lucidchart Wins

The concessions are real, and for some teams they decide it.

Real-time collaboration. Several people editing one diagram simultaneously, with cursors, comments, and @-mentions. Schemity does not do this and does not intend to - it takes a deliberate single-designer position where one person holds the pen and feedback arrives through review. If your process depends on a live shared canvas, Lucidchart is built for it and Schemity is not.

Everything else on the canvas. Your ERD sits next to the sequence diagram, the org chart, the flowchart, and the whiteboard workshop from last sprint - in one document, in one product, with one integration story into Confluence and Jira. Schemity draws database diagrams and nothing else.

Zero installation and universal access. A browser tab and a link. Non-technical stakeholders can open and comment without installing anything. Schemity's read-only diagram mode lets someone explore a diagram without database access, but it is still an application they have to install.

A free entry point. Three documents and sixty shapes is not much, but it is enough to try the tool without a card. Schemity's answer is a two-week full trial, after which designing keeps working.

What Is a Good Lucidchart Alternative for Entity Relationship Diagrams?

It depends on which half of Lucidchart you were actually using. If the value was the shared canvas and the whiteboard culture around it, no database-specific tool will replace that, and you should keep Lucidchart for the diagrams that are genuinely about communication.

If the value was the ERD - if you are diagramming a database that exists, or designing one that will - then the useful alternative is a tool whose primitives are tables, foreign keys, and migrations rather than shapes and connectors. Schemity is that tool in its offline desktop form: connect, reverse engineer, model with the keyboard, review the migration diff, and keep every diagram as a JSON file that lives in the repo next to the code it describes. That last part changes the review workflow more than anything else on this page - a schema change shows up as a readable diff in a pull request, not as a screenshot pasted into a ticket.

There is also the arithmetic. A per-seat subscription is a permanent line item; the diagram stays accessible exactly as long as you keep paying, and what you can model gets metered along the way. A $129 one-time purchase ERD tool with unlimited local workspaces has neither property.

Who Should Use Lucidchart

Your diagrams are a team conversation and real-time co-editing is the point
The ERD is one artifact among many kinds of diagram in the same workspace
Stakeholders who will never install a desktop app need to open and comment
Confluence, Jira, and the rest of the Atlassian surface are where your documentation lives

Who Should Use Schemity

You are diagramming a database that exists, and want the tool to read it directly
Your engines are PostgreSQL, Supabase, MySQL, MariaDB, SQL Server, or SQLite
The ERD should live in Git, be reviewed in pull requests, and survive any vendor
Schema changes should produce a migration diff you approve, not SQL you hand-write
One purchase, no seats, no meter on how many tables you are allowed to model

The Bottom Line

Lucidchart is a strong diagramming product that happens to include ERD shapes. That framing explains every friction in this post: no live connection, relationships that depend on the file you fed it, and 199 tables to place by hand. If your diagram is a picture of a discussion, none of that matters.

If your diagram is a picture of a database, it matters constantly - and the fix is a desktop ERD tool that opens a connection, reads the constraints, keeps the layout, and writes the file to disk where Git can see it.

Comparing the database-native tools instead?

The cloud-generation schema visualizer: see ChartDB alternative.
The DSL-based sketch pad: see dbdiagram.io alternative.
The full desktop database IDE: see DbSchema alternative.

Comparing Staging and Production Database Schemas Side by Side

Son Tran — Thu, 23 Jul 2026 03:32:25 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Every environment runs a slightly different schema, and comparing them usually means diffing two SQL dumps line by line. Schemity reverse-engineers each environment into its own diagram in the same workspace, then merge-aware paste transfers one layout onto the other so the tables missing from the target arrive as dashed drafts - the drift, drawn.

Open your staging database and your production database as two diagrams in the same Schemity workspace, copy every entity from one and paste it into the other, and the drift draws itself: tables that exist in both snap into the same positions, and tables that exist only in the source arrive with a dashed border. No dump, no diff, no scrolling.

You already know the schemas don't match. That is not the hard part. The hard part is that nobody can say how they don't match without an afternoon of forensic work, and so the answer is usually a shrug and a deploy.

Why staging and production schemas drift apart

The gap opens through completely ordinary behavior. Something breaks in production at an inconvenient hour and someone runs an ALTER TABLE directly against it, meaning to backport the change into the migration files later. Red Gate, describing how this actually plays out, notes that many DBAs are forced to short-circuit the usual dev-test-prod model and apply the fix straight to production, because standing up a parallel hotfix environment "would cost too much in resources, time and money." Bytebase calls emergency hotfixes the number-one source of schema drift, for exactly this reason.

Then the environments diverge on their own. Neon's account of why your staging database never matches production puts numbers on the baseline: with a nightly refresh, "staging is between 0 and 24 hours behind production," and on a weekly cycle, 168 hours behind. Indexes are where it bites hardest - one added to production to rescue a slow query and never propagated back, so the same query "completes in 50ms in staging and times out after 30 seconds in production."

And migration tooling will not catch it for you. Flyway, Liquibase and Alembic record which migrations ran; none of them verify that the resulting schema is the one you expect. A migration marked applied says nothing about what somebody did to the table afterwards by hand.

How do I compare database schemas between staging and production?

The standard answers are all textual, and text is the wrong shape for this question.

Approach	What you get	What it costs
`pg_dump -s` both, then `diff`	Every difference, exactly	Sequence values, comment lines and column ordering create noise; a 200-table schema is thousands of lines
`information_schema` comparison queries	Precise column-level answers	You have to know what to ask before you ask it
Vendor schema-compare tools	A change script	Usually a per-seat subscription, and often SQL Server only
Two diagrams, side by side	Where the difference sits in the model	You need a tool that can hold both environments at once

The last row is the one that answers the question people are really asking. orders gained a fulfilment_status column in production is a fact. The fulfilment domain has a column in production that no other environment has, and three tables around it reference it is an answer. Only the second one tells you whether the next deploy is safe.

Holding two environments in one workspace

A Schemity workspace holds as many connections and diagrams as you want, so app-production, app-staging and app-local live next to each other in one list. Tag each connection by environment - Local, Staging, Production - and the list stays scannable, so you never have to squint at a host string to work out which database you are about to read. Test the connection before saving it, and every password goes into your operating system's keychain rather than a config file.

Then reverse-engineer each one into its own diagram. Open them at once and switch with Ctrl/Cmd + 1, 2, 3 - the same schema, three environments, one keystroke apart. Because Schemity is a desktop ERD tool working over your own connections, all three reads happen from your machine; nothing about your production schema is uploaded anywhere to make the comparison possible.

That alone is worth the setup. But flipping between two tabs only helps if the two pictures are arranged the same way, and a fresh reverse-engineer never is.

Merge-aware paste turns the layout into the diff

This is where the comparison becomes visual. Select every entity in the production diagram, copy, switch to the staging tab, and paste. Schemity matches entities by name and treats the two cases differently:

An entity that already exists in staging receives only the visual attributes - position, size and color, with the color carrying through to its relationship lines. The schema in staging is not touched.
An entity that does not exist in staging yet is pasted in full, with a dashed border marking it as a draft that the database has not confirmed.

So after one paste, staging is laid out exactly like production, and every dashed box on the canvas is a table production has that staging does not. Reverse the direction and you get the other half of the answer. The drift is not a report you read - it is the shape of the picture.

Nothing has been written to staging. Dashed entities are drafts, not changes: on a live-connected diagram the schema only persists after a migration succeeds, and saving warns you about entities the database has never heard of. If you decide the gap should be closed, the generated migration SQL diff hands you the ALTER statements to review - your decision, applied deliberately, not a sync button.

For field-level differences inside tables that exist in both, the diagram carries the detail on its face: nullable flags, defaults, unique badges and check-constraint underlines are all readable without opening a single dialog, and fuzzy search jumps you to any column by a fragment of its name.

Keeping the comparison honest over time

A one-off comparison is a snapshot. What makes it a practice is that each diagram re-syncs itself against its own database every time you open it - so the production diagram is always today's production, and the staging diagram is always today's staging. You are never comparing two stale pictures of each other.

Underneath, every diagram is a plain JSON file in a folder you can commit. Commit all three environment diagrams into the repo and the drift acquires a history: git diff shows what changed in production between Tuesday and Friday, reviewable in a pull request alongside the migration that should have caused it. That is the same argument as keeping the ERD in your Git repo, pointed at a different problem - not documenting one schema, but auditing the distance between several.

If the schemas are large, scope the comparison. A context view is a read-only, focused subset of the main diagram, showing one domain's entities without altering the model behind it. Compare the billing context across environments instead of all 200 tables, and export the SQL of just that view when you need the DDL. When the question is architectural rather than column-level, the Context Map answers it at the level of whole contexts.

Schema drift is not exotic. It is the ordinary residue of production being where the pressure lands - the environment where hotfixes happen, indexes appear, and nobody has time to backport. What you need is not a tool that prevents it, because nothing does. You need to be able to see it in ten seconds, on a picture you already understand, without your schema leaving the building to make it possible.

Roles and Permissions Schema Design for Multi-Tenant RBAC (Part 2)

Son Tran — Thu, 23 Jul 2026 03:31:44 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Roles belong to a tenant; permissions do not. A permission describes what the software can do, so it is system-wide and every tenant adapts to it. This part derives the roles, members_roles, roles_pems, and pems tables, and shows how a module and method pair extracted from your routing becomes the permission check your middleware runs on every request. A stable key on each permission survives module and method renames, and a deprecated_at timestamp retires removed permissions visibly instead of silently deleting grants from custom roles.

Multi-Tenant RBAC Data Model, Part 2: Roles, Permissions, and the Routing Table

Roles carry a tenant_id; permissions do not. That one asymmetry is the whole design. A role is something a tenant invents - "Regional Manager" means whatever that company decides it means - while a permission describes a capability of the software, and every tenant runs the same software. This part builds the four remaining tables on top of the tenants, users, and members foundation from Part 1, and then shows where the permission rows actually come from: your routing table.

We are assuming a micro framework with no opinion about authorization - no built-in users, no roles, no permissions, nothing to configure. Everything gets built from scratch. That sounds like more work, and it is, but it means every table below exists for a reason we can state out loud.

The Complete Multi-Tenant RBAC Schema

Here is where Part 1 was heading. Seven tables, and every relationship is one we can now derive.

Read it from the outside in. users and tenants are the two independent things. members sits between them as the tenant-scoped membership. roles hangs off tenants. pems hangs off nothing at all. And two junction tables - members_roles and roles_pems - carry the two N:N relationships that make role-based access control work: a member has many roles, and a role grants many permissions.

Why Roles Belong to a Tenant

roles carries tenant_id, and the unique constraint spans (tenant_id, name) rather than name alone. Both facts follow from the same observation: the word "Admin" is not a global concept. Every tenant gets to have one, and two tenants' Admins have nothing to do with each other.

Scoping the constraint to the pair is what makes that possible. A single-column unique index on name would mean the first tenant to create "Manager" takes the name away from everyone else - which is exactly the kind of accidental cross-tenant coupling that only shows up in production, on the day your second customer signs up. Scoping it to (tenant_id, name) says the real rule out loud: names must be unique within a tenant, and mean nothing outside it.

Why Permissions Are System-Wide, Not Tenant-Scoped

Now the table that surprises people: pems has no tenant_id.

The instinct in a multi-tenant schema is to stamp tenant_id on everything, because tenant isolation is the thing you are most afraid of getting wrong. But a permission is not tenant data. A permission says this software has an endpoint that archives a course. That fact is produced by your codebase, not by your customer. Every tenant is running the same deployment, hitting the same routes, exercising the same capabilities. There is exactly one true list of them.

Think about what a tenant_id on pems would actually commit you to:

Duplication with no variance. With 40 modules averaging 5 methods each, you have 200 permission rows. Add a tenant_id and 500 tenants turn that into 100,000 rows that are all copies of the same 200 facts.
A write on every deploy. Ship a new endpoint and you now have to fan a new permission row out to every tenant, forever, as a migration that grows with your customer count.
Rows that can disagree. The moment the same permission exists 500 times, 500 copies can drift. One tenant's row says the module is course, another says courses, and the middleware silently stops matching.

So the direction of adaptation runs one way: tenants adapt to permissions, not the other way around. A tenant cannot invent a capability the software does not have. What a tenant can do is compose - build its own roles out of the fixed permission vocabulary, and call them whatever it likes. That is the entire freedom a tenant needs, and roles already provides it.

This is also why pems sits alone on the diagram with a single line into it. It has no foreign key to anything. It is a vocabulary, and vocabularies do not belong to anyone.

	`roles`	`pems`
Scope	One tenant	The whole system
Defined by	The customer	The codebase
Changes when	An admin edits them	You deploy a new route
Unique over	`(tenant_id, name)`	`(module, method)`, plus a stable `key`
Row count	Grows with customers	Grows with features

Where Permission Rows Come From: Module and Method

If permissions are produced by the codebase, they should be read from the codebase rather than typed by hand into a seed file - and never frozen into a database enum type whose value set only a migration can change. That is what module and method are for.

Organize every feature as a module, and every module as a set of methods. course has list, read, create, update, archive. report has list, read, export. The pair is what identifies a capability, which is why the unique constraint on pems spans (module, method) - the same reasoning as (tenant_id, name) on roles, applied to a different pair. Neither half means anything alone; create is not a permission, and course is not a permission, but course.create is.

The way to keep that list honest is to attach the pair to the route itself. Whatever your framework's routing looks like, every route gains two pieces of metadata:

GET    /courses            -> module: course,  method: list
POST   /courses            -> module: course,  method: create
GET    /courses/{id}       -> module: course,  method: read
PATCH  /courses/{id}       -> module: course,  method: update
POST   /courses/{id}/archive -> module: course, method: archive

Now the routing table is the permission list. At deploy time, walk the registered routes, collect the distinct (module, method) pairs, and upsert them into pems. Adding an endpoint adds a permission automatically. More importantly, it becomes structurally difficult to ship an unguarded endpoint, because the route that has no module and method is the one that stands out in review.

Why Each Permission Carries a Key That Never Changes

Matching by (module, method) has one failure mode, and it is the most ordinary act in a codebase: renaming something. Decide that course should have been courses, update the routes, and the next deploy's upsert finds no row for the new pair - so it inserts one. The old row now matches no route, so it reads as removed, and every grant that referenced it - in every tenant, custom roles included - is attached to a row the middleware will never look up again. A rename, the safest refactor you can make in code, becomes a silent permission wipe in the database.

The fix is to separate what a permission is called from what it is. Each route carries one more piece of metadata: a key - an opaque unique string, a UUID generated once when the route is first written and hardcoded in source right next to module and method:

POST /courses -> key: 6b9d5f2a-..., module: course, method: create, default_roles: {Admin, Manager}

The deploy-time sync upserts by key: if the key exists, update its module, method and default_role_names in place; if not, insert a new row. Renaming course to courses is now an UPDATE to one row that every grant already points at, and nothing anywhere is lost. The unique constraint over (module, method) stays - the pair is still what the middleware matches at request time and still the human-readable identity - but the key is the identity that survives time.

The rename hazard does not disappear; it moves onto a field whose only job is to never change, and which nobody has a reason to change, because a UUID does not drift toward better naming the way words do. The one discipline it demands is that keys are generated fresh, never copy-pasted from the route above - a duplicated key is the new way to corrupt the list, and it is exactly the kind of mistake a unique constraint on key turns into a deploy-time error instead of a silent merge.

How Default Roles Bootstrap a New Tenant

There is a third piece of metadata on the route, and it is the one that pays off biggest: which default roles this capability belongs to.

POST   /configs   -> module: config,  method: create,  default_roles: {Admin}
POST   /courses   -> module: course,  method: create,  default_roles: {Admin, Manager}
GET    /courses   -> module: course,  method: list,    default_roles: {Admin, Manager, User}

Creating a system config is an owner-level act, so it is {Admin} and nothing else. Creating a course is ordinary operational work, so {Admin, Manager}. Listing courses is something everyone does, so all three. The developer writing the endpoint is the person best placed to make that call, and they make it once, at the route, next to the code it guards. That array lands in pems.default_role_names.

Now invert it at tenant creation. Every permission already knows which default roles it belongs to, so the bootstrap routine reads the whole pems table, groups by role name, and creates Admin, Manager and User for the new tenant with their grants already correct. No per-tenant configuration, no checklist, no human deciding for the four hundredth time that a manager can create a course. A brand-new tenant gets a complete, working set of roles for free, on the first request after signup.

Those default roles are read-only. A tenant can assign them to members as they are, but nobody - not even the tenant admin - can edit their permissions. Customization happens by duplicate and modify: need a "Course Coordinator" who is a Manager without billing access? Copy Manager, drop the permissions that do not apply, save it under a new name. The copy belongs to the tenant and is theirs to change however they like.

That restriction looks like a limitation and is actually the thing that makes the whole system maintainable, for a reason that only shows up on the next deploy. Hold onto it.

Either way, this is the composition freedom from earlier made concrete: a tenant cannot invent capabilities, but it can slice the fixed vocabulary any way it likes, starting from a sensible default instead of a blank page.

Storing this as an array rather than another junction table is deliberate. These are role names, not foreign keys - they cannot point at any tenant's roles rows, because at deploy time those rows do not exist yet, and after bootstrap each tenant has its own. The array is a template, read once per tenant and never joined against. Array types are first-class in PostgreSQL, and this is exactly the case they are for.

What Happens to Existing Tenants When You Add a Route

Nothing - until a sync runs, no existing tenant can use the new capability. Deploy course.archive with {Admin, Manager} and the permission row lands in pems immediately, but roles_pems holds no grant for it: tenant number one signed up last year, and its Admin role predates the route. So the deploy pipeline ends with a command - call it syncrolepems - that walks every tenant and syncs its default roles against the pems table: after it runs, each default role grants exactly the permissions that name it in default_role_names - no more, no less.

In member terms: every member holding a default role picks up the new permission the moment the pipeline runs syncrolepems, in every tenant at once. Members on custom roles get nothing - their roles stay exactly as their admin built them, until that admin grants the new permission on purpose.

This is where the read-only rule pays off. No tenant can have edited a default role, so there is no local intent to preserve - no diffing against the last run, no working out which permissions are new, just asserting the desired state in both directions. The removal direction is the one an incremental, add-only backfill silently gets wrong: decide that archiving a course is an owner-level act after all, drop Manager from the route's default_role_names, and the next deploy revokes the grant from every tenant's Manager, because the desired state no longer contains it. Re-running is free - the composite primary key on roles_pems makes every insert an on-conflict-do-nothing - so the command simply runs on every deploy.

Matching is by name, which is the second reason default_role_names stores names rather than ids: the same array that builds Admin, Manager and User for a new tenant locates the equivalent roles in every old one, and the (tenant_id, name) unique constraint makes that lookup exact.

The one hard boundary: never touch a user-defined role. The Course Coordinator a tenant copied from Manager is their artifact, frozen at the moment of copying, and the deploy pipeline has no standing to add powers the admin never chose or remove ones they did. Route removal is where that rule gets tested, because when a route disappears the capability genuinely no longer exists, and something has to happen to the grants pointing at it. The tempting implementation is to delete the pems row and let the foreign key cascade take the grants - clean, and silent, which is exactly the problem. The admin who added that permission to their Course Coordinator yesterday opens the role tomorrow and finds it shorter than they left it, with nothing anywhere to say why.

So removal is a state, not a deletion. When a key no longer appears in the routing table, the sync stamps that row's deprecated_at timestamp instead of issuing a DELETE. A deprecated permission denies at the middleware exactly as if it were gone - the capability really did leave the software, and the check simply requires deprecated_at to be null - but the pems row itself stays.

From there, the two kinds of role part ways, exactly along the ownership line drawn above. Default roles belong to the pipeline, so syncrolepems drops the grant outright: the desired state no longer contains the deprecated permission, and no notification is owed for rows no tenant ever edited. Custom roles belong to the tenant, so their grants are left precisely where they are - and the role editor renders the permission as deprecated. The custom role shows what happened to it instead of hiding it: the permission is right there, visibly retired, and the admin who added it yesterday learns the vocabulary changed rather than suspecting their role was tampered with. And if the route comes back next sprint, the sync clears deprecated_at on the same key - default roles get the grant re-asserted, and every custom-role grant resumes working, because none of them was ever destroyed.

Seen whole, the pems side of the sync is nothing but set membership on key. Because keys never change, one pass compares the keys extracted from the routes against the keys in the table, and every row falls into one of four branches:

Key in the routes and in the table, with a different module or method - a rename. Update the row in place; every grant stays attached.
Key in the routes but not in the table - a new capability. Insert it.
Key in the table but not in the routes - a deleted route. Stamp deprecated_at.
Key in both, but the row is stamped - the route came back. Clear deprecated_at.

A deleted route is an absence in source, not an event - but the sync never needs the event, because comparing full key sets makes the absence computable. And since all four branches are decided by key membership alone, renames and deletions cannot touch the same row, the branches run in any order, and the command stays safe to re-run blindly - the property this whole pipeline is built on.

One edge deserves a comment in the sync code before it costs a debugging session: in-place renames under the (module, method) unique constraint can transiently collide. If a deploy renames one permission onto the pair another permission just vacated, row-by-row UPDATE order decides whether the sync hits a unique violation halfway through. Declaring that constraint DEFERRABLE INITIALLY DEFERRED and running the sync in a single transaction moves the check to commit time, after every rename has landed - which is precisely the situation that PostgreSQL feature exists for. Retiring a verb from the vocabulary and erasing every sentence that used it are different operations - the first is a deploy, the second is a decision, made later, if ever.

One thing the ERD does not show: nothing in roles marks which rows are the read-only defaults. You can derive it - a role is a default if its name appears in some permission's default_role_names, and the unique constraint keeps that unambiguous - or you can make it explicit with a boolean column and let the database refuse the edit rather than the application layer. The derived version costs no schema change; the explicit one survives someone writing a second code path.

Which Role Does a New Member Get?

A members row appears the moment someone joins a tenant, and until they hold a role they can do precisely nothing. Something has to decide their starting permissions.

The schema-shaped answer is another boolean on roles: mark one row per tenant as the default, and assign it on signup. One column, per-tenant flexible, obvious. It is also the one column I deliberately leave out.

Consider how it fails. A flag is a switch, and switches get flipped - by a support engineer in an admin panel, by a migration that seeds the wrong row, by a helpful script. Flip it onto Admin and nothing breaks. No error, no failed request, no alert. Every person who joins that tenant from then on arrives holding full administrative access, and the system is behaving exactly as configured. You find out weeks later, if you find out at all.

That is what makes it disqualifying. It is not a one-time mistake, it is a standing condition that keeps manufacturing over-privileged accounts until somebody notices, and the blast radius grows with every signup.

So the default role is named in source code instead. User is the role with the fewest permissions, that fact is known while the routes are being written, and it belongs in the same place default_role_names already lives - the codebase. Changing which role new members receive becomes a code change: reviewed, diffed, deployed, attributable to a person. It stops being a checkbox.

The consequence is that privilege only ever increases by explicit human action. A new member who needs to be a Manager asks an admin to upgrade them, and somebody with the authority to grant it does so on purpose. That is a slightly worse user experience and a considerably better security posture: every escalation has a name attached, and the path of least resistance is the least-privileged one.

This is a different kind of flag from the read-only marker discussed above, and the difference is the whole argument. A read-only marker is descriptive - it states what a row is, and getting it wrong lets through an edit that should have been refused. An auto-assign marker is imperative - it causes privilege to be granted, on every future signup, with nobody looking. Those failure modes are not comparable, which is why one is a reasonable column and the other is not.

It costs something, and the cost is worth naming: a tenant cannot decide that its new members start as Managers. Everyone starts at the bottom and gets promoted. Some customers will ask for it, and the flexible version is entirely buildable - the boolean is easy to add and it would work. Choosing not to add it is a judgment that a silent, persistent failure pointing toward more privilege is the wrong risk to accept for the convenience it buys.

How Middleware Turns a Route into an Authorization Check

The two ends now meet in the middle, and they meet on the same pair of strings.

At deploy time, the routing table writes into pems: these are the capabilities that exist.

At request time, the middleware reads the matched route's metadata to learn which (module, method) this request requires, then asks one question: does the current member hold a role that grants it? The check never looks at the URL, the HTTP verb, or the controller name. It compares a pair of strings from the route against a set of pairs belonging to the member.

That is what makes the guarantee from Part 1 real - even if they know the API specs and bypass the UI, they will still be blocked at the API layer. There is no UI-side permission logic to bypass, because the UI was never the thing enforcing it. The route declares what it needs; the middleware decides. A client that calls the endpoint directly hits exactly the same check.

Resolving the member's permission set is a walk across the whole schema: members to members_roles to roles to roles_pems to pems. Four joins to answer one boolean.

Why the Junction Tables Have No ID

Both members_roles and roles_pems use the two foreign keys as their primary key, with no surrogate id in sight. Part 1 gave members its own id and argued hard for it - so why the opposite answer here?

Because these two really are nothing but pairings. roles_pems has no lifecycle: the row means this role grants this permission and it will never mean anything else. No status, no history worth keeping on the row itself, and nothing else in the schema will ever need a foreign key pointing at one specific grant. The pairing is the row's identity, so making the two keys the primary key is the honest shape, and it comes with duplicate protection for free.

members failed both of those tests, which is why it got an id. Look at the U badges on its tenant_id and user_id in the diagram: that composite unique constraint is doing the job the primary key does for roles_pems. One membership per user per tenant, guaranteed either way - the difference is only whether that guarantee also has to serve as the row's identity.

Same schema, same rule, opposite conclusions - which is the point. The shape of a junction table is a consequence of what the row means, not a habit you apply uniformly.

	`members`	`members_roles`, `roles_pems`
Primary key	Surrogate `id`	The two foreign keys
Pairing enforced by	A composite unique constraint	The primary key itself
Has its own state	Password, login attempts, status	Nothing beyond the pairing
Referenced by other tables	Yes, extensively	Never

And since the shape is a decision, the name is where to record it. The convention is small and worth adopting: pluralize both halves for a pure pairing, only the second half for a pairing that carries its own identity, and give the table a domain name once it is an entity in its own right.

members_roles, roles_pems - both plural. Composite key, nothing but the pairing.
member_roles - singular then plural. Surrogate id, the two foreign keys as ordinary fields, a unique constraint over the pair. The form for a junction that spans two bounded contexts and may have to survive them splitting into separate databases - it needs an identity that does not depend on the pairing staying put, but it is still recognizably a pairing.
members - a name of its own. Mechanical naming would have produced tenant_users, but the table on the left of that comparison is an entity that happens to join two tables, and the domain already has a word for what its rows represent. tenant_users would describe how the table came to exist; members describes what it is.

The payoff is that reading the schema stops requiring a lookup. roles_pems tells you it is a composite-key pairing; member_roles tells you it has an id and a unique constraint, and that somebody thought about why; members tells you to stop thinking of it as a junction at all. A name that disagrees with its own shape becomes an obvious thing to fix in review.

Drawing these is also where an ERD tool earns its keep or gets in the way. In Schemity, dragging an N:N relationship between two entities creates the junction table with both foreign keys and the composite primary key already in place, so the default shape is the correct one for a pure pairing - and when a junction turns out to need its own identity, you add the id and move the uniqueness into a named composite constraint instead of rebuilding the table.

The Constraint This ERD Cannot Express

One honest gap, because it is the classic multi-tenant RBAC bug and the diagram will not warn you about it.

Nothing in the foreign keys stops members_roles from linking a member in tenant A to a role owned by tenant B. Both foreign keys are individually valid - the member exists, the role exists - and the row is a cross-tenant privilege escalation. Referential integrity checks that rows exist, not that they belong to the same tenant.

There are three ways to close it, and the schema should pick one deliberately:

Carry tenant_id into the junction and use composite foreign keys, so the database itself refuses a mismatched pair. Strongest guarantee, at the cost of a wider key.
Enforce it in the application layer, where role assignment already knows the acting member's tenant. Cheapest, and correct until someone writes a second code path.
Enforce it with row-level security, if your database supports it and you are already scoping queries by tenant.

Whichever you choose, notice that the ERD is what surfaced the question. The gap is visible precisely because the auth tables and the account tables sit in different bounded contexts and you can see the lines crossing between them - roles.tenant_id and members_roles.member_id reaching into the account model from opposite directions, with nothing tying them together. When the coupling surface between two contexts is small enough to read in one glance, the missing constraint in it is findable.

Seven tables, one asymmetry, and a routing table doing double duty as the source of truth for what your software can do. That is a complete role-based access control model for a multi-tenant system, and none of it needed a framework's opinion to get there.

Many-to-Many in an ERD Shouldn't Mean Hand-Building the Junction Table

Son Tran — Wed, 22 Jul 2026 02:01:35 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Relational databases cannot store a many-to-many relationship directly, so most ERD tools make you hand-build the junction table - Microsoft documents six manual steps for one relationship. In Schemity, you drag between the two entities and pick N:N; the junction table appears with its foreign keys, composite primary key, and convention-following name already in place, as a real table you can rename and extend. One refinement: keep that composite primary key when both parents live in the same bounded context, but give a junction its own id plus a unique constraint over the pair when it bridges two contexts or grows a lifecycle of its own, like a subscription - so the pairing can recur and the contexts can split databases later without rewriting the table's identity.

A many-to-many relationship is one conceptual fact, and expressing one fact in your diagram should cost one gesture - not a hand-assembled third table with copied key columns and two carefully aimed relationship lines. The junction table is a mechanical consequence of the relationship, and mechanical consequences are exactly what a tool should produce for you.

Most ERD tools disagree. Microsoft's documentation for the database diagram designer in SQL Server Management Studio lays out six manual steps to map one many-to-many relationship: add the two tables, right-click to create a third, rename it in a dialog, copy the primary key columns from each parent into it, set the primary key to include all of the copied columns, then define a one-to-many relationship from each parent - making sure the junction lands on the "many" side both times. Six steps, five objects (three tables and two relationships), one fact.

And this is not a legacy-tool quirk. dbdiagram.io - a DSL-first tool built by people who think hard about schema notation - had users asking for native many-to-many support for years before the <> syntax shipped in June 2022. As one user put it in February of that year: "I have no idea why this is not implemented and it needs a vote, its basic ERD stuff." Until then, every book-author pairing meant writing the associative table out by hand.

Hand-built junction tables are where schemas quietly go wrong

The six steps are tedious, but tedium is the smaller problem. Each step is also a chance to encode a mistake that the diagram will happily render as correct:

Forget the composite key and nothing stops the same pairing from being inserted twice. A student_courses table without uniqueness over (student_id, course_id) records the same enrollment as many times as your application bugs allow.
Aim a crow's foot the wrong way and your junction sits on the "one" side of a relationship, which quietly turns the whole construction back into a 1:N.
Name the keys inconsistently - studentId in one junction, student_id in the next - and the schema drifts one hand-typed field at a time.

These are not beginner-only failures. They are what happens when a tool outsources a mechanical construction to a human, on the tenth junction table of a long modeling session. The difference between a 1:N and an N:N relationship is precisely the junction table and its composite key - get either wrong and the diagram claims a cardinality the schema does not enforce.

How do I create a many-to-many relationship in an ERD?

Conceptually, the answer is always the same: a many-to-many relationship cannot hold a foreign key on either side alone, so you resolve it into a junction table - a third table carrying one foreign key per parent - which turns one N:N into two 1:N relationships. That resolution is fully determined the moment you decide the relationship is N:N. Nothing about it requires human judgment.

So Schemity treats it as output, not input. Drag from one entity to the other and pick N:N in the relationship dialog, and the junction table is created automatically: one foreign key field per parent, the two keys forming a composite primary key so each pairing is unique, and a name generated from your naming convention, like students_courses. Prefer to place the table yourself? Draw two relationships into an empty entity and Schemity detects it as a junction table and does the same wiring. Foreign keys follow the snake_case or camelCase convention you set per connection, and land below the primary key instead of wherever the cursor happened to be.

	Hand-built (SSMS-style)	Schemity
Steps per relationship	6 documented manual steps	1 drag, pick N:N
Foreign key columns	Copied by hand from each parent	Added automatically, convention-named
Composite primary key	You remember to set it	Set automatically over both keys
Duplicate pairings	Possible if you forget uniqueness	Blocked by the composite key from the start
Junction naming	Typed in a dialog, per table	Auto-generated, editable

The junction table is a real table, not a notation trick

Some tools go to the opposite extreme and hide the junction entirely - a single N:N line with no table behind it. That reads nicely until the pairing needs data of its own, which it almost always eventually does: an enrollment gets a grade and an enrolled_at, a role-permission grant gets a granted_by. A junction your tool refuses to show is a junction you cannot extend.

Schemity's auto-created junction is an ordinary entity. Rename it, recolor it, add the attribute columns the relationship accrues, and when a pairing needs extra scoping, add a named composite unique constraint - each unique set gets its own colored U badge, so two overlapping rules on the same junction stay distinguishable. The full crow's foot notation on both lines keeps the two 1:N halves readable, with cardinality, ON DELETE, and ON UPDATE all configurable. You get the honesty of the physical schema and the convenience of the one-gesture shorthand - not a choice between them.

That combination matters most in the schemas that lean hardest on junctions. A multi-tenant RBAC design is essentially junction tables all the way down - members to roles, roles to permissions - and each one needs exactly the wiring described above. Building that model in a desktop ERD tool that constructs every junction correctly by default means the tenth one is as sound as the first, whether you are sketching offline on a laptop or working against a live development database. And because the auto-junction is derived from the relationship's cardinality rather than painted on, it obeys the same rule that keeps 1:1 relationships from being drawn as 1:N: the diagram only says what the constraints actually enforce.

When should a junction table have a composite primary key vs its own id?

There are two legitimate shapes for a junction table, and choosing between them is not a matter of taste - it is a matter of where the two parents live.

The first shape is the one the auto-junction gives you: the two foreign keys are the primary key. The pairing itself is the row's identity, uniqueness comes free from the key, and there is nothing extra to maintain. The second shape gives the junction its own surrogate id, keeps the two foreign keys as ordinary fields, and enforces the pairing with a composite unique constraint over both. Same duplicate protection - a different answer to the question of what the row is.

The rule that decides between them is the context boundary:

Both parents in the same bounded context: take the composite primary key. The link is an internal detail of one domain - nothing outside the context will ever address a link row directly, the two tables will live and move together, and the auto-created shape is exactly right. Drag, pick N:N, done. Maximum convenience, zero ceremony.
Parents in two different contexts: give the junction its own id and a unique-together constraint. A junction that bridges contexts is not an internal detail - it is the coupling point between two domains, and you cannot know how long those domains will keep sharing one database. If one context is ever extracted into its own service and schema, a foreign key cannot cross the database boundary anymore: the constraint gets dropped and the column degrades gracefully into a soft reference. When that column was an ordinary field guarded by a unique constraint, the split costs one small ALTER, and the row's own id - the thing audit records, events, and APIs have been pointing at - survives untouched. When that column was half of the primary key, the split forces you to restructure the table's identity, and everything that referenced it, at the worst possible moment.

There is a second hint that points to the surrogate shape, and it works even inside a single context: the junction has a lifecycle of its own. Some link tables never stay bookkeeping. A subscription is, structurally, the junction between a customer and a plan - a customer subscribes to many plans, a plan serves many customers - yet nobody models it as a bare pairing, because a subscription is born, trials, goes past due, and gets canceled; Stripe's API gives the subscription object eight distinct lifecycle statuses, from trialing to canceled. An enrollment is the same story one industry over. The moment a link row starts changing state, two things quietly break the composite-primary-key shape:

Other tables start pointing at the link row. Invoices reference the subscription, certificates reference the enrollment. With a surrogate id, each of those is one clean foreign key; with a composite primary key, every referencing table must carry both parent keys forever.
The pairing stops being unique for all time. A customer cancels and later resubscribes to the same plan; a student retakes the same course next term. Uniqueness becomes a scoped business rule - one active subscription per customer-plan pair - which a named unique constraint can be evolved or re-scoped to express, and which a primary key can never become without rebuilding the table.

So the full heuristic: take the composite primary key while the junction is pure bookkeeping inside one bounded context, and reach for the surrogate id plus unique-together constraint when the junction crosses a context boundary or the moment you catch it accruing a lifecycle. In practice the two signals travel together - the link tables that grow into real business entities are usually the very ones coupling two domains.

	Composite primary key	Own id + unique-together constraint
Row identity	The pairing itself	A surrogate id; the pairing is a named unique constraint
Best when	Both parents share one bounded context and the link is pure bookkeeping	The junction bridges two contexts, or is itself a business entity with a lifecycle
Other tables referencing the link row	Must carry both parent keys as a composite foreign key	Point at one clean id column
If the pairing can recur over time	Impossible - the primary key forbids the second row	Re-scope the unique constraint (for example, unique among active rows)
If the contexts split databases	Primary key must be restructured, references and all	Drop one foreign key constraint; the id and the unique pair survive
In Schemity	Drag between parents, pick N:N	Create the entity, drag one relationship from each parent, add a composite unique constraint

Schemity makes the second shape nearly as cheap as the first. Create the junction entity yourself - the active entity template already gives it its id primary key - then drag a relationship from each parent: both foreign keys land right below the primary key, named by your convention. Because the table now contains a field that is not a foreign key, the junction auto-detection stays out of the way and the surrogate shape is preserved; finish by spanning the two foreign keys with a named composite unique constraint, and its colored U badge announces the pairing rule on the diagram itself.

The boundary that drives this decision is also visible in the tool. A context view is a saved, focused view of your schema that shows only a subset of entities and the relationships between them - the practical form of a bounded context ERD. Put each domain in its own context view, and every cross-context junction you model shows up on the Context Map as a dependency arrow with its foreign keys counted - so the junctions that deserve the surrogate-key treatment are precisely the ones the map highlights.

Your ERD tool knows what a many-to-many relationship implies. It should be the one doing the implying - and when you deliberately overrule the default shape at a context boundary, it should make that shape just as cheap to build.

Why ERD Tools Draw Your 1:1 Relationship as 1:N

Son Tran — Wed, 22 Jul 2026 02:00:50 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: A 1:1 relationship in SQL is nothing but a foreign key with a unique constraint, so any tool that reads the key and ignores the constraint draws it as 1:N - a bug reported against MySQL Workbench in 2009 and against dbdiagram in 2025. Schemity derives cardinality from the constraint itself: toggle the foreign key's uniqueness and the relationship toggles between 1:1 and 1:N, and composite unique sets get named, colored U badges instead of one ambiguous marker.

A one-to-one relationship in SQL is not a special kind of line. It is a foreign key with a unique constraint - and any tool that reads the foreign key but ignores the constraint will draw your 1:1 as 1:N.

This is not a hypothetical failure. In March 2009, a user filed bug #43920 against MySQL Workbench 5.0.30: reverse engineering a script turned every 1:1 relationship into 1:N, which they called "a big problem if you use JPA and you generate the entities with some tool." The bug was closed as Not a Bug, with a developer explaining that Workbench's 1:1 relationship button "is just for the graphic not for the SQL" - the button changes the picture without emitting the unique constraint that would make the picture true. Users kept disputing that resolution in the comments from 2010 all the way to 2024.

Sixteen years after the original report, in May 2025, a dbdiagram user hit the same misreading from the other direction: they imported PostgreSQL SQL in which a column carried both a UNIQUE constraint and a FOREIGN KEY, and wrote, "By reading the SQL, I would expect the system to report the relation as 1:1 relation, but instead I see the system reporting it as a 1:n relation." Different tool, different decade, same bug - because both tools treat cardinality as something separate from the constraints that define it.

Why does my ERD show a one-to-one relationship as one-to-many?

Because your tool derives the relationship from the foreign key alone and never checks whether that key is unique. There are two versions of the failure, and the two reports above are one of each:

On the way in, the importer sees FOREIGN KEY and draws a crow's foot. The UNIQUE constraint sitting on the same column may well be parsed and stored, but it never reaches the code that picks the line ends. The schema says 1:1; the diagram says 1:N.
On the way out, the editor stores "1:1" as a drawing attribute. You pick it from a dropdown, the line ends change, and the generated SQL contains no unique constraint at all. The diagram says 1:1; the schema says 1:N.

Either way, the diagram and the database now disagree about a fact as basic as "can a user have two profiles?" - and whichever artifact your teammate happens to read determines what they believe.

Uniqueness is the cardinality, not a decoration

Relational databases have no CARDINALITY keyword. The relationship type is never stored anywhere as a fact of its own - it is a consequence of which constraints exist:

What the schema actually contains	What the diagram must draw
Foreign key, no unique constraint	1:N - crow's foot on the child side
Foreign key with a unique constraint or unique index	1:1 - a single bar on both sides
Foreign key inside a composite unique constraint spanning other columns	Still 1:N - the combination is unique, the key alone is not
Two foreign keys in a junction table, unique together	N:N, resolved into two 1:N relationships

The third row is the one that trips up even tools that do check uniqueness: UNIQUE (tenant_id, email) does not make tenant_id unique, so the relationship it participates in stays one-to-many. A tool cannot get this right by pattern-matching column names. It has to model unique constraints as first-class objects with member lists - which is exactly what most diagram tools skip.

This is the same lesson as reading crow's foot notation against the SQL it implies: the notation is a rendering of constraints, not an independent layer of truth. When a tool lets the rendering float free of the constraints, the rendering lies.

A relationship type you toggle, not repaint

Schemity makes the two facts one fact. A relationship between two entities is 1:1 precisely when its foreign key is unique - so you toggle between 1:1 and 1:N by toggling the foreign key's uniqueness, not by repainting line ends. There is no separate drawing attribute to fall out of sync, which means the Workbench failure mode - a 1:1 picture backed by 1:N SQL - cannot be drawn at all.

The same holds on the way in. When you reverse engineer a PostgreSQL, MySQL, or SQL Server schema into an ERD, unique constraints and unique indexes are read alongside the foreign keys, so a unique foreign key arrives as the 1:1 relationship it is. As a desktop ERD tool, Schemity does all of this locally - the schema you are reverse engineering never leaves your machine, which matters when the database you are documenting is the one you are not allowed to paste into a web app.

Composite unique constraints deserve names and colors, not one shared badge

Single-column uniqueness is the easy half. The harder half is the multi-column rule - "email is unique per tenant", "line numbers are unique within an order" - and it has been underserved in diagrams for a long time. Back in 2010, a Visual Paradigm Database Architect 5.2 user asked the forum how to see which columns belonged to a multi-column unique constraint; the patch that answered the request showed a single "U" on any column involved in any unique constraint. Better than nothing, but if a table carries two overlapping constraints, one undifferentiated marker cannot tell you which columns group together.

Schemity treats ERD composite unique constraints as first-class objects: each one has a member list, an optional name, and a color, and every involved field wears an underlined U badge in that color - so two different unique sets on the same table are distinguishable at a glance, and the composite unique constraint reads as the business rule it is. The entity footer keeps a running tally of fields, indexes, check constraints, and unique rules, so a table's rule density is visible before you open anything.

This is the constraint that carries most multi-tenant RBAC schema designs, where UNIQUE (tenant_id, email) is the difference between "email is a login" and "email is a login within one tenant." A diagram that cannot show which columns form the pair is hiding the tenancy rule itself.

The diagram should not be able to disagree with the schema

The Workbench developer was honest about the design: the 1:1 button was "just for the graphic." That is the root problem, and it is not specific to one tool - any ERD tool that stores cardinality as decoration will eventually show you a relationship the database does not enforce, the same way most tools hide the check constraints that encode your domain rules.

An offline ERD tool built for software engineers should work the way the database works: uniqueness is the cardinality, constraints are objects with identity, and the crow's foot at the end of a line is derived from facts, not chosen from a dropdown. When the diagram physically cannot say something the schema does not say, you stop having to ask which one is telling the truth.

Your DDD Context Map Is Already in Your Foreign Keys

Son Tran — Wed, 22 Jul 2026 02:00:14 +0000

Disclosure: I build Schemity, a desktop ERD tool - this post is from our blog and uses it for the examples.

TL;DR: Hand-drawn context maps go stale because nothing ties them to the schema, and cross-context coupling stays invisible until an extraction fails. Schemity's Context Map derives the map from your foreign keys: each context view becomes one node, arrows show dependency direction with a foreign key count, and double-clicking an arrow lists the exact foreign keys behind it.

You do not need to draw your context map, because your schema already contains it: every foreign key that crosses a context boundary is one edge of the map. Schemity's Context Map renders that map for you - each context view collapses into a single node, and the arrows between nodes are derived from the actual foreign keys in the diagram, not from anyone's memory of them.

The reason this matters is what teams do today instead. The context map - the DDD picture of which bounded contexts exist and who depends on whom - is usually a drawing. As one practitioner report on Context Mapper puts it, DDD models "are typically developed on a whiteboard or with Post-it notes," and few tools support maintaining them - which is why a dedicated DSL for writing context maps by hand has existed since 2018. A whiteboard photo is stale the day after the workshop. A hand-written DSL file is better, but it is still a second artifact: someone has to notice that the schema changed and go edit the map to match. Nothing enforces that, so nobody does it, and the map quietly stops being true.

Meanwhile the coupling the map was supposed to expose keeps accumulating where nobody is looking. One backend engineering account describes how a single innocent JOIN payments.transactions ON orders.payment_id = payments.id "ends up becoming the coupling hell," and recounts teams struggling for 3+ years to break core business logic out of a big database - because by the time anyone tried to extract a module, months of cross-module foreign keys had piled up unseen. The pain is not that the dependencies exist. It is that no view of the system showed them at the scale where they could be judged.

How do I see the dependencies between bounded contexts in my database?

Derive the picture from the schema instead of drawing it. In Schemity, an offline ERD tool built for software engineers, that is what the Context Map does.

A context view is a saved, focused view of your schema that shows only a subset of entities and the relationships between them - the natural home of a bounded context ERD. The Context Map is the level above: a view where each context view is rendered as a single node, and an arrow is drawn from context A to context B whenever entities in A hold foreign keys into entities in B. Each arrow carries a badge with the number of foreign keys flowing in that direction.

There is no separate modeling step to reach it. The contexts are the views you already saved while working on the schema, and the map is one click away from the list of them.

In my own multi-tenant auth schema - 56 entities, 71 relations on the main view - the Context Map collapses to three nodes: Account View, Auth View, Segment View. Between Auth View and Account View there are two arrows, one per direction: 1 foreign key flowing out of Account View, 5 flowing back into it. That asymmetry is the design in one glance - identity lives in account, and auth consumes it. On a whiteboard map I would have drawn one vague line labeled "uses." The derived map tells me the direction and the weight, and it can never disagree with the schema, because it is computed from it.

Each context view can carry its own color, and the Context Map inherits it: the node header and every outgoing dependency arrow take the context's color, the same way entity colors propagate to relationship lines one level down. Contexts stay recognizable at both zoom levels, and clicking a context highlights all of its dependency arrows, so inspecting one context on a busy map never means following lines by eye. Every arrow begins with a circle at its source end - the same discipline as line hops on the main canvas: where a line starts must never be a guess, even when it passes through another context on its way. On a map with many nodes, fuzzy search works here too - type a fragment of a context's name and the map focuses and highlights it - and the footer keeps the two numbers that describe the architecture in view: how many contexts, how many dependencies.

Three nodes is a small schema. Here is the same view on a larger one - a CMS whose footer reads 12 contexts and 20 dependencies between them:

At that size the whole architecture still fits on one screen, which is the point: twelve contexts and twenty dependencies is a paragraph of prose or an unreadable wall of 60 tables, but it is a single readable picture. Finding one context in it is a few keystrokes rather than a hunt.

The arrows carry one more signal: shape. A straight arrow is a one-way dependency. A curved arrow means the dependency runs both ways - a circular dependency between two contexts. That is exactly what the curved pair between Auth View and Account View admits about my schema: those two contexts lean on each other, and neither could be extracted without touching the other. Scanning a schema for context-level cycles used to be a query-writing exercise; on the Context Map it is a visual scan for curves.

Curves catch the two-context case. For cycles that hide across three or more contexts - A depends on C, C on B, B back on A - every individual arrow is straight, so no shape can flag them. That is a graph question, and the map gives you two ways to walk the graph. The manual way turns click-to-highlight into a traversal: click the context you are checking, follow its highlighted arrows to each target, and re-highlight round by round - if a round ever lights an arrow back to where you started, you have found an indirect cycle. One click is one round of that walk: the selected context keeps its arrows and their foreign key counts in full color while every other dependency drops back, so you are reading four edges instead of twenty.

Or ask the built-in AI chat, which analyzes the Context Map and names the cycles directly - the faster route when the map has many contexts. It will also re-arrange the map's layout on request, so tidying the architecture picture is one sentence, not a drag session.

Every arrow is backed by the exact foreign keys that create it

A high-level map you cannot interrogate is just a prettier whiteboard. So every arrow on the Context Map answers for itself: double-click it, and a panel lists each entity relation behind the dependency - source field, target entity, and the real constraint name.

The 5-key arrow from Auth View into Account View expands into member_roles.member_id -> members, otps.member_id -> members, otps.tenant_id -> tenants, roles.tenant_id -> tenants, and sso_configs.tenant_id -> tenants. Five keys, two shapes: a member identity or a tenant identity flowing inward.

The badge is a promise the panel keeps: one row per foreign key, always. On the CMS map above, the 3 on progress -> learning opens into three relations - trainee_badges.trainee_id, trainee_reward_points.trainee_id, and trainee_stage_points.trainee_id, each pointing at trainees, each with its real constraint name attached.

That is the difference between "progress depends on learning" and a work list. Three columns, three constraints to drop or replace - and the shape of the coupling is legible too: all three point at the same table, so this dependency is one concept borrowed three times, not three separate entanglements.

The nodes answer for themselves the same way. A context that carries a markdown description shows a file icon on its Context Map node, opening the rendered description in place - so the data dictionary that lives inside the ERD surfaces at the architecture scale too: what a context is for sits one click from the arrows that show what it depends on. This is where a boundary stops being a shape and starts being a rule: which tables the context owns, which it merely borrows as a scope anchor, and what it deliberately excludes.

That is a coupling surface you can defend in a design review - or the itemized work list you hand to whoever extracts the module. The "3+ years of untangling" story above is what happens when that list is assembled after the extraction decision instead of being one double-click away the whole time.

Why a derived context map beats a drawn one

	Drawn map (whiteboard, Miro, DSL)	Schemity Context Map
Source of the edges	Someone's memory of the schema	The foreign keys themselves
When the schema changes	Someone must notice and redraw	The map is derived, so it follows
Dependency weight	Not shown, or guessed	Foreign key count per direction
Drill-down	None - ask the person who drew it	Double-click lists every FK and constraint name
Direction of dependency	Often a line with no arrowhead	Always directional, one arrow per direction
Circular dependencies	Discovered during extraction	Curved arrows flag every cycle at a glance

The left column is not a strawman; it is the state of the art the Context Mapper authors describe. The right column is only possible because in Schemity the contexts and the schema live in the same file: the main view is the single source of truth, context views are perspectives on it, and the Context Map is derived from both. There is no moment where the map and the schema can drift, because the map is not stored - it is computed.

The third scale: coupling between contexts

I wrote before that you cannot judge coupling and cohesion from the same view - the main view answers coupling, a context view answers cohesion. The Context Map completes that instrument set with a third scale. The main view shows you which entities couple across borders; the Context Map shows you how much and in which direction, with the entities abstracted away entirely. And inside a context view, the orange boundary dot tells you an entity reaches outside the view - the Context Map is where that reach is finally analyzed rather than merely flagged.

This is the zoom ladder domain-driven design database schema work needs: a database context view to read each bounded context without the noise of all 800 tables, the main view to see every entity and edge at once, and the Context Map to see the architecture - contexts and dependencies, nothing else. All three are ERD perspectives on one set of entities in one local JSON file, in a desktop ERD tool that works entirely offline - so the context map you show in the architecture review is not a hopeful drawing. It is the schema, zoomed out.

And it travels. The Context Map exports as JPG, PNG, or sharp-at-every-zoom SVG, or as a Mermaid diagram that GitHub, GitLab, Notion, and Obsidian render natively - so the derived architecture picture can sit in the README of the very repo whose modules it describes, regenerated whenever the schema moves.