Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The dbt-adapters project is a monorepo that hosts the v1 generation of dbt adapters. It provides the core framework, shared logic, and official implementations for connecting dbt to various data warehouses and databases. This architecture allows data analysts and engineers to transform data using software engineering practices across different SQL and non-SQL platforms.
Sources: README.md:12-14, README.md:20-30
The repository is structured to separate the base framework from specific adapter implementations and testing utilities. This modular design ensures consistency in how dbt interacts with different backends while allowing for platform-specific optimizations.
Sources: dbt-adapters/README.md:41-55, AGENTS.md:11-20
Project Architecture
The project follows a monorepo structure where each component is an independent Python package. The dependency chain flows from the base framework down to specialized adapters.
This diagram illustrates the hierarchical relationship between the core framework and the various database-specific adapters.
Sources: CLAUDE.md:16-25, AGENTS.md:11-20
Core Components
The system is divided into four primary functional areas that facilitate the integration between dbt-core and the data platform:
| Component | Responsibility | Relevant Files |
|---|---|---|
| Connections | Creating and managing thread-safe connection pooling to storage and compute. | base/connections.py, sql/connections.py |
| Dialect | Translating dbt-core requests into platform-specific SQL actions (DDL/DML). | base/column.py, base/relation.py, global_project/macros/ |
| Relation Caching | Local management of relation metadata and dependencies to optimize performance. | cache.py |
| Integration | Managing the interface, protocols, and plugins between dbt-core and the adapter. | base/impl.py, base/plugin.py, protocol.py |
Sources: dbt-adapters/README.md:30-74
Adapter Types
The framework defines two major adapter categories that serve as the foundation for all concrete implementations:
BaseAdapter
The BaseAdapter (found in dbt-adapters/src/dbt/adapters/base/impl.py) defines the absolute minimum functionality required to work with dbt-core. It includes abstract methods that every concrete adapter must implement, as well as default behaviors for non-platform-specific logic.
Sources: dbt-adapters/README.md:15-19, CLAUDE.md:31-41
SQLAdapter
The SQLAdapter (found in dbt-adapters/src/dbt/adapters/sql/impl.py) inherits from BaseAdapter. it provides specialized implementations tailored for SQL-based platforms, including standard patterns for SQL connection management and common DDL operations.
Sources: dbt-adapters/README.md:21-25, CLAUDE.md:31-41
Development and Testing Workflow
The monorepo utilizes hatch for environment management and changie for changelog automation. Development is typically performed within a specific adapter directory rather than the repository root.
The sequence above shows the standard workflow for contributing changes to any adapter within the repository.
Sources: AGENTS.md:22-54, CONTRIBUTING.md:43-60
Testing Infrastructure
Testing is supported by dbt-tests-adapter, which provides a shared suite of functional tests. Concrete adapters inherit from these base test classes to ensure they meet the standard dbt feature requirements (e.g., materializations, snapshots, and documentation generation).
Sources: AGENTS.md:61-70, CLAUDE.md:63-75
Framework Extension Points
Adapters extend the framework through several mechanisms:
- Macro Overrides: Adapters provide SQL templates in
src/dbt/include/{adapter}/macros/. These typically use the{adapter}__prefix to override global defaults. - Capabilities: Adapters declare supported features (like
SchemaMetadataByRelations) using aCapabilityDict. - External Catalogs: A plugin system in
dbt/adapters/catalogs/allows adapters to support external table formats like Apache Iceberg.
Sources: AGENTS.md:82-113, CLAUDE.md:183-210
Conclusion
The dbt-adapters project serves as the critical bridge between the high-level transformation logic of dbt and the technical realities of various data platforms. By providing a robust base through BaseAdapter and SQLAdapter, it enables a consistent development experience while maintaining the flexibility needed to support diverse database architectures.
Sources: dbt-adapters/README.md:13-25, AGENTS.md:112-115