dbt-redshift

Warnings

• breaking dbt-redshift must be installed with the same minor version as dbt-core (e.g., dbt-core==1.10.x requires dbt-redshift==1.10.x). Mismatched versions will lead to errors.
  Fix: Always install `dbt-redshift` and `dbt-core` with matching minor versions. Use `pip install dbt-core==X.Y.Z dbt-redshift==X.Y.Z`.
• gotcha Incorrect or incomplete configuration in `profiles.yml` is a common source of connection errors. This includes wrong `host`, `port`, `user`, `password`, `dbname`, or `schema`.
  Fix: Carefully verify all connection parameters in your `profiles.yml` against your Redshift cluster settings. Ensure network connectivity (security groups, firewalls) allows access from where dbt is run.
• gotcha IAM authentication for Redshift requires specific additional parameters in `profiles.yml` (e.g., `iam_duration_seconds`, `iam_user`, `iam_role_arn`, `cluster_id`, `db_user`). Misconfiguration is frequent.
  Fix: Refer to the official dbt-redshift documentation for the exact IAM configuration schema. Ensure your AWS credentials and IAM roles have the necessary permissions to generate Redshift credentials.
• gotcha Redshift user permissions can prevent dbt from creating schemas or tables. The user configured in `profiles.yml` needs `CREATE` schema/table privileges in the target database.
  Fix: Grant appropriate permissions to your Redshift user. For example: `GRANT CREATE ON SCHEMA public TO your_user;` and ensure `your_user` can create tables in the desired schemas.
• gotcha Long-running dbt models might time out if `statement_timeout_in_seconds` is not configured or set too low. The default may vary but can be insufficient for complex transformations.
  Fix: Increase `statement_timeout_in_seconds` in your `profiles.yml` or `dbt_project.yml` for specific models or targets. E.g., `statement_timeout_in_seconds: 1800` (30 minutes).
• gotcha Redshift's support for complex ephemeral materializations (especially deeply nested CTEs or specific window functions) can be limited or lead to performance issues. dbt-redshift sometimes converts them to `views` or `tables` or fails.
  Fix: For complex logic, consider explicitly using `view` or `table` materializations instead of `ephemeral` to avoid unexpected behavior or performance bottlenecks specific to Redshift's query optimizer.

Install

• pip install dbt-redshift Install dbt-redshift

Imports

• Not applicable for end-users

  dbt-redshift is an adapter, loaded by dbt-core based on your profiles.yml configuration. End-users typically do not directly import symbols from dbt-redshift in Python code.

  The library primarily provides CLI functionality and configuration-driven interaction via dbt-core.

Quickstart

This quickstart demonstrates how to set up a basic dbt project to connect to a Redshift cluster. It covers installation, project initialization, configuring `profiles.yml` with essential connection details (using environment variables for credentials), and running a simple dbt model to verify the connection and transformation.

# 1. Install dbt-redshift
pip install dbt-redshift

# 2. Initialize a new dbt project
dbt init my_redshift_project
cd my_redshift_project

# 3. Configure profiles.yml (located in ~/.dbt/profiles.yml or dbt project directory)
# Create or edit ~/.dbt/profiles.yml with your Redshift connection details:
# my_redshift_project:
#   target: dev
#   outputs:
#     dev:
#       type: redshift
#       host: your-redshift-cluster-endpoint.redshift.amazonaws.com
#       port: 5439
#       user: os.environ.get('REDSHIFT_USER', 'your_user')
#       password: os.environ.get('REDSHIFT_PASSWORD', 'your_password')
#       dbname: your_database
#       schema: your_schema
#       threads: 4

# 4. Create a simple dbt model (e.g., models/example/my_first_dbt_model.sql)
# -- models/example/my_first_dbt_model.sql
# select 1 as id, 'hello' as message

# 5. Test the connection and run your model
dbt debug --target dev
dbt run