📊 dbt-model-erd
Automatically generate beautiful entity-relationship diagrams for your dbt models
🎯 What is dbt-model-erd?
dbt-model-erd analyzes your dbt SQL models and YAML schemas to automatically generate interactive ER diagrams showing relationships between fact and dimension tables. No manual diagramming required!
✨ Key Features
- 🖼️ Visual Clarity: Generate clean, professional ER diagrams for your data warehouse
- 🔄 Auto-Detection: Automatically detects relationships between fact and dimension tables
- 📝 Documentation: Embeds diagrams directly in your dbt model documentation
- 🧠 Smart Inference: Intelligently infers primary keys, foreign keys, and column types
- 🛠️ Highly Configurable: Customize every aspect of your diagrams
- 🔒 No External Dependencies: Renders diagrams client-side without requiring Node.js
- 🏎️ CI/CD Friendly: Works seamlessly in continuous integration environments
🚀 Quick Start
Installation
pip install dbt-model-erd
Basic Usage
# Navigate to your dbt project
cd your-dbt-project
# Generate diagrams for fact models
python -m dbt_erd --model-path models/fact
# View the generated diagrams
open assets/img/fact/fact_orders_model.html
What It Does
- Scans your dbt SQL files for
ref()relationships - Reads YAML schemas for column definitions
- Generates Mermaid ER diagrams showing table structures
- Creates interactive HTML files
- Updates your model YAML with diagram links
📖 Documentation
| Document | Description |
|---|---|
| QUICKSTART.md | Get started in 5 minutes with examples |
| TESTING_GUIDE.md | How to test locally before publishing |
| PUBLISHING_GUIDE.md | Complete guide to publish to PyPI |
| CONTRIBUTING.md | Guidelines for contributors |
💡 Example
Your dbt Project
models/fact/fact_orders.sql:
WITH orders AS (
SELECT * FROM {{ source('raw', 'orders') }}
),
customers AS (
SELECT * FROM {{ ref('dim_customer') }}
),
products AS (
SELECT * FROM {{ ref('dim_product') }}
),
final AS (
SELECT
o.order_id,
o.customer_id,
o.product_id,
o.amount
FROM orders o
LEFT JOIN customers c ON o.customer_id = c.customer_id
LEFT JOIN products p ON o.product_id = p.product_id
)
SELECT * FROM final
Generated Diagram
erDiagram
fact_orders {
int order_id PK
int customer_id FK
int product_id FK
float amount
}
dim_customer {
int customer_id PK
string first_name
string last_name
}
dim_product {
int product_id PK
string product_name
float price
}
dim_customer ||--o{ fact_orders : "customer_id"
dim_product ||--o{ fact_orders : "product_id"
🎨 Configuration
Generate Default Config
python -m dbt_erd --output-config my_config.yml
Example Configuration
# Visualization settings
visualization:
max_dimensions: 10
show_columns: true
column_limit: 20
# Mermaid settings
mermaid:
theme: "default" # Options: default, neutral, forest, dark
direction: "LR" # Options: LR (left-right), TB (top-bottom)
outputs:
mmd: true # Generate raw Mermaid source code
html: true # Generate HTML with client-side rendering
# Table styling options
style:
fact_table_fill: "#f5f5f5" # Light gray for fact tables
dimension_table_fill: "#e8f4f8" # Light blue for dimension tables
📁 See examples/ for more configuration options.
🔧 Advanced Usage
Parallel Processing
For large projects with many models:
python -m dbt_erd --model-path models/fact --parallel
Custom Configuration
python -m dbt_erd --model-path models/fact --config advanced_config.yml
Verbose Mode
For debugging:
python -m dbt_erd --model-path models/fact --verbose
CI/CD Integration
Example GitHub Actions workflow:
name: Update ERD Diagrams
on:
push:
branches: [ main ]
paths:
- 'models/**/*.sql'
- 'models/**/*.yml'
jobs:
update-diagrams:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: '3.9'
- name: Install dbt-model-erd
run: pip install dbt-model-erd
- name: Generate ERD diagrams
run: python -m dbt_erd --model-path models/fact
- name: Commit changes
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add assets/
git commit -m "Update ERD diagrams" || echo "No changes"
git push
🖼️ How It Works
Pure Browser-Based Rendering
dbt-model-erd generates diagrams without requiring Node.js or making external API calls:
- Mermaid Source Code (.mmd): Raw diagram definition you can version control
- HTML with Client-Side Rendering (.html): Interactive diagram rendered in the browser
When embedded in dbt docs, you get clickable HTML links to interactive diagrams.
Customizable Table Styling
You can customize the appearance of your diagrams:
- Set different colors for fact and dimension tables
- Choose from different themes (default, neutral, forest, dark)
- Set diagram direction (left-right or top-bottom)
- Control column display limits
Diagram Generation Process
- Analyzes SQL files to find fact and dimension tables based on naming patterns
- Detects relationships between tables by identifying foreign keys
- Generates Mermaid diagram code representing these relationships
- Creates HTML files that render the diagrams client-side
- Updates your model YAML files to include links to the diagrams in dbt docs
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Development Setup
git clone https://github.com/entechlog/dbt-model-erd.git
cd dbt-model-erd
pip install -e ".[dev]"
# Run tests
make test
# Run linting
make lint
# Format code
make format
📊 Project Status
- ✅ Version: 0.1.0 (Beta)
- ✅ Python: 3.8+
- ✅ License: MIT
- ✅ Status: Active Development
Roadmap
- Support for bridge/junction tables
- Enhanced relationship type detection
- Export to PNG/SVG
- Integration with dbt Cloud
- Support for dbt metrics
- Custom Jinja templates
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built with Mermaid.js for diagram rendering
- Inspired by the dbt community's need for better data model visualization
- Thanks to all contributors
📧 Support & Community
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- dbt Slack: #tools-and-integrations
⭐ Star History
If you find this tool helpful, please consider giving it a star on GitHub!
Made with ❤️ for the dbt community
Metadata
Release files for dbt-model-erd 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dbt_model_erd-0.1.1.tar.gz | 46.5 kB | Without provenance | Details for dbt_model_erd-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dbt_model_erd-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for dbt_model_erd-0.1.1-py3-none-any.whl |
Total release size: 68.8 kB
Release files / dbt_model_erd-0.1.1.tar.gz
| Download URL | dbt_model_erd-0.1.1.tar.gz |
|---|---|
| Size | 46.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ce53de1e7ab4f117703626f7dbc65ac5b9b4ee56b65b0749f55909d8716c9c8
|
|
BLAKE2b-256 checksum How to use checksums |
331e50b7bfd5d0bd3e57c8a840dc1509dc780452a8c69249036661e502b47422
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / dbt_model_erd-0.1.1-py3-none-any.whl
| Download URL | dbt_model_erd-0.1.1-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
72ee40a40137a4d9c68be87ff3e481ae1fa71ead0591f3380599b6247be70bd0
|
|
BLAKE2b-256 checksum How to use checksums |
5e3abdaa1b099fab5b3be9203994261726cfc9a0491dc72fe6320dd30760ec14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Security for dbt-model-erd 0.1.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.