dbt-common

1.37.3 · active · verified Sat Mar 28

dbt-common is a Python library that provides shared common utilities used by dbt-core and various dbt adapter implementations. It centralizes functionalities to ensure consistency and efficiency across the dbt ecosystem. The library is actively maintained by dbt Labs, with a current version of 1.37.3, and typically follows the release cadence of `dbt-core` and related adapter packages.

Warnings

breaking Major versions of `dbt-core` (e.g., v1 to v2) may include breaking changes that impact `dbt-common` and its consumers, particularly adapter plugins and custom implementations that rely on dbt's internal Python interfaces. These changes are typically communicated in dbt's release notes for adapter maintainers.
Fix: Refer to the `dbt-core` release notes and migration guides for adapter developers. Update your adapter implementations to align with the new Python interfaces exposed or used by `dbt-common`.
breaking Changes to dbt's metadata interfaces, including artifacts (like `manifest.json`, `catalog.json`) and structured logging, are considered breaking for `dbt-common`'s consumers if fields are deleted, renamed, or their types/defaults change without backward compatibility.
Fix: Ensure your tools or integrations parsing dbt artifacts are updated to handle the new schema versions. Monitor dbt Developer Hub for detailed artifact schema changes.
deprecated The `DBT_` environment variable prefix has been deprecated for custom variables to prevent collisions with dbt's internal variables. New dbt environment variables are now prefixed with `DBT_ENGINE`.
Fix: Update any custom environment variables currently using the `DBT_` prefix to a different, non-colliding prefix, or ensure they do not conflict with dbt's internal `DBT_ENGINE` variables.
gotcha `dbt-common` is a foundational library, not typically intended for direct end-user application development. Its utilities are primarily consumed by `dbt-core` and dbt adapter implementations. Expect minimal direct documentation for independent usage.
Fix: When using dbt, interact primarily with `dbt-core` or specific adapters. If you are developing a dbt adapter or extending `dbt-core`, refer to the `dbt-common` source code and dbt Labs' developer guides for internal API usage.

Install

pip install dbt-common Install latest version

Imports

__version__

import dbt_common; print(dbt_common.__version__)

DbtCommonError

from dbt_common.exceptions import DbtCommonError

Quickstart

This quickstart demonstrates how to import the `dbt_common` library and access its version. It also shows how to import and catch a base exception class, `DbtCommonError`, which is part of its utilities, illustrating basic programmatic interaction. Note that `dbt-common` is primarily an internal utility for `dbt-core` and adapters, so direct end-user application development with it is rare.

import dbt_common
from dbt_common.exceptions import DbtCommonError

print(f"dbt-common version: {dbt_common.__version__}")

try:
    raise DbtCommonError("This is a dbt common error.")
except DbtCommonError as e:
    print(f"Caught expected error: {e}")

view raw JSON →