dbt-redshift Adapter
Relevant source files
The following files were used as context for generating this wiki page:
The dbt-redshift adapter is a specialized plugin within the dbt ecosystem that enables dbt to interact with Amazon Redshift data warehouses. It is built as an extension of the dbt-postgres adapter, leveraging the underlying PostgreSQL compatibility while implementing Redshift-specific optimizations such as distribution styles, sort keys, and late-binding views.
The adapter manages connection pooling through the redshift-connector library and handles DDL/DML execution for materializations like tables, views, and materialized views. It also supports advanced Redshift features including cross-database Datasharing via SHOW APIs and native column type alterations for VARCHAR and VARBYTE types.
Sources: AGENTS.md:10, CLAUDE.md:143-150, dbt-redshift/pyproject.toml:34
Core Architecture and Inheritance
The Redshift adapter follows a hierarchical inheritance structure within the dbt-adapters monorepo. It specifically extends the PostgresAdapter to reuse SQL dialect commonalities while overriding methods to accommodate Redshift's unique architecture.
The diagram above illustrates the inheritance chain where the Redshift adapter inherits from the PostgreSQL adapter, which in turn inherits from the base SQL and Adapter frameworks.
Sources: AGENTS.md:10, CLAUDE.md:11-20, CLAUDE.md:145
Relation Configurations
Redshift requires specific configurations for performance tuning, primarily centered around how data is distributed across nodes and how it is sorted within blocks.
Distribution Styles (DISTSTYLE)
The adapter supports four primary distribution styles defined in relation_configs/dist.py. These styles determine how Redshift distributes table rows across compute nodes.
| Style | Description |
|---|---|
AUTO | Redshift determines the optimal distribution based on table size. |
EVEN | Rows are distributed across slices in a round-robin fashion. |
ALL | A copy of the entire table is distributed to every node. |
KEY | Rows are distributed according to the values in one column. |
Sources: CLAUDE.md:158-161, dbt-redshift/src/dbt/adapters/redshift/relation_configs/dist.py
Sort Keys
Sort keys determine the physical order in which data is stored on disk. The adapter supports both COMPOUND and INTERLEAVED sort keys.
The flow above describes how sort key configurations are categorized during relation creation.
Sources: CLAUDE.md:164, dbt-redshift/src/dbt/adapters/redshift/relation_configs/sort.py
Connection and Authentication
The adapter utilizes redshift-connector for database communication and supports multiple AWS-native authentication methods.
Supported Authentication Methods
- Basic: Standard username and password.
- IAM User/Role: Uses AWS IAM credentials for authentication.
- Identity Center (IDC): Supports browser-based Single Sign-On (SSO).
- IdpTokenAuthPlugin: Allows for token-based authentication from Identity Providers.
Sources: CLAUDE.md:170-172, dbt-redshift/CHANGELOG.md:329-331
Credential Configurations
Key credentials used in the Redshift profile include:
host,port(default 5439),database,user,passwordregion,cluster_idiam_profile,access_key_id,secret_access_keyserverless_work_group,serverless_acct_id(for Redshift Serverless)
Sources: CLAUDE.md:174-175, dbt-redshift/CHANGELOG.md:307-309
Advanced Redshift Features
Datasharing and SHOW APIs
The adapter supports cross-database Datasharing by opting into Redshift's SHOW APIs instead of standard PostgreSQL catalog queries. This is enabled via the datasharing profile credential or the redshift_use_show_apis behavior flag.
The sequence shows how the adapter chooses between legacy system views and modern SHOW APIs based on configuration.
Sources: CLAUDE.md:179-181, dbt-redshift/CHANGELOG.md:58-75
Relation Management
The adapter implements several Redshift-specific DDL behaviors:
- Late-Binding Views: Configured via
bind: false, allowing views to be created without dependent table verification. - Native Alteration: Supports native
ALTER COLUMN TYPEfor resizingVARCHARandVARBYTEcolumns without rebuilding the table. - Concurrent Drops: The
allow_concurrent_dropscredential allows skipping theDROP RLockfor projects without complex downstream view dependencies.
Sources: CLAUDE.md:167-168, dbt-redshift/CHANGELOG.md:52-53, dbt-redshift/CHANGELOG.md:79
Development and Testing
The dbt-redshift package is managed via hatch and includes both unit and functional tests.
Development Workflow
cd dbt-redshift
hatch run setup # Install dependencies
hatch run code-quality # Lint and type check
hatch run unit-tests # Run local tests
hatch run integration-tests # Run against live Redshift
Sources: AGENTS.md:32-48, CLAUDE.md:19-35
Flaky Test Handling
Redshift integration tests include a specific environment for flaky tests, which are run sequentially to avoid transaction conflicts: hatch run integration-tests-flaky.
Sources: AGENTS.md:55-57, CLAUDE.md:183
The dbt-redshift adapter provides the necessary glue between dbt's transformation logic and Redshift's MPP architecture. By extending the PostgreSQL base and adding support for AWS-specific authentication and Redshift-specific performance features like distribution and sort keys, it ensures that dbt projects can scale effectively on Amazon's data warehouse platform.