> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/engine-guide/redshift/connect-to-redshift.md).

# Connect to Redshift

Configure Redshift connections for local development and DataOS Depot deployments.

With roles and grants in place, this is the connect stage. Configure the gateway that lets Vulcan reach Redshift, then validate it before writing models.

{% hint style="info" %}
**Flagged for review:** the source manual had a generic "install Vulcan" step here (`pip install vulcan-<version>-py3-none-any.whl`) with an unresolved placeholder for the wheel link ("TBD: attach the wheel link from your DataOS distribution channel"). That step isn't Redshift-specific and doesn't appear on any other converted engine page, so it's left out here. The broken link is still unresolved wherever the shared install/prerequisites doc lives and worth fixing there.
{% endhint %}

## Connection options

Set these options under `gateways.<name>.connection` in `config.yaml`.

| Option     | Description                                         | Type   | Required |
| ---------- | --------------------------------------------------- | ------ | -------- |
| `type`     | Engine type name. Must be `redshift`.               | string | Yes      |
| `host`     | The Redshift cluster or Serverless endpoint.        | string | Yes      |
| `port`     | The port number (default `5439`).                   | int    | Yes      |
| `database` | The database to connect to. Must already exist.     | string | Yes      |
| `user`     | The username for authentication.                    | string | Yes      |
| `password` | The password for authentication.                    | string | Yes      |
| `ssl`      | Enable SSL for the connection.                      | bool   | No       |
| `sslmode`  | Connection security level (for example, `require`). | string | No       |

### Authentication methods

* Username and password (required): set `user` and `password`.
* SSL (required for production): set `ssl: true` and `sslmode: require`.

{% hint style="warning" %}
Always inject the password from an environment variable: `password: {{ env_var('REDSHIFT_PASSWORD') }}`.
{% endhint %}

## Example gateway config

Local direct connection:

```yaml
model_defaults:
  dialect: redshift
  start: "2025-01-01"

gateways:
  default:
    connection:
      type: redshift
      host: "{{ env_var('REDSHIFT_HOST') }}"
      port: "{{ env_var('REDSHIFT_PORT', default='5439') }}"
      database: "{{ env_var('REDSHIFT_DATABASE', default='dev') }}"
      user: "{{ env_var('REDSHIFT_USER') }}"
      password: "{{ env_var('REDSHIFT_PASSWORD') }}"
      ssl: true
      sslmode: require
    state_connection:
      type: postgres
      host: "{{ env_var('STATESTORE_HOST', default='localhost') }}"
      port: "{{ env_var('STATESTORE_PORT', default='5432') }}"
      user: "{{ env_var('STATESTORE_USER', default='vulcan') }}"
      password: "{{ env_var('STATESTORE_PASSWORD', default='vulcan') }}"
      database: "{{ env_var('STATESTORE_DATABASE', default='statestore') }}"
    state_schema: redshift_retail

default_gateway: default
```

{% hint style="info" %}
`state_connection` is strongly recommended for Redshift, the same pattern as Databricks. Vulcan's plan/interval state lives in Postgres; isolate projects with `state_schema`.
{% endhint %}

## Local development

{% hint style="info" %}
Unlike PostgreSQL, Redshift has no official local container. You cannot run a full Redshift stack end to end on your laptop. Point local development at a small dev cluster or a low-RPU Serverless workgroup, and keep only the Vulcan state store local.
{% endhint %}

Bring up a local Postgres container for Vulcan state:

```bash
set -a && source .env && set +a
docker run -d --name vulcan-state \
  -e POSTGRES_USER=vulcan -e POSTGRES_PASSWORD=vulcan \
  -e POSTGRES_DB=statestore -p 5432:5432 postgres:15
```

Then validate against your Redshift target:

```bash
vulcan migrate
vulcan plan
```

## Production deployment

DataOS Depot is recommended for production. Configure a gateway with `type: depot` and `address: dataos://<depot-name>?purpose=rw`. The depot manages the Redshift credential and access purpose.

{% stepper %}
{% step %}
**Apply the Redshift instance secret**

Apply the Redshift instance secret.
{% endstep %}

{% step %}
**Apply the Redshift depot**

Apply the Redshift depot.
{% endstep %}

{% step %}
**Apply the Git secret**

Apply the Git secret.
{% endstep %}

{% step %}
**Add `config.yaml` to the repository**

Configure the depot-backed gateway in `config.yaml`.
{% endstep %}

{% step %}
**Apply the Vulcan domain resource**

Apply the Vulcan domain resource in `deploy.yaml`.
{% endstep %}
{% endstepper %}

| Manifest               | Purpose                                                         | Key fields                                                |
| ---------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| `redshift-secret.yaml` | DB credentials                                                  | `host`, `user`, `password`, etc.                          |
| `redshift-depot.yaml`  | Registers the cluster; binds secrets to `rw` / `query` / `scan` | `spec.type: redshift`, `spec.spec.host`, `secrets[].id`   |
| `secret-git-sync.yaml` | Repo credentials                                                | Git sync keys                                             |
| `config.yaml`          | Gateway `type: depot`, `address: dataos://<depot>?purpose=rw`   | See example above                                         |
| `deploy.yaml`          | Workflow + API                                                  | `engine: redshift`, `depots`, `repo.*`, `workflow`, `api` |

{% hint style="warning" %}
The depot `name` in the manifest must match `dataos://<name>?purpose=rw` exactly in both `deploy.yaml` and `config.yaml`. A mismatch passes `apply` but fails workflow runs.
{% endhint %}

### Depot purposes

Bind the correct purpose to each secret. A `query` credential cannot create tables. Do not give consumers an `rw` credential.

| Purpose | Who uses it      | What it allows                         |
| ------- | ---------------- | -------------------------------------- |
| `rw`    | Vulcan workflow  | Read/write schemas for materialization |
| `scan`  | Metadata scanner | Catalog / lineage                      |
| `query` | Consumers        | Read-only SQL path                     |

### Before you deploy checklist

* [ ] `.env` with Redshift connection vars, or a depot-backed gateway in `config.yaml`
* [ ] Postgres statestore configured for `state_connection`
* [ ] `vulcan migrate` and `vulcan plan` succeed locally
* [ ] Redshift instance secret applied
* [ ] Redshift depot applied; its `name` matches `dataos://<name>?purpose=rw` in both the Vulcan resource and `config.yaml`
* [ ] Git secret applied
* [ ] Vulcan resource sets `engine: redshift`, `depots`, `repo`, `workflow`, `api.replicas`
* [ ] Cron **`timezone: UTC`** in production; `endOn` ≥ 1–2 years out; `concurrencyPolicy: Forbid`

### Next step

After connection configuration is ready, choose a model strategy in [Materialization Behavior](https://v2.dataos.info/references/engine-guide/redshift/materialization-behavior.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/engine-guide/redshift/connect-to-redshift.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
