dbterd

Generate ERD-as-a-code from your dbt projects

Transform your dbt artifact files or metadata into stunning Entity Relationship Diagrams using multiple formats: DBML, Mermaid, PlantUML, GraphViz, D2, DrawDB, and a canonical JSON payload

python-cli

🚀 Quick Start

Two ways to get your first ERD on screen — pick whichever matches your mood:

🖱️ Prefer a GUI? Install the dbterd for VS Code extension, open your dbt project, and explore interactive ERDs without touching the command line.

⌨️ Prefer the CLI?

pip install dbterd --upgrade
dbterd run -ad samples/dbtresto

That's it — your diagram is generated. Read on for the full tour.

🎯 Entity Relationship Detection

dbterd intelligently detects entity relationships through three algorithms — pick the one that matches how your dbt project expresses its data contracts:

🧪 Test Relationships (default) — infers relationships from dbt relationships data tests
🏛️ Semantic Entities (-a semantic) — detects relationships via dbt Semantic Layer entity definitions
📜 Model Contract Constraints (-a model_contract) — detects relationships via dbt model contract's foreign_key constraints (dbt 1.9+ / manifest v12+)

For detailed configuration options, see our CLI References.

🎨 Supported Output Formats

No need to pick just one — dbterd has a format for every occasion, from quick GitHub previews to full-blown interactive database designers.

Format	Description	Use Case
DBML	Database Markup Language	Interactive web diagrams
Mermaid	Markdown-friendly diagrams	Documentation, GitHub
PlantUML	Text-based UML	Technical documentation
GraphViz	DOT graph description	Complex relationship visualization
D2	Modern diagram scripting	Beautiful, customizable diagrams
DrawDB	Web-based database designer	Interactive database design
JSON	Canonical, schema-validated ERD payload	Tooling & integrations (VS Code extension, custom apps)

🎯 Try the DBML Demo, or see the canonical JSON payload that powers the VS Code extension and docs sites!

🌟 Ecosystem

dbterd plays well with others. These companion projects build on top (and "down")of it to take your ERDs beyond the command line:

Project	What it does
	dbterd-vscode — a VS Code extension that turns your dbt project into interactive ERDs without ever leaving your editor, powered by `dbterd` under the hood.
	`dbdocs` — an alternative dbt docs site — catalog, ERD, and column-level lineage baked into a single self-contained HTML file.
	`artifact-parser` — a pluggable framework that converts JSON artifacts into typed, validated Python objects

🚀 Installation

Requires Python 3.10+. dbterd 1.25 was the last release to support Python 3.9; support was dropped since 1.26, as 3.9 reached end-of-life in October 2025 and the dbt 1.11 artifact parser emits X | Y type annotations that won't evaluate on it anyway. If you're still on 3.9, pin dbterd==1.25.* — otherwise upgrade your interpreter (it's worth it).

pip install dbterd --upgrade

Verify Installation:

dbterd --version

[!TIP] For dbt-core users: It's highly recommended to keep artifact-parser updated to the latest version to support newer dbt-core versions and their manifest/catalog json schemas:
pip install "artifact-parser[dbt]" --upgrade

⚙️ Configuration Files

Tired of typing the same CLI arguments repeatedly? Your fingers deserve better. dbterd supports configuration files to streamline your workflow!

# Initialize a configuration file
dbterd init

# Now just run with your saved settings
dbterd run

Supported formats:

.dbterd.yml - YAML configuration (recommended)
pyproject.toml - Add [tool.dbterd] section to your existing Python project config

Learn more in the Configuration Files Guide.

💡 Examples

CLI Examples

🖱️ Click to explore CLI examples

# 📊 Select all models in dbt_resto
dbterd run -ad samples/dbtresto

# 🎯 Select multiple dbt resources (models + sources)
dbterd run -ad samples/dbtresto -rt model -rt source

# 🔍 Select models excluding staging
dbterd run -ad samples/dbtresto -s model.dbt_resto -ns model.dbt_resto.staging

# 📋 Select by schema name
dbterd run -ad samples/dbtresto -s schema:mart -ns model.dbt_resto.staging

# 🏷️ Select by full schema name
dbterd run -ad samples/dbtresto -s schema:dbt.mart -ns model.dbt_resto.staging

# 🌟 Other sample projects
dbterd run -ad samples/fivetranlog -rt model -rt source
dbterd run -ad samples/facebookad -rt model -rt source
dbterd run -ad samples/shopify -s wildcard:*shopify.shopify__*

# 🔗 Custom relationship detection
dbterd run -ad samples/dbt-constraints -a "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

# 💻 Your local project
dbterd run -ad samples/local -rt model -rt source

Python API Examples

Generate Complete ERD

from dbterd.api import DbtErd

# Generate DBML format
erd = DbtErd().get_erd()
print("ERD (DBML):", erd)

# Generate Mermaid format
erd = DbtErd(target="mermaid").get_erd()
print("ERD (Mermaid):", erd)

# Generate canonical JSON payload (nodes/edges/metadata)
erd = DbtErd(target="json").get_erd()
print("ERD (JSON):", erd)

Generate Single Model ERD

from dbterd.api import DbtErd

# Get ERD for specific model
dim_prize_erd = DbtErd(target="mermaid").get_model_erd(
    node_unique_id="model.dbt_resto.dim_prize"
)
print("ERD of dim_prize (Mermaid):", dim_prize_erd)

Sample Output:

erDiagram
  "MODEL.DBT_RESTO.DIM_PRIZE" {
    varchar prize_key
    nvarchar prize_name
    int prize_order
  }
  "MODEL.DBT_RESTO.FACT_RESULT" {
    varchar fact_result_key
    varchar box_key
    varchar prize_key
    date date_key
    int no_of_won
    float prize_value
    float prize_paid
    int is_prize_taken
  }
  "MODEL.DBT_RESTO.FACT_RESULT" }|--|| "MODEL.DBT_RESTO.DIM_PRIZE": prize_key

🤝 Contributing

We welcome contributions! Whether you've found a bug, dreamed up a feature, or just want to fix a typo — you're very welcome here.

Ways to contribute: 🐛 Report bugs | 💡 Suggest features | 📝 Improve documentation | 🔧 Submit pull requests

See our Contributing Guide for detailed information.

Show your support:

⭐ Star this repository
📢 Share on social media
✍️ Write a blog post
☕ Buy me a coffee

👥 Contributors

A huge thanks to our amazing contributors — the people who turned "wouldn't it be nice if..." into actual working code. 🙏

📧 Support

Need help? We're here for you! Check 📖 Documentation, 🐛 Report Issues and 💬 Discussions

Made with ❤️ by the dbterd community

Release files for dbterd 1.31.0

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

Source distribution (sdist)

Source distribution for dbterd 1.31.0
File	Size	Uploaded
dbterd-1.31.0.tar.gz	67.6 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dbterd 1.31.0
File	Interpreter	ABI	Platform	Reset
dbterd-1.31.0-py3-none-any.whl 87.1 kB Sep 6, 2026	Python 3	none	any	Details

Total release size: 154.7 kB

Release files / dbterd-1.31.0.tar.gz

Download URL	dbterd-1.31.0.tar.gz
Size	67.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`3b9305a4ce05d8845657318a6edf1bce700144138b8382fe9c2250432f5bc047`
BLAKE2b-256 checksum How to use checksums	`0a8863ab4d15df32ed293ea0ea3d32bf443fe0b9d98daf8bb264d06c309fa8c5`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/datnguye/dbterd
Publishing commit: github.com/datnguye/dbterd/tree/e7783aaef708ad1c765c9ce1f44def9ebabba2c7

Workflow

Publishing configuration: github.com/datnguye/dbterd/blob/e7783aaef708ad1c765c9ce1f44def9ebabba2c7/.github/workflows/pypi-publish.yml
Publishing logs: github.com/datnguye/dbterd/actions/runs/34019732213/attempts/1

Artifact

Subject: dbterd-1.31.0.tar.gz
SHA-256 checksum: 3b9305a4ce05d8845657318a6edf1bce700144138b8382fe9c2250432f5bc047 Verifying attestations

Release files / dbterd-1.31.0-py3-none-any.whl

Download URL	dbterd-1.31.0-py3-none-any.whl
Size	87.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f0bbdc587022fa7b8ca493d7a2a0473450744b60fd3430587d5718ebcf7d2d9b`
BLAKE2b-256 checksum How to use checksums	`b4e8c06456cda1ca94fc123718a23771b9941e78691ad5cb968bb601a254126c`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/datnguye/dbterd
Publishing commit: github.com/datnguye/dbterd/tree/e7783aaef708ad1c765c9ce1f44def9ebabba2c7

Workflow

Publishing configuration: github.com/datnguye/dbterd/blob/e7783aaef708ad1c765c9ce1f44def9ebabba2c7/.github/workflows/pypi-publish.yml
Publishing logs: github.com/datnguye/dbterd/actions/runs/34019732213/attempts/1

Artifact

Subject: dbterd-1.31.0-py3-none-any.whl
SHA-256 checksum: f0bbdc587022fa7b8ca493d7a2a0473450744b60fd3430587d5718ebcf7d2d9b Verifying attestations