# dbt-labs/dbt-snowflake architecture

> Architecture diagram of the GitHub repository dbt-labs/dbt-snowflake, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dbt-labs/dbt-snowflake
- Repository: https://github.com/dbt-labs/dbt-snowflake

## Overview

##### Project type and purpose
- This is an open-source adapter plugin for the dbt core framework.
- It implements the Snowflake adapter interface so that dbt can compile models into Snowflake-compatible SQL, connect to Snowflake, run queries, and manage objects.
- Key indicators:
– `dbt/adapters/snowflake` Python package
– `dbt/include/snowflake` macros and project config
– CI/CD workflows, Dockerfiles, tests for adapter functionality

##### File structure
- Top-level directories:
– `dbt/adapters/snowflake`: core adapter implementation (authentication, connection, SQL compilation, relation & cursor handling)
– `dbt/include/snowflake`: pre-built macros (materializations, grants, relations) and sample `dbt_project.yml`
– `docker`: Dockerfiles for development & testing inside containers
– `scripts`: helper scripts for release and token refresh
– `tests`: extensive functional & unit tests validating adapter behavior against Snowflake
– `.github/workflows`: CI/CD pipelines to lint, test, release adapter packages
- Config files:
– `pyproject.toml` & `hatch.toml` for Python packaging
– `.pre-commit-config.yaml` for linting
– `changie.yaml` for automated changelogs

##### README (and CONTRIBUTING, CHANGELOG)
- README simply points to the new monorepo location (`dbt-labs/dbt-adapters`), confirming this is a single adapter.

##### Main components
a. dbt Core CLI Layer
– The entry point where users run `dbt run`, `dbt compile`, etc.
– Loads `dbt-snowflake` plugin via Python entry points.

b. Adapter Plugin Layer
– Package: `dbt/adapters/snowflake`
– Subcomponents:
- Authentication (OAuth, key pair, JWT)
- Connection management (Snowflake Python Connector)
- SQL compilation overrides (relation, column, constant rendering)
- Relation & record classes (cursor, handle)
– Exposes the standard Adapter interface to dbt core.

c. Macro Library
– Folder: `dbt/include/snowflake/macros`
– Materializations (table, incremental, snapshot)
– Grant management macros
– Utility macros for type casting, escaping, optional filters

d. Snowflake Data Warehouse (External Service)
– The actual Snowflake account, databases, schemas, and tables
– Receives compiled SQL from adapter, executes, returns results

e. Development & CI/CD
– Docker build + test containers (`docker/dev.Dockerfile`, `docker/test.sh`)
– GitHub workflows for linting, unit and functional tests across adapter versions
– Release pipelines generating Python wheels

##### Relationships & interactions
1. CLI invokes adapter entry point →
2. Adapter compiles Jinja models using macro library →
3. Adapter opens connection to Snowflake →
4. Adapter sends SQL commands →
5. Snowflake executes and returns results →
6. Adapter processes results → CLI displays to user
- CI/CD flow:
– Push code → GitHub actions → Docker test environment → run tests → build & publish wheel

##### Architectural patterns & principles
- Plugin-based modular architecture: adapter implements common interface for dbt core
- Layered design: CLI layer → Adapter core → Macro library → External Database
- Test isolation: unit tests mock connector; functional tests run against real Snowflake or emulator

##### Technologies & frameworks
- Python 3.x
- Jinja templating (for SQL generation)
- Snowflake Python Connector
- Hatch / pyproject.toml for packaging
- Docker for isolated development/test environments
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "User Interaction"
        CLI["dbt Core CLI"]:::code
    end

    subgraph "Adapter Plugin Layer"
        Auth["Authentication"]:::code
        Connection["Connection Management"]:::code
        subgraph "SQL Compilation Overrides"
            Impl["impl.py"]:::code
            Column["column.py"]:::code
            Constants["constants.py"]:::code
            Relation["relation.py"]:::code
        end
        subgraph "Relation & Record Classes"
            Handle["handle.py"]:::code
            Cursor["cursor.py"]:::code
            SFQID["sfqid.py"]:::code
            SQLState["sqlstate.py"]:::code
        end
    end

    subgraph "Macro Library"
        Macros["snowflake/macros"]:::code
        ProjectConfig["dbt_project.yml & profile_template.yml"]:::code
    end

    subgraph "Snowflake Data Warehouse"
        Snowflake[(Snowflake)]:::external
    end

    subgraph "Dev & CI/CD"
        DockerEnv["docker/dev.Dockerfile & test.sh"]:::ci
        GitHubActions[".github/workflows"]:::ci
        Scripts["scripts/*.sh & *.py"]:::ci
    end

    subgraph "Test Harness"
        FunctionalTests["tests/functional"]:::code
        UnitTests["tests/unit"]:::code
    end

    %% Data Flow
    CLI -->|"loads plugin"| Auth
    CLI -->|"loads plugin"| Connection
    CLI -->|"loads plugin"| Impl
    Auth --> Connection
    Connection --> Snowflake
    Impl --> Snowflake
    Column --> Impl
    Constants --> Impl
    Relation --> Impl
    Handle --> Connection
    Cursor --> Connection
    SFQID --> Cursor
    SQLState --> Cursor
    Impl --> Macros
    Macros -->|"SQL Templates"| Impl
    Snowflake -->|"results"| CLI

    %% CI/CD Flow
    GitHubActions --> DockerEnv
    DockerEnv --> FunctionalTests
    DockerEnv --> UnitTests
    FunctionalTests --> Scripts
    UnitTests --> Scripts

    %% Click Events
    click CLI "https://github.com/dbt-labs/dbt-snowflake/blob/main/pyproject.toml"
    click Auth "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/auth.py"
    click Connection "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/connections.py"
    click Impl "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/impl.py"
    click Column "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/column.py"
    click Constants "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/constants.py"
    click Relation "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/relation.py"
    click Handle "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/record/handle.py"
    click Cursor "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/record/cursor/cursor.py"
    click SFQID "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/record/cursor/sfqid.py"
    click SQLState "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/record/cursor/sqlstate.py"
    click Macros "https://github.com/dbt-labs/dbt-snowflake/tree/main/dbt/include/snowflake/macros"
    click ProjectConfig "https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/include/snowflake/dbt_project.yml"
    click DockerEnv "https://github.com/dbt-labs/dbt-snowflake/blob/main/docker/dev.Dockerfile"
    click GitHubActions "https://github.com/dbt-labs/dbt-snowflake/tree/main/.github/workflows"
    click Scripts "https://github.com/dbt-labs/dbt-snowflake/blob/main/scripts/build-dist.sh"
    click FunctionalTests "https://github.com/dbt-labs/dbt-snowflake/tree/main/tests/functional"
    click UnitTests "https://github.com/dbt-labs/dbt-snowflake/tree/main/tests/unit"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#4A90E2,color:#000
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef ci fill:#FFEFD5,stroke:#CD853F,color:#000
```
