Adapter Class Hierarchy

Relevant source files

The following files were used as context for generating this wiki page:

• dbt-adapters/src/dbt/adapters/base/impl.py
• dbt-adapters/src/dbt/adapters/sql/impl.py
• dbt-adapters/src/dbt/adapters/base/plugin.py
• dbt-adapters/src/dbt/adapters/protocol.py
• dbt-adapters/src/dbt/adapters/factory.py
• CLAUDE.md

The dbt adapter system is built on a structured hierarchy of classes that define how dbt interacts with different database platforms. This hierarchy ensures a consistent interface for dbt-core while allowing platform-specific implementations for connections, relation handling, and SQL generation.

At the core of this system are two primary adapter types: the BaseAdapter, which defines the mandatory functionality for any adapter, and the SQLAdapter, which provides a specialized foundation for SQL-based data warehouses. These classes work in conjunction with protocols and factory managers to register and instantiate the correct adapter based on user configuration.

Sources: dbt-adapters/README.md, CLAUDE.md:27-39

Core Inheritance Structure

The inheritance tree is designed to move from abstract protocols to concrete, platform-specific implementations.

1. AdapterProtocol: A Python Protocol that defines the required interface (methods and attributes) that any adapter class must satisfy.
2. BaseAdapter: The abstract base class that implements the AdapterProtocol. it scaffolds methods for communication between dbt and the database.
3. SQLAdapter: Inherits from BaseAdapter and updates default implementations to work with standard SQL-based platforms.
4. Concrete Adapters: Platform-specific classes (e.g., PostgresAdapter, BigQueryAdapter) that inherit from either SQLAdapter or BaseAdapter.

Adapter Class Diagram

The following diagram illustrates the relationship between the base framework classes and the specialized adapters.

Key Components and Responsibilities

Each level of the hierarchy takes on specific responsibilities to support dbt's execution model.

Component	Responsibility	Relevant Files
BaseAdapter	Abstract base providing cache management, macro resolution, and foundational connection handling.	base/impl.py
SQLAdapter	Implements SQL-specific logic such as DDL operations (drop, rename) and SQL connection patterns.	sql/impl.py
ConnectionManager	Manages thread-safe connection pooling and interactions with the database driver.	base/connections.py
BaseRelation	Represents a database object (table/view) and handles identifier quoting/formatting.	base/relation.py

Sources: dbt-adapters/README.md:15-60, CLAUDE.md:41-51

Plugin Registration and Factory Management

The AdapterFactory and AdapterPlugin system manage the discovery and instantiation of these classes. When dbt starts, it loads plugins which map a specific adapter type (e.g., postgres) to its implementation classes.

The Loading Flow

1. load_plugin(name): Imports the adapter module and retrieves the Plugin object.
2. AdapterPlugin: Holds references to the Adapter class, Credentials class, and dependency chains.
3. register_adapter(): Instantiates the adapter class and stores it in the FACTORY container.

Implementation Patterns

Macro Accessibility

Methods in the adapter hierarchy that need to be callable from Jinja macros are marked with the @available decorator. This is defined in dbt.adapters.base.meta.

# Example from dbt-adapters/src/dbt/adapters/base/impl.py
from dbt.adapters.base.meta import available

class BaseAdapter(AdapterProtocol):
    @available
    def get_columns_in_relation(self, relation):
        # Implementation logic
        pass

Sources: CLAUDE.md:50, AGENTS.md:73-81

Capability Declaration

Adapters declare their support for specific dbt features (like Snapshot or Microbatch) using a CapabilityDict. This allows the core logic to adapt its behavior based on the specific capabilities of the underlying database.

Sources: CLAUDE.md:52, AGENTS.md:83-89

Summary

The Adapter Class Hierarchy provides a robust, extensible framework for supporting diverse data platforms. By separating general adapter logic (BaseAdapter) from SQL-specific patterns (SQLAdapter), the architecture allows new adapters to be implemented with minimal boilerplate while maintaining strict adherence to the AdapterProtocol.