dbt-adapters

1.22.9 · active · verified Sat Mar 28

dbt-adapters is a Python library that defines the set of adapter protocols and base functionality crucial for integrating dbt-core with various data platforms. It serves as the foundational interface for developing database-specific dbt adapters. As of its current version 1.22.9, it's an actively developed component within the dbt ecosystem, with a release cadence that is increasingly independent of dbt-core, especially since dbt-core v1.8.

Warnings

breaking Breaking changes in dbt-core v1.8+ for adapter developers. dbt-core and dbt-adapters were decoupled. Adapters should no longer directly import from `dbt-core` and instead rely on interfaces defined in `dbt-adapters` and `dbt-common`. Users must explicitly install `dbt-core` and their specific `dbt-<adapter>` package.
Fix: Adapter maintainers: Refactor imports to use `dbt-adapters` and `dbt-common` interfaces. Users: Always explicitly install `dbt-core` and your desired `dbt-<adapter>` (e.g., `pip install dbt-core dbt-snowflake`).
gotcha Adapter methods like `get_response` and `execute` are expected to return `connection.AdapterResponse` objects, not just strings, since `dbt-core` v1.1. Custom adapters that return strings might face unexpected behavior.
Fix: Adapter maintainers should update method implementations to return `dbt.contracts.connection.AdapterResponse` objects or a subclass thereof.
gotcha Correct configuration of `profiles.yml` is essential. Missing or incorrect entries, or failing to install the corresponding `dbt-<database-adapter>` package, will prevent dbt from connecting to your data warehouse and result in errors like 'Error importing adapter: No module named...'
Fix: Ensure `profiles.yml` is correctly configured with `type` matching your installed adapter (e.g., `type: postgres` for `dbt-postgres`). Verify the specific `dbt-<database-adapter>` package is installed.
deprecated Starting with `dbt-core` v1.10, deprecation warnings are raised for custom inputs, duplicate YAML keys, and unexpected Jinja blocks. While initially warnings, these will become errors in future versions.
Fix: Review and update dbt project configurations and custom macros to eliminate deprecated patterns. Consult dbt-core release notes for specific guidance on addressing warnings.
breaking Changes to dbt artifact schema versions (e.g., manifest.json) require compatible `dbt-core` versions when using state-based functionality (`--state` flag). Mismatched schema versions will cause errors and require concurrent upgrades of dbt orchestrations.
Fix: When upgrading, ensure all dbt environments and state-dependent jobs are updated to compatible `dbt-core` versions simultaneously.

Install

pip install dbt-adapters Install dbt-adapters (for adapter developers)
pip install dbt-core dbt-<your-database-adapter> Recommended: Install dbt-core and a specific adapter (for dbt users)

Imports

BaseAdapter
```
from dbt.adapters.base.impl import BaseAdapter
```
For developers extending the base adapter functionality. End-users typically do not directly import from dbt-adapters Python modules.
SQLAdapter
```
from dbt.adapters.sql.impl import SQLAdapter
```
For developers building SQL-based adapters, inheriting from BaseAdapter. End-users typically do not directly import from dbt-adapters Python modules.
adapter (Jinja context variable)
```
{% do adapter.dispatch('macro_name', 'package_name')(arg1, arg2) %}
```
The primary way dbt users interact with adapter functionality within dbt models (via Jinja macros).

Quickstart

dbt-adapters is a low-level library for building dbt adapters. End-users interact with adapter functionality through dbt-core and specific database adapters. The quickstart below illustrates how a dbt user sets up a project and uses adapter-specific logic via Jinja macros in a SQL model, which leverages the interfaces provided by `dbt-adapters`.

# 1. Install dbt-core and your specific database adapter (e.g., dbt-postgres)
# pip install dbt-core dbt-postgres

# 2. Initialize a dbt project
# dbt init my_dbt_project
# cd my_dbt_project

# 3. Configure your profiles.yml (typically in ~/.dbt/profiles.yml)
# Example profiles.yml content (replace with your database details):
# my_dbt_project:
#   target: dev
#   outputs:
#     dev:
#       type: postgres
#       host: localhost
#       user: myuser
#       password: "{{ env_var('DB_PASSWORD') }}"
#       port: 5432
#       dbname: mydatabase
#       schema: public

# 4. Create a dbt model (e.g., models/my_model.sql)
# Use the 'adapter' object in Jinja to call adapter-specific functionality.
# For instance, to get the current timestamp, which might vary by database dialect:
-- my_model.sql
SELECT
    {{ adapter.dispatch('current_timestamp', 'dbt')() }} as current_time,
    1 as id

view raw JSON →