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

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.

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 entity_relationship) — 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.

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

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

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

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

pip install "artifact-parser[dbt]" --upgrade

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.

# 📊 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

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

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

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

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