dbt-snowflake Adapter
Relevant source files
The following files were used as context for generating this wiki page:
The dbt-snowflake adapter is a specialized plugin within the dbt ecosystem that enables dbt to interact with the Snowflake data warehouse. It extends the SQLAdapter base class provided by the dbt-adapters framework and utilizes the snowflake-connector-python to manage connections and execute SQL transformations. As part of a monorepo, it shares a foundational architecture with other first-party adapters while implementing Snowflake-specific features like Dynamic Tables, Iceberg integration, and diverse authentication methods.
Sources: dbt-snowflake/README.md:27-30, CLAUDE.md:144-147, README.md:23-32
Architecture and Components
The adapter is structured to handle Snowflake's unique DDL and metadata requirements. It follows the standard dbt adapter layout, consisting of Python implementation logic and Jinja SQL macros that override default dbt behaviors.
Core Modules
impl.py: Contains the main adapter implementation logic.connections.py: Manages Snowflake-specific connection pooling andCredentials.relation.py: Defines Snowflake relation types (e.g., Dynamic Tables, Iceberg).auth.py: Handles various Snowflake authentication methods including OAuth and Key Pair.relation_configs/: Manages complex configuration states for objects like Dynamic Tables.
Sources: CLAUDE.md:144-149, AGENTS.md:86-94
Dependency Structure
The following diagram illustrates how the Snowflake adapter fits into the broader project dependency chain:
The Snowflake adapter inherits from the base framework and is validated by the shared test suite.
Sources: CLAUDE.md:15-28, AGENTS.md:12-22
Key Features and Configurations
Snowflake supports several advanced materializations and security features that are exposed through dbt configurations.
Materializations
The adapter supports standard dbt materializations (table, view, incremental) along with Snowflake-specific types:
| Feature | Description | Config Option |
|---|---|---|
| Dynamic Tables | Tables that automatically refresh based on a target lag. | materialized='dynamic_table' |
| Iceberg Tables | Open table format support (Built-in or REST). | table_format='iceberg' |
| Transient Tables | Tables that do not have a Fail-safe period. | transient=true |
| Clustering | Defines clustering keys for data layout optimization. | cluster_by=['col1'] |
Sources: CLAUDE.md:151-170, dbt-snowflake/CHANGELOG.md:41-65
Authentication Methods
dbt-snowflake supports a wide array of authentication protocols to accommodate different security requirements:
- Username/Password: Standard credentials.
- Key Pair: Uses private keys (with optional passphrases).
- OAuth: Token-based authentication for integrated environments.
- SSO: External browser-based authentication.
- Workload Identity Federation: Support for OIDC and identity tokens without specific users.
- Programmatic Access Token (PAT): For automated access.
Sources: CLAUDE.md:172-178, dbt-snowflake/CHANGELOG.md:38-40, dbt-snowflake/CHANGELOG.md:174-177
Dynamic Table Management
Dynamic Tables are a core feature of the Snowflake adapter, allowing for declarative data refresh logic. The adapter manages the lifecycle of these tables, including creation, scheduling, and configuration updates.
The adapter compares the existing state of a Dynamic Table against the dbt model configuration to determine if an ALTER or REPLACE is necessary.
Sources: dbt-snowflake/CHANGELOG.md:46-70, CLAUDE.md:154-156
External Catalog Integration
The adapter leverages the dbt-adapters catalog framework to support Snowflake's Iceberg implementation. It supports multiple catalog types for Iceberg tables:
built_in: Snowflake-managed Iceberg tables.iceberg_rest: Integration with external REST-based catalogs (e.g., Glue Catalog Linked Databases).
Catalog Configuration Example
Users define catalog integrations in dbt_project.yml or through model-level configurations:
# dbt_project.yml
catalogs:
- name: my_iceberg_catalog
write_integrations:
- name: my_write_integration
catalog_type: built_in
table_format: iceberg
external_volume: "my_volume"
Sources: CLAUDE.md:253-272, dbt-snowflake/CHANGELOG.md:231-236, dbt-snowflake/CHANGELOG.md:286-292
Development and Testing
Developing the Snowflake adapter requires a local environment setup using hatch.
Common Commands
- Setup:
hatch run setup(installs adapter and dependencies in editable mode). - Unit Tests:
hatch run unit-tests(logic tests not requiring a database). - Integration Tests:
hatch run integration-tests(requirestest.envwith Snowflake credentials).
Sources: AGENTS.md:26-34, CLAUDE.md:37-51
Capabilities Declaration
The adapter explicitly declares its support for specific features via CapabilityDict. This allows dbt-core to optimize execution paths (e.g., using CatalogsV2 for improved metadata discovery).
Sources: CLAUDE.md:124-129, dbt-snowflake/CHANGELOG.md:73-75