Skip to content

dbterd

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

dbterd logo

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

docs PyPI version python-cli License: MIT python codecov

dbterd stars


๐ŸŽฏ Entity Relationship Detection

dbterd intelligently detects entity relationships through:

For detailed configuration options, see our CLI References.

๐ŸŽจ Supported Output Formats

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

๐Ÿš€ Installation

pip install dbterd --upgrade Successfully installed dbterd restart โ†ป

Verify Installation:

dbterd --version

For dbt-core users

It's highly recommended to update dbt-artifacts-parser to the latest version in order to support the newer dbt-core version which would cause to have the new manifest / catalog json schema:

pip install dbt-artifacts-parser --upgrade

๐Ÿ’ก 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 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

๐ŸŽฏ Try the Quick Demo with DBML format!


๐Ÿค Contributing

We welcome contributions! ๐ŸŽ‰

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

buy me a coffee

๐Ÿ‘ฅ Contributors

A huge thanks to our amazing contributors! ๐Ÿ™


**Made with โค๏ธ by the dbterd community**