Configuration Files¶

dbterd supports configuration files to streamline your workflow and reduce the need for repetitive CLI arguments. Think of it as your ERD generation control center – set it once, use it everywhere!

Supported Configuration Files¶

dbterd automatically discovers configuration files in your current directory:

1. .dbterd.yml - YAML configuration file (recommended for most users)
2. pyproject.toml - TOML configuration with [tool.dbterd] section (great for Python projects)

Quick Start¶

Initialize Configuration¶

The easiest way to get started is using the dbterd init command:

This creates a .dbterd.yml file with all available options documented and ready to customize.

Available templates:

dbterd init [--template dbt-core]

dbterd init --template dbt-cloud

dbterd init --force

Configuration File Examples¶

YAML Configuration (.dbterd.yml)¶

Here's a practical example for a dbt Core project:

# Output Settings
target: mermaid
output: ./docs/erd
output-file-name: schema.mmd

# Selection & Filtering
select:
  - fct_*
  - dim_*
exclude:
  - stg_*

# Resource Types
resource-type:
  - model
  - source

# Relationship Detection
algo: test_relationship

# Entity Naming
entity-name-format: schema.table
omit-entity-name-quotes: false
omit-columns: false

# dbt Artifact Settings
artifacts-dir: ./target
bypass-validation: true

# dbt Project Settings (if using --dbt flag)
dbt: false
dbt-project-dir: .
dbt-auto-artifacts: false

TOML Configuration (pyproject.toml)¶

Add dbterd configuration to your existing pyproject.toml:

[tool.dbterd]
target = "mermaid"
output = "./docs/erd"
output-file-name = "schema.mmd"

select = [
    "fct_*",
    "dim_*"
]
exclude = ["stg_*"]

resource-type = ["model", "source"]
algo = "test_relationship"

entity-name-format = "schema.table"
omit-entity-name-quotes = false
omit-columns = false

artifacts-dir = "./target"
bypass-validation = true

dbt = false
dbt-project-dir = "."
dbt-auto-artifacts = false

dbt Cloud Configuration¶

For projects using dbt Cloud:

# Output Settings
target: dbml
output: ./target

# dbt Cloud Settings
dbt-cloud: true
dbt-cloud-host-url: cloud.getdbt.com
dbt-cloud-account-id: "12345"
dbt-cloud-job-id: "67890"
# Note: Store service-token in environment variable DBTERD_DBT_CLOUD_SERVICE_TOKEN
dbt-cloud-api-version: v2

# Selection
select:
  - wildcard:*transaction*

# Resource Types
resource-type:
  - model

[tool.dbterd]
target = "dbml"
output = "./target"
dbt-cloud = true
dbt-cloud-host-url = "cloud.getdbt.com"
dbt-cloud-account-id = "12345"
dbt-cloud-job-id = "67890"
# Note: Store service-token in environment variable DBTERD_DBT_CLOUD_SERVICE_TOKEN
dbt-cloud-api-version = "v2"

select = ["wildcard:*transaction*"]
resource-type = ["model"]

export DBTERD_DBT_CLOUD_SERVICE_TOKEN="your_token_here"

Available Configuration Options¶

All CLI parameters can be configured in files. Here's the complete reference:

Output Settings¶

Selection & Filtering¶

Relationship Detection¶

Entity Naming¶

Artifact Settings¶

dbt Project Settings¶

dbt Cloud Settings¶

export DBTERD_TARGET=mermaid
export DBTERD_OUTPUT=./my-docs

Usage Patterns¶

Override Config with CLI Arguments¶

Configuration files provide defaults, but CLI arguments always take precedence:

# Config says target: dbml
# CLI overrides to mermaid
dbterd run --target mermaid

Multiple Environments¶

Use different config files for different environments:

# .dbterd.dev.yml
target: mermaid
artifacts-dir: ./target
select:
  - "*"

# Use explicitly
dbterd run  # Uses default config if exists

# .dbterd.prod.yml
target: dbml
artifacts-dir: ./target
select:
  - fct_*
  - dim_*
exclude:
  - stg_*

CI/CD Integration¶

Configuration files work great in CI/CD pipelines:

# GitHub Actions example
- name: Generate ERD
  run: |
    dbterd run
  env:
    DBTERD_DBT_CLOUD_SERVICE_TOKEN: ${{ secrets.DBT_CLOUD_TOKEN }}

The config file provides stable defaults while sensitive values come from secrets.

Auto-Detection Features¶

Artifact Version Detection¶

dbterd now automatically detects manifest and catalog versions from the metadata.dbt_schema_version field:

# No need to specify versions manually!
artifacts-dir: ./target
# manifest-version: 12  # Auto-detected
# catalog-version: 1    # Auto-detected

This means you rarely need to specify --manifest-version or --catalog-version anymore – dbterd figures it out for you!

Graceful Fallback¶

If no configuration file exists, dbterd falls back to CLI defaults gracefully. This means:

• Existing CLI workflows continue to work unchanged
• You can adopt config files incrementally
• No breaking changes to existing scripts

Key Naming Convention¶

Configuration files use kebab-case for keys (e.g., artifacts-dir, dbt-cloud), which automatically converts to the snake_case used internally by Python.

Both styles work in YAML/TOML:

artifacts-dir: ./target
dbt-project-dir: .

artifacts_dir: ./target
dbt_project_dir: .

Troubleshooting¶

Config File Not Found¶

If you create a config file but dbterd doesn't use it:

1. Ensure the file is in your current working directory
2. For pyproject.toml, verify the [tool.dbterd] section exists
3. Check file permissions (must be readable)

Invalid YAML/TOML Syntax¶

If you see parsing errors:

Configuration error: Invalid YAML in .dbterd.yml:
while parsing a block mapping

• Validate your YAML syntax using a linter
• Ensure proper indentation (YAML is whitespace-sensitive)
• Check for missing colons or quotes

Config Not Taking Effect¶

If your config seems ignored:

1. CLI arguments override config files – check your command
2. Environment variables override config files – check env | grep DBTERD
3. Use dbterd debug to see evaluated configuration values

Python < 3.11 TOML Support¶

For Python versions below 3.11, install the tomli package:

pip install tomli

Otherwise, you'll see:

TOML support requires 'tomli' package for Python < 3.11

Best Practices¶

1. Use .dbterd.yml for project defaults - Check it into version control so your team shares the same configuration
2. Store secrets in environment variables - Never commit tokens or credentials
3. Override with CLI for one-off changes - No need to edit the config for quick experiments
4. Document your configuration - Use YAML comments to explain why certain options are set
5. Start with dbterd init - Let dbterd generate a well-documented template for you

Learn More¶

• CLI Reference - Complete CLI documentation
• Choose the Parser - Understanding relationship detection algorithms
• dbt Cloud Integration - Using dbterd with dbt Cloud