CLI Reference (dbterd)¶

Run dbterd --help or dbterd -h to see the basic guideline for CLI Reference.

Sample Datasets¶

The project includes several sample datasets in the samples/ directory that you can use to test and explore the CLI commands:

samples/jaffle-shop/: A simple dbt artifacts with customers, orders, and payments models
samples/dbtresto/: A more complex artifacts with dimension and fact tables for analysis
samples/dbt-constraints/: Demonstrates using constraints for relationships
samples/facebookad/, samples/fivetranlog/, samples/shopify/: Additional sample artifacts

The examples below show how to use these sample datasets with dbterd commands.

dbterd -h Usage: dbterd [OPTIONS] COMMAND [ARGS]...

Tools for producing diagram-as-code from dbt artifacts

Options:
--version Show the version and exit.
-h, --help Show this message and exit.

Commands:
debug Inspect the hidden magics
run Generate ERD file from reading dbt artifact files
run-metadata Generate ERD file from reading Discovery API (dbt Cloud)

dbterd run¶

Command to generate diagram-as-a-code file from dbt artifact files, optionally downloading from Administrative API (dbt Cloud).

Examples:

CLI (with samples)CLI (within dbt project)--help (-h)

# Generate DBML ERD from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop

# Generate Mermaid ERD from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop --target mermaid

# Generate D2 ERD from dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto --target d2

# Generate GraphViz ERD without columns
dbterd run --artifacts-dir ./samples/dbtresto --target graphviz --omit-columns

# Generate artifacts first
dbt docs generate

# Generate ERD in your preferred format
dbterd run [-t dbml or -t mermaid]

Usage: dbterd run [OPTIONS]

Run the convert

Options:
    -ad, --artifacts-dir TEXT     Specified the full path to dbt artifacts path
                                    which known as /target directory  [default:
                                    C:\Users\DAT\Documents\Sources\dbterd\target]
    -o, --output TEXT             Output the result file. Default to the same
                                    target dir  [default:
                                    C:\Users\DAT\Documents\Sources\dbterd\target]
    -s, --select TEXT             Selecttion criteria
    -ns, --exclude TEXT           Exclusion criteria
    -t, --target TEXT             Target to the diagram-as-code platform
                                    [default: dbml]
    -a, --algo TEXT               Specified algorithm in the way to detect
                                    diagram connectors  [default:
                                    test_relationship]
    -mv, --manifest-version TEXT  Specified dbt manifest.json version
    -cv, --catalog-version TEXT   Specified dbt catalog.json version
    -rt, --resource-type TEXT     Specified dbt resource type(seed, model,
                                    source, snapshot),default:model, use examples,
                                    -rt model -rt source
    --omit-columns                Flag to omit columns in diagram. Currently
                                    only mermaid is supported
    -h, --help                    Show this message and exit.

dbterd run --select (-s)¶

Selection criteria.

Select all dbt models if not specified, supports multiple options

Rules:

By name: model name starts with input string
By exact: exact model name, formed as exact:model.package.name
By schema: schema name starts with an input string, formed as schema:<your_schema_name>
By wildcard: model name matches to a wildcard pattern, formed as wildcard:<your_wildcard>
By exposure: exposure name, exact match

Examples:

CLI (by name)CLI (by exact name)CLI (by schema)CLI (by wildcard)CLI (by exposure)

dbterd run -s "model.package.partital_name"

# Example with jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop -s "model.jaffle_shop.order"

dbterd run -s "exact:model.package.name"

# Example with jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop -s "exact:model.jaffle_shop.orders"

dbterd run -s "schema:my_schema_name"

# Example with dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto -s "schema:dbt_resto"

dbterd run -s "wildcard:*xyz"

# Example with dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto -s "wildcard:*fact_*"

dbterd run -s "exposure:my_exposure_name"

`AND` and `OR` logic¶

AND logic is applied to a single selection split by comma (,)
OR logic is applied to 2+ selection

Examples:

ANDOR

# All models belong to 'abc' schema AND also need to match the pattern of '*xyz.*'
dbterd run -s schema:abc,wildcard:*xyz.*

# All models belong to 'abc' schema, OR match to the pattern of '*xyz.*'
dbterd run -s schema:abc -s wildcard:*xyz.*

dbterd run --exclude (-ns)¶

Exclusion criteria. Rules are the same as Selection Criteria.

Do not exclude any dbt models if not specified, supports multiple options

Examples:

CLICLI (long style)

dbterd run -ns 'model.package_name.table'

dbterd run --exclude 'model.package_name.table'

dbterd run --artifacts-dir (-ad)¶

Configure the path to directory containing dbt artifact files.

It will take the the nested /target directory of --dbt-project-dir if not specified.

Default to the current directory's /target if both this option and --dbt-project-dir option are not specified

Examples:

CLICLI (long style)

dbterd run -ad "./target"

dbterd run --artifacts-dir "./target"

dbterd run --output (-o)¶

Configure the path to directory containing the output diagram file.

Default to ./target

Examples:

CLICLI (long style)

dbterd run -o "./target"

dbterd run --output "./target"

dbterd run --output-file-name (-ofn)¶

Configure the output file name

Default to output.{modulename} which is defined in the target module

Examples:

CLICLI (long style)

dbterd run -ofn "erd.dbml"

dbterd run --output-file-name "erd.dbml"

dbterd run --target (-t)¶

Default to dbml

Supported target, please visit Generate the Targets

Examples:

CLISample-specific examplesCLI (long style)

dbterd run -t dbml
dbterd run -t mermaid
dbterd run -t d2
dbterd run -t graphviz
dbterd run -t plantuml
dbterd run -t drawdb

# Generate DBML output for jaffle-shop
dbterd run --artifacts-dir ./samples/jaffle-shop -t dbml

# Generate Mermaid ERD for dbtresto
dbterd run --artifacts-dir ./samples/dbtresto -t mermaid

# Generate D2 diagram for dbtresto
dbterd run --artifacts-dir ./samples/dbtresto -t d2

# Generate GraphViz output for jaffle-shop
dbterd run --artifacts-dir ./samples/jaffle-shop -t graphviz

dbterd run --target dbml

dbterd run --algo (-a)¶

Specified algorithm in the way to detect diagram connectors

Check the docs 📖

Supported ones:

test_relationship: Looking for all relationship tests to understand the ERs
semantic: Looking for all semantic models' entities (primary & foreign) to understand the ERs

In the advanced use case of test_relationship, the test name can be configurable by following syntax:

{algorithm_name}:(name:{contains_test_name}|c_from:{referencing_column_name}|c_to:{referenced_column_name})

In the above:

algorithm_name (Mandatory): test_relationship or semantic
contains_test_name: Configure the test name (detected with contains logic). Default to relationship
c_from: Configure the test metadata attribute (1) for the foreign key column name(s). If (1)'s value is multiple columns, it will concat them all with _and wording > NOTE: It always looking at the column_name attribute firstly
c_to: Configure the test metadata attribute (2) for the referenced column name(s). If (2)'s value is multiple columns, it will concat them all with _and wording. Default to field

For example, if you would use dbt-constraints package

The dbt-constraints package is using different name of test which is close to the constraint names, in this case, you would need to customize the input string here:

dbterd run \
--algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

Examples:

CLI (test_relationship)CLI (semantic)CLI (long style)Use foreign_key test

dbterd run -a test_relationship

# Example with jaffle-shop sample (using test_relationship algorithm)
dbterd run --artifacts-dir ./samples/jaffle-shop -a test_relationship -t mermaid

dbterd run -a semantic

# Example with dbtresto sample (using semantic algorithm)
dbterd run --artifacts-dir ./samples/dbtresto -a semantic -t d2

dbterd run --algo test_relationship

dbterd run --algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

# Example with dbt-constraints sample (using foreign_key test)
dbterd run --artifacts-dir ./samples/dbt-constraints -a "test_relationship:(name:foreign_key)" -t mermaid

dbterd run --omit-columns¶

Flag to omit columns in diagram. Currently only mermaid is supported

Default to False

Examples:

CLI

dbterd run --target mermaid --omit-columns

# Example with dbtresto sample (omitting columns for a cleaner diagram)
dbterd run --artifacts-dir ./samples/dbtresto --target mermaid --omit-columns

dbterd run --manifest-version (-mv)¶

Specified dbt manifest.json version

Auto detect if not specified

Examples:

CLICLI (long style)

dbterd run --manifest-version 7

dbterd run -mv 7

dbterd run --catalog-version (-cv)¶

Specified dbt catalog.json version

Auto detect if not specified

Examples:

CLICLI (long style)

dbterd run --catalog-version 7

dbterd run -cv 7

dbterd run --resource-type (-rt)¶

Specified dbt resource type(seed, model, source, snapshot).

Default to ["model"], supports multiple options

Examples:

CLICLI (long style)

dbterd run -rt model -rt source

dbterd run --resource-type model

dbterd run --dbt¶

Flag to indicate the Selection to follow dbt's one leveraging Programmatic Invocation

Default to False

Examples:

CLI (use dbt selection)CLI (use dbterd selection)

dbterd run -s +something --dbt
# select 'something' and the upstream

dbterd run -s something
# select starts with 'something'

dbterd run --dbt --dbt-auto-artifact¶

Flag to indicate force running dbt docs generate to the targeted project in order to produce the dbt artifact files.

This option have to be enabled together with --dbt option, and will override the value of --artifacts-dir to be using the /target dir of the value of --dbt-project-dir.

Default to False

Examples:

CLI

dbterd run -s +something --dbt --dbt-auto-artifacts

dbterd run --dbt-project-dir (-dpd)¶

Specified dbt project directory path

You should specified this option if your CWD is not the dbt project dir, and normally used with --dbt enabled. It will take the value of --artifacts-dir if not specified.

Default to the current directory if both this option and --artifacts-dir option are not specified

Examples:

CLI

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --dbt-target (-dt)¶

Specified dbt target name

Probably used with --dbt enabled.

Default to the dbt's profile configuration

Examples:

CLI

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt --dbt-target prod
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project using target name 'prod'
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --entity-name-format (-enf)¶

Decide how the table name is generated on the ERD.

By default, the table name is the dbt node name (resource_type.package_name.model_name).

Currently, it supports the following keys in the format:

resource.package.model (by default)
database.schema.table
Or any other partial forms e.g. schema.table, resource.model

Examples:

CLISample-specific examples

dbterd run --entity-name-format resource.package.model # by default
dbterd run --entity-name-format database.schema.table # with fqn of the physical tables
dbterd run --entity-name-format schema.table # with schema.table only
dbterd run --entity-name-format table # with table name only

# Generate ERD with simplified entity names from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop --entity-name-format schema.table -t mermaid

# Generate ERD with table names only from dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto --entity-name-format table -t d2

dbterd run --omit-entity-name-quotes¶

Flag to omit the double quotes in the generated entity name. Currently only dbml is supported.

Default to False

Enabled it to allow dbdocs to recognize the schemas and display them as grouping:

With quotes:

dbdocs-enf-with-quotes

Without quotes:

dbdocs-enf-without-quotes

⚠️ As of 2024 June: DBML doesn't support nested schema in the entity name which means 'database.schema.table' won't be allowed, but 'schema.table' does!

Examples:

CLI

dbterd run --entity-name-format resource.package.model --omit-entity-name-quotes # ❌
dbterd run --entity-name-format database.schema.table --omit-entity-name-quotes # ❌
dbterd run --entity-name-format schema.table --omit-entity-name-quotes # ✅

dbterd run --dbt-cloud¶

Decide to download artifact files from dbt Cloud Job Run instead of compiling locally.

Check Download artifacts from a Job Run for more details.

Examples:

CLI

dbterd run --dbt-cloud
dbterd run --dbt-cloud --select wildcard:*transaction*

dbterd run-metadata¶

Command to generate diagram-as-a-code file by connecting to dbt Cloud Discovery API using GraphQL connection.

Check this guideline for more details.

Examples:

CLIBasic usage

# Generate DBML ERD from dbt Cloud environment
dbterd run-metadata --dbt-cloud-environment-id 123456 --dbt-cloud-service-token your_token

# Generate Mermaid ERD from dbt Cloud with specific models
dbterd run-metadata --target mermaid --select model.project.customers --dbt-cloud-environment-id 123456

# Generate D2 ERD with custom query file
dbterd run-metadata --target d2 --dbt-cloud-environment-id 123456 --dbt-cloud-query-file-path ./my_query.gql

dbterd run-metadata [-t dbml or -t mermaid]

dbterd debug¶

Shows hidden configured values, which will help us to see what configs are passed into and how they are evaluated to be used.

Examples:

CLIOutput

# Show debug information for a run command
dbterd debug --artifacts-dir ./samples/jaffle-shop

# Show debug information for a run-metadata command
dbterd debug --dbt-cloud-environment-id 123456

2023-09-08 16:43:45,066 - dbterd - INFO - Run with dbterd==1.0.0 (main.py:54)
2023-09-08 16:43:45,071 - dbterd - INFO - **Arguments used** (main.py:63)
2023-09-08 16:43:45,073 - dbterd - DEBUG - {
    "artifacts_dir": "",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "",
    "dbt_target": null
} (main.py:64)
2023-09-08 16:43:45,079 - dbterd - INFO - **Arguments evaluated** (main.py:65)
2023-09-08 16:43:45,081 - dbterd - INFO - Using dbt artifact dir at: C:\Users\DAT\Documents\Sources\dbterd\target (base.py:41)
2023-09-08 16:43:45,082 - dbterd - INFO - Using dbt project  dir at: C:\Users\DAT\Documents\Sources\dbterd (base.py:42)
2023-09-08 16:43:45,084 - dbterd - DEBUG - {
    "artifacts_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd",
    "dbt_target": null
} (main.py:66)

CLI Reference (dbterd)¶

Sample Datasets¶

dbterd run¶

dbterd run --select (-s)¶

AND and OR logic¶

dbterd run --exclude (-ns)¶

dbterd run --artifacts-dir (-ad)¶

dbterd run --output (-o)¶

dbterd run --output-file-name (-ofn)¶

dbterd run --target (-t)¶

dbterd run --algo (-a)¶

dbterd run --omit-columns¶

dbterd run --manifest-version (-mv)¶

dbterd run --catalog-version (-cv)¶

dbterd run --resource-type (-rt)¶

dbterd run --dbt¶

dbterd run --dbt --dbt-auto-artifact¶

dbterd run --dbt-project-dir (-dpd)¶

dbterd run --dbt-target (-dt)¶

dbterd run --entity-name-format (-enf)¶

dbterd run --omit-entity-name-quotes¶

dbterd run --dbt-cloud¶

dbterd run-metadata¶

dbterd debug¶

`AND` and `OR` logic¶