<div style="display: flex; align-items: center; justify-content: space-between;"> <div> <h1 style="margin: 0;">dbterd</h1> <p style="margin: 0; font-weight: bold;">Generate ERD-as-a-code from your dbt projects</p> </div> <img src="docs/assets/logo.svg" alt="dbterd logo" width="200" height="80"> </div>

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

🎯 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 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.

🎨 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 |

🎯 Try the Quick Demo with DBML format!

🚀 Installation

pip install dbterd --upgrade

Verify Installation:

dbterd --version

[!TIP] For dbt-core users: It's highly recommended to keep dbt-artifacts-parser updated to the latest version to support newer dbt-core versions and their manifest/catalog json schemas:
pip install dbt-artifacts-parser --upgrade
Note: dbterd now automatically bypasses Pydantic validation errors by default, which helps with compatibility when using newer dbt artifact schemas.

⚙️ 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

<details> <summary>🖱️ <strong>Click to explore CLI examples</strong></summary>

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

</details>

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

Dbterd

Install / Use

README