Adapter Capabilities Framework

Relevant source files

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

• dbt-adapters/src/dbt/adapters/capability.py
• AGENTS.md
• CLAUDE.md
• dbt-adapters/README.md
• dbt-adapters/CHANGELOG.md

The Adapter Capabilities Framework is a structured system within the dbt-adapters ecosystem used to declare and manage the specific features supported by a concrete database adapter. By providing a standardized method for adapters to communicate their technical limits or extended features, dbt-core can optimize execution strategies and provide accurate feedback to users. Sources: dbt-adapters/README.md, CLAUDE.md, AGENTS.md

This framework moves away from hard-coded feature detection by using an enumeration-based registry. Each adapter defines a CapabilityDict that maps a specific Capability to a CapabilitySupport object, which indicates the level of support (e.g., Full, Partial, or None). Sources: AGENTS.md, dbt-adapters/src/dbt/adapters/capability.py

Core Components and Architecture

The framework is built around three primary data structures that define what a capability is, how it is supported, and how those declarations are grouped together.

Capability Enumeration

The Capability enum acts as the registry for all identifiable features an adapter might implement. These range from metadata retrieval optimizations to specific execution strategies like Microbatching. Sources: dbt-adapters/src/dbt/adapters/capability.py

Support Levels

Support for a capability is not binary. The Support enum defines the extent of an adapter's implementation for a given feature:

• Full: The feature is completely supported as intended.
• Partial: The feature is supported with known limitations.
• None: The feature is not supported.
  Sources: dbt-adapters/src/dbt/adapters/capability.py

Architecture Overview

The following diagram illustrates the relationship between the Capability registry and the Adapter implementation.

The diagram shows how a concrete adapter uses a CapabilityDict to map specific Capability keys to CapabilitySupport values. Sources: dbt-adapters/src/dbt/adapters/capability.py, AGENTS.md

Framework Implementation

Adapters implement the framework by defining a private _capabilities attribute using the CapabilityDict class. This allows dbt-core and other framework components to query the adapter's features at runtime. Sources: CLAUDE.md, AGENTS.md

Key Capabilities Registry

Capability	Description
SchemaMetadataByRelations	Ability to fetch schema metadata for specific relations rather than an entire schema.
TableLastModifiedMetadata	Support for retrieving the last modified time of a table from system metadata.
MicrobatchConcurrency	Support for concurrent execution within the Microbatch incremental strategy.
CatalogsV2	Support for the version 2 catalog bridge architecture.
Sources: dbt-adapters/src/dbt/adapters/capability.py, dbt-adapters/CHANGELOG.md

Code Example: Declaring Capabilities

Concrete adapters declare their supported features during class definition.

from dbt.adapters.capability import Capability, CapabilitySupport, CapabilityDict, Support

class MyAdapter(SQLAdapter):
    _capabilities = CapabilityDict({
        Capability.SchemaMetadataByRelations: CapabilitySupport(support=Support.Full),
        Capability.MicrobatchConcurrency: CapabilitySupport(support=Support.Full),
    })

Sources: AGENTS.md

Evolution of Capabilities

The framework is designed to be extensible. New capabilities are added to the Capability enum as dbt introduces new features that require adapter-specific implementation. Sources: dbt-adapters/CHANGELOG.md

Recent Additions

• CatalogsV2: Added to support adapter-owned v2 catalog bridge architecture. Sources: dbt-adapters/CHANGELOG.md: 38-39
• MicrobatchConcurrency: Introduced to gate functionality for microbatch execution strategies. Sources: dbt-adapters/CHANGELOG.md: 339-340
• SchemaMetadataByRelations: Used to optimize metadata lookups, governed by MAX_SCHEMA_METADATA_RELATIONS. Sources: dbt-adapters/CHANGELOG.md: 618-619

Conclusion

The Adapter Capabilities Framework provides the necessary abstraction for dbt-core to remain database-agnostic while still leveraging platform-specific optimizations. By centralizing feature declarations in the CapabilityDict, the framework ensures that developers can easily identify and implement required functionality when building or maintaining dbt adapters. Sources: dbt-adapters/README.md, CLAUDE.md