https://github.com/datnguye/dbterd
Generate the ERD as a code from dbt artifacts
https://github.com/datnguye/dbterd
cli d2 dbml dbt-cloud dbt-core drawdb erd graphviz mermaid plantuml python-api
Last synced: 19 days ago
JSON representation
Generate the ERD as a code from dbt artifacts
- Host: GitHub
- URL: https://github.com/datnguye/dbterd
- Owner: datnguye
- License: mit
- Created: 2022-06-24T07:35:31.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-21T06:12:10.000Z (about 1 month ago)
- Last Synced: 2026-03-21T19:12:38.754Z (30 days ago)
- Topics: cli, d2, dbml, dbt-cloud, dbt-core, drawdb, erd, graphviz, mermaid, plantuml, python-api
- Language: Python
- Homepage: https://dbterd.datnguyen.de/
- Size: 6.21 MB
- Stars: 305
- Watchers: 7
- Forks: 36
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-dbt - dbterd - CLI to generate DBML file from dbt manifest.json. (Utilities)
- jimsghstars - datnguye/dbterd - Generate the ERD as a code from dbt artifacts (Python)
README
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
[](https://dbterd.datnguyen.de/)
[](https://pypi.org/project/dbterd/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org)
[](https://codecov.io/gh/datnguye/dbterd)
[](https://github.com/datnguye/dbterd)
## 🎯 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](https://docs.getdbt.com/reference/resource-properties/data-tests#relationships)** *(default)* — infers relationships from dbt `relationships` data tests
- **🏛️ [Semantic Entities](https://docs.getdbt.com/docs/build/entities)** (`-a entity_relationship`) — detects relationships via dbt Semantic Layer entity definitions
- **📜 [Model Contract Constraints](https://docs.getdbt.com/docs/collaborate/govern/model-contracts)** (`-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](https://dbterd.datnguyen.de/latest/nav/guide/cli-references.html#dbterd-run-algo-a).
## 🎨 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](https://dbdiagram.io/d)** | Database Markup Language | Interactive web diagrams |
| **[Mermaid](https://mermaid-js.github.io/mermaid-live-editor/)** | Markdown-friendly diagrams | Documentation, GitHub |
| **[PlantUML](https://plantuml.com/ie-diagram)** | Text-based UML | Technical documentation |
| **[GraphViz](https://graphviz.org/)** | DOT graph description | Complex relationship visualization |
| **[D2](https://d2lang.com/)** | Modern diagram scripting | Beautiful, customizable diagrams |
| **[DrawDB](https://drawdb.vercel.app/)** | Web-based database designer | Interactive database design |
🎯 **[Try the Quick Demo](https://dbterd.datnguyen.de/latest/nav/guide/targets/generate-dbml.html)** with DBML format!
## 🚀 Installation
```bash
pip install dbterd --upgrade
```
Verify Installation:
```bash
dbterd --version
```
> [!TIP]
> **For dbt-core users**: It's highly recommended to keep [`dbt-artifacts-parser`](https://github.com/yu-iskw/dbt-artifacts-parser) updated to the latest version to support newer `dbt-core` versions and their [manifest/catalog json schemas](https://schemas.getdbt.com/):
> ```bash
> 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!
```bash
# 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](https://dbterd.datnguyen.de/latest/nav/guide/configuration-file.html).
## 💡 Examples
### CLI Examples
🖱️ Click to explore CLI examples
```bash
# 📊 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**
```python
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**
```python
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:**
```mermaid
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](https://dbterd.datnguyen.de/latest/nav/development/contributing-guide.html)** for detailed information.
**Show your support:**
- ⭐ Star this repository
- 📢 Share on social media
- ✍️ Write a blog post
- ☕ [Buy me a coffee](https://www.buymeacoffee.com/datnguye)
[](https://www.buymeacoffee.com/datnguye)
## 👥 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](https://dbterd.datnguyen.de/), 🐛 [Report Issues](https://github.com/datnguye/dbterd/issues) and 💬 [Discussions](https://github.com/datnguye/dbterd/discussions)
---
**Made with ❤️ by the dbterd community**
---
### Sponsored by GitAds
[](https://gitads.dev/v1/ad-track?source=datnguye/dbterd@github)