DBeaver ER Diagrams: Live and Offline Schema Visualization That Actually Helps Onboarding

The problem: a new database, zero documentation, and a Friday deploy

You inherit a PostgreSQL instance with 200 tables, no foreign keys documented in the wiki, and a team that communicates schema changes through Slack screenshots. You need to understand the data model before Monday's migration window. Opening psql and running \d on every table isn't a plan.

DBeaver's ER Diagram feature solves this twice: once with a live connection for exploration, and again offline from migration scripts for version-controlled documentation. Both modes share the same layout engines, filter controls, and export formats — so the diagram you explore today can become the diagram you commit tomorrow.

Live connection: force-directed overview, hierarchical documentation

Open Database → New ER Diagram, pick your connection, and select the schemas you care about. DBeaver reads declared foreign keys, indexes, and constraints automatically across 80+ database engines. You get two layout algorithms:

• Force-directed — nodes repel, edges act like springs. Good for a first glance at a 50-table domain; clusters emerge naturally.
• Hierarchical (Sugiyama) — layers tables by dependency direction. Foreign-key arrows point downward, producing the clean "boxes and lines" diagram you'd draw by hand.

Both layouts let you drag nodes manually; positions persist in the .dbeaver-er file inside your project. A filter dialog (schema, table name pattern, object type) keeps noise down — essential when the catalog has hundreds of tables but you only care about the billing schema.

Offline reverse engineering: diagrams from migration folders

Point DBeaver at a directory of Flyway or Liquibase SQL files (File → New → ER Diagram → From SQL files) and it builds the same diagram without a live connection. This is the CI-friendly path: your documentation pipeline can generate a PlantUML or Mermaid file on every merge, commit it alongside the migrations, and render it in GitHub Markdown or Confluence.

Supported export formats: PNG, SVG, PDF, GraphViz DOT, PlantUML, Mermaid. The text-based formats (PlantUML, Mermaid, DOT) are the ones that survive code review — reviewers see schema diffs, not binary image diffs.

Worked example: generating a version-controlled diagram from Flyway migrations

1. Create a folder db/migrations with Flyway-named files:

   V1__init.sql
   V2__add_orders_fk.sql
   V3__add_indexes.sql

2. In DBeaver: File → New → ER Diagram → choose From SQL files → select the folder.
3. Pick Hierarchical layout, enable Show indexes and Show constraints in the options pane.
4. Right-click the diagram background → Export → PlantUML → save as docs/schema.puml.
5. Add a GitHub Action step that runs plantuml -tsvg docs/schema.puml and commits the SVG, or embed @startuml ... @enduml directly in a Markdown file for GitHub's native Mermaid renderer.

Result: a diagram that lives in the repo, updates with every migration, and requires no database credentials to view.

Trade-offs you'll hit

• Layout persistence is workspace-local. The .dbeaver-er file stores node positions, but the .dbeaver project metadata (which remembers which diagram file belongs to which connection) lives in the workspace .dbeaver folder. Sharing a diagram across machines means exporting the whole project or using Team Edition's shared project storage.
• Performance drops above ~500 tables. The diagram editor lags on monolithic views. Workaround: create multiple focused diagrams per domain/schema instead of one giant canvas.
• Implicit relationships are invisible. If your codebase uses a naming convention like user_id → users.id without a declared FK, DBeaver won't draw an edge. Only declared foreign keys appear.
• PlantUML/Mermaid export drops coordinates. The exported text contains only graph structure; the target renderer (PlantUML server, Mermaid.js) re-lays-out the diagram. The visual arrangement you crafted in DBeaver won't survive the round-trip.

Try it this afternoon

1. Open DBeaver → Help → About → Installation Details → Features → verify "ER Diagram" version matches your DBeaver release (24.x includes hierarchical layout).
2. Create a throwaway diagram from your development database: Database → New ER Diagram → pick one schema → choose Hierarchical → apply a table name filter like order%.
3. Right-click background → Export → PlantUML → paste the output into a Markdown file and preview it. If the syntax renders, you have a documentation pipeline candidate.
4. If you maintain Flyway/Liquibase scripts, repeat step 2 with File → New → ER Diagram → From SQL files pointing at your migrations folder.

Ten minutes of clicking replaces hours of manual diagram drawing — and the output lives in source control where it belongs.