Skip to main content

qdbd

Interactive ER diagrams from QuickDBD text, DBML or a dbt project, readable at 200+ tables

PyPI version Python versions CI status Docs status Total downloads
VS Code Marketplace version Open VSX version Open VSX downloads Latest release License Ruff

Docs · Live demos · Quickstart · PyPI · VS Code Marketplace · Open VSX

The AdventureWorks DW star schema as a qdbd diagram, with the FactInternetSales table selected

AdventureWorks DW (28 tables), a star schema in five regions, built by qdbd. Try it live →

Searching, focusing and opening a table in a qdbd diagram

Watch the full 75-second demo →

What is qdbd?

qdbd is a command-line tool that turns a database schema written as text into an interactive ER diagram.

  • Diagrams drawn by hand look good, but they live outside the repo and go stale the first time the schema changes.
  • Generated diagrams stay current, but most become unreadable past a few dozen tables.

With qdbd the schema is a plain-text file in git, written in QuickDBD's syntax or DBML (dbdiagram.io's), or generated from a dbt project. qdbd checks it, lays it out, and builds one self-contained HTML page you can search, filter, click through and share.

You get a diagram that lives next to your code and stays usable at hundreds of tables.

qdbd is not affiliated with QuickDBD or dbdiagram.io. It reads the same text syntaxes, so schemas copy back and forth, and qdbd convert turns one syntax into the other.

Key features

  • QuickDBD-compatible: the parser mirrors QuickDBD's own, error messages included. A file that passes qdbd check --strict pastes into QuickDBD unchanged.
  • dbt import: qdbd import dbt reads manifest.json. Primary keys come from unique + not_null tests or constraints, relationships from relationships tests, and --infer-fks fills the gaps from column names.
  • Readable at 200+ tables: automatic layout, search, dbt-style selectors (+orders+1, group:marts, tag:fact), shaded regions per file, collapsed views and a minimap.
  • Review changes in pull requests: qdbd diff reports what a branch changed, the GitHub Action posts it as a PR comment, and --diff-base colours the changes in the diagram. To propose a column change, tag the column # @tag: added or # @tag: removed and it's drawn green or red (column tags).
  • VS Code extension: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor, or in your browser on localhost. Export, share, compare with git, convert to and from DBML, and dbt import from the sidebar or the Command Palette, with no terminal: it installs the CLI itself. Get it from the VS Code Marketplace or, for Cursor, Windsurf and VSCodium, Open VSX (docs).
  • AI agents: qdbd mcp gives Claude, Copilot and Cursor your schema as tools: tables and columns, join paths as SQL (composite keys included), checks for their edits and diffs against main (docs).
  • One schema, many outputs: an HTML page, PNG, SVG, editable draw.io, or a shareable link. Installs with pip: no Node, Graphviz or browser needed.

Every demo is a single HTML page written by qdbd build, from a QuickDBD schema or a dbt manifest.

200 tables
200 tables
Five business domains, 200 tables and every relationship type. Search, filter, click a table to focus it.
Schema diff
Schema diff
What a branch changed, coloured in: new tables in green, changed columns in amber, removals listed.
OMOP CDM on Synthea
OMOP CDM on Synthea
OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests.
Skytrax reviews (dbt yml)
Skytrax reviews (dbt yml)
Four star schemas, drawn by hand. One # @dbt: line adds the dbt yml's descriptions, pii tags and column types. Source: the qdbd-dbt-demo repo on GitHub.

View all 21 demos →

Quickstart

Fastest start: try it without installing

curl -O https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/examples/quickdbd-sample.txt
uvx --from quickdbd-cli qdbd serve quickdbd-sample.txt

A browser tab opens with the diagram and an editor. Change the text and the diagram reloads; drag tables to arrange them.

Or step by step

1. Install

pipx install quickdbd-cli      # or: pip install quickdbd-cli / uv tool install quickdbd-cli

Python 3.11+. See Install for other options.

2. Write a schema, or generate one from dbt

Save this as schema.txt, or paste in a schema from QuickDBD unchanged:

Customer
-
CustomerId PK int
Email string UNIQUE

Order as o
----
OrderId PK int
CustomerId int FK >- Customer.CustomerId
Total decimal(10,2)

A table is a name, a line of dashes, then one column per line. FK >- Customer.CustomerId means many orders to one customer. The full syntax is in Schema Syntax. DBML from dbdiagram.io works as it is, as .dbml or .txt (DBML).

For a dbt project, generate the schema instead:

dbt docs generate                                  # writes target/manifest.json + catalog.json
qdbd import dbt target/ -o erd/ --infer-fks        # one .txt file per dbt folder

3. Edit it live

qdbd serve schema.txt

Edit in the browser or in your own editor; the diagram reloads on save. Dragged positions are saved to schema.layout.json, which you commit next to the schema.

In VS Code (or Cursor), the extension does the same inside the editor, with errors as you type and the diagram following your cursor. Search QuickDBD in the Extensions view: it's on the VS Code Marketplace and Open VSX.

4. Build, export and share

qdbd build schema.txt -o schema.html      # one self-contained page
qdbd export schema.txt -o schema.png      # or .svg, .drawio
QDBD_ALLOW_SHARE=1 qdbd share schema.txt  # a link via a GitHub gist: off by default, see the disclaimer

Run in CI

The GitHub Action checks the schema and builds the diagram. On pull requests it also posts one schema-diff comment, updated on every push.

# .github/workflows/erd.yml
name: ERD
on: [pull_request, push]
jobs:
  erd:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: MarkPhamm/quickdbd-cli@v0.6.3
        with:
          path: erd/                  # schema file(s) or folder(s)
          output: site/index.html

dbt projects, GitHub Pages, pre-commit and GitLab CI are covered in CI and Automation.

How qdbd works

dbt project ──qdbd import dbt──┐
                               ├──▶ schema/*.txt, *.dbml   (QuickDBD syntax or DBML, in git)
hand-written / pasted ─────────┘           │
                                           ├──▶ qdbd check   validation, QuickDBD's error messages  ──▶ CI gate
                                           ├──▶ qdbd serve   live editor, drag to arrange           ──▶ schema.layout.json
                                           ├──▶ qdbd build   interactive HTML                       ──▶ GitHub Pages, artifacts
                                           ├──▶ qdbd diff    what changed vs main                   ──▶ PR comment
                                           ├──▶ qdbd export  PNG · SVG · draw.io                    ──▶ docs, slides, wikis
                                           └──▶ qdbd mcp     schema tools for AI agents             ──▶ Claude, Copilot, Cursor
  • The parser follows QuickDBD's own parser step by step, so the same text gives the same tables and the same errors.
  • The layout comes from ELK. Positions you drag are saved by table name, and new tables are placed next to the tables they relate to, so the diagram doesn't reshuffle.
  • One renderer draws both the page and the images. It runs in the browser, and inside an embedded JavaScript engine for CLI exports, so a PNG always matches the page.
  • Builds are deterministic: no timestamps or randomness, so the output only changes when the schema does.

What it looks like

1. The schema, a text file in your repo:

# Every order belongs to one customer.
Order as o
----
OrderId PK int IDENTITY
CustomerId int FK >- Customer.CustomerId
Status string="pending" # current fulfilment state

2. The command:

qdbd build schema/ -o erd.html

3. The page: click a table for its columns, comments and relationships, or type another table's name to get the join path as SQL.

Table details panel

qdbd and QuickDBD

qdbd QuickDBD
Text syntax QuickDBD's or DBML QuickDBD's
Tables per diagram no limit 10 on the free plan
Where it runs your terminal and CI; the result is a static HTML file the QuickDBD web app
Where the schema lives .txt / .dbml files in your git repo the web app
dbt import, schema diffs, PR comments ✅ —

Use QuickDBD's editor when you want it: a schema that passes qdbd check --strict pastes in unchanged.

FAQ

Do I need a QuickDBD account? No. qdbd only borrows the text syntax.

Does qdbd connect to my database? No. It reads .txt / .dbml schema files or a dbt manifest.json. Nothing connects to a warehouse.

Does my schema leave my machine? Only if you turn sharing on (QDBD_ALLOW_SHARE=1, or quickdbd.allowSharing in VS Code) and run qdbd share, which uploads the page to a GitHub gist in your account (secret by default), publish it yourself (a tunnel, GitHub Pages), or connect an AI agent through qdbd mcp, whose answers go to your AI provider. qdbd serve loads its code editor from a CDN; the built pages load nothing.

How big can a diagram get? The demos go up to 200 tables. Search, selectors, regions and collapsed views keep large diagrams workable; --select builds a page with just the part you need.

Can I edit the diagram by hand? You edit the text; the diagram is generated from it. Table positions are the one thing you arrange yourself, by dragging in qdbd serve.

Learn more

About the author

qdbd is built and maintained by Minh (Mark) Pham (@MarkPhamm). Issues, ideas and pull requests are welcome on GitHub.

License

Apache-2.0. Bundled third-party files (ELK, Inter) and the sources of the demo schemas are listed in NOTICE.

Metadata

Release files for quickdbd-cli 0.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for quickdbd-cli 0.6.3
File Size Uploaded Provenance Actions
quickdbd_cli-0.6.3.tar.gz 1.3 MB Without provenance Details for quickdbd_cli-0.6.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for quickdbd-cli 0.6.3
File Interpreter ABI Platform Actions
quickdbd_cli-0.6.3-py3-none-any.whl Python 3 none any Details for quickdbd_cli-0.6.3-py3-none-any.whl

Total release size: 2.6 MB

Release files / quickdbd_cli-0.6.3.tar.gz

Download URL quickdbd_cli-0.6.3.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
fe98f71383c887ea9bffb2e4d1d55fb1eb17526e6913793e7f5ef3c8752e093b
BLAKE2b-256 checksum
How to use checksums
6912c26acefe688c0ce9490a5ab0be721ff427c662beab616192e40d63088699
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Release files / quickdbd_cli-0.6.3-py3-none-any.whl

Download URL quickdbd_cli-0.6.3-py3-none-any.whl
Size 1.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c52163faf1a9dcc7e85ac2216ab1d7db9e4dd7204d16723c1263d29c8ee29b76
BLAKE2b-256 checksum
How to use checksums
5a3c6e7e71b41b29deefc9e4a7ae726a33e81bff09d7ffa056523150a38cee77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Security for quickdbd-cli 0.6.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page