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, and DrawDB
๐ฏ Entity Relationship Detection¶
dbterd intelligently detects entity relationships through:
- ๐งช Test Relationships (default method)
- ๐๏ธ Semantic Entities (use
-a
option)
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¶
Verify Installation:
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:
๐ก 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
๐ฅ Contributors¶
A huge thanks to our amazing contributors! ๐