> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delphina.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Redshift: VPC endpoint + IAM role

> Connect Delphina to a private Redshift cluster or workgroup through a Redshift-managed VPC endpoint using an IAM role

export const timeout_0 = "Confirm the grant to Delphina's account is active, and that the port is in a supported range."

Use this setup when your Redshift endpoint is private. You grant Delphina's AWS account access to your workgroup or cluster, and Delphina connects over AWS's private network with short-lived credentials from an IAM role.

Part of the [Redshift Connection Guide](/administration/redshift). Not sure which setup you need? Start there.

## Before you start

Ask your Delphina contact for:

* Delphina's AWS account ID, and confirmation that Delphina can create an endpoint in your AWS region.
* Delphina's principal ARN and a unique external ID, for the IAM role's trust policy.

You also need a Redshift superuser (Step 2, and Step 3 on provisioned clusters) and permission to create IAM roles in the AWS account that owns your warehouse (Step 3).

Each step has **Serverless** and **Provisioned** tabs where they differ. Serverless endpoints contain `redshift-serverless` (`<workgroup>.<account>.<region>.redshift-serverless.amazonaws.com`); provisioned endpoints look like `<cluster>.<id>.<region>.redshift.amazonaws.com`.

## Step 1: Set up the network path

<Tabs>
  <Tab title="Serverless">
    Requirements:

    * The workgroup port must be in the range **5431–5455** or **8191–8215**. The default, 5439, qualifies.

    Steps:

    1. In the Redshift console, open your workgroup → **Data access** → **Granted accounts** → **Grant access**.
    2. Enter the Delphina AWS account ID (and VPC ID, if you want to restrict access to one VPC) from your Delphina contact.
    3. Tell your Delphina contact once it's granted. We create the endpoint on our side and confirm when it's connected.
  </Tab>

  <Tab title="Provisioned">
    Requirements:

    * An **RA3** or **RG** cluster with **cluster relocation** turned on, or a **Multi-AZ** deployment. DC2 clusters can't use a VPC endpoint; see [DC2 clusters](/administration/redshift#dc2-clusters) for your options, including an [SSH tunnel](/administration/redshift/ssh-tunnel).
    * The cluster port must be in the range **5431–5455** or **8191–8215**. The default, 5439, qualifies.

    Steps:

    1. In the Redshift console, open your cluster → **Properties** → **Granted accounts** → **Grant access**.
    2. Enter the Delphina AWS account ID (and VPC ID, if you want to restrict access to one VPC) from your Delphina contact.
    3. Tell your Delphina contact once it's granted. We create the endpoint on our side and confirm when it's connected.

    You can also grant access from the CLI:

    ```bash theme={null}
    aws redshift authorize-endpoint-access \
      --cluster-identifier <CLUSTER_ID> \
      --account <DELPHINA_ACCOUNT_ID>
    ```
  </Tab>
</Tabs>

## Step 2: Grant database access

Run this as a superuser, such as the admin user created with your workgroup or cluster, connected to **the database Delphina will use**: the one you send us in Step 4. A Delphina connection reads one database.

Use a superuser if you can. A non-superuser needs the `CREATE ROLE` permission and the right to grant on every schema and table involved, either by owning them or by holding the privileges `WITH GRANT OPTION`, and can't set default privileges for other users' tables (below).

```sql theme={null}
-- Roles apply to the whole workgroup or cluster, so create it once.
CREATE ROLE delphina_role;

-- Repeat for each schema Delphina should read.
GRANT USAGE ON SCHEMA <schema_name> TO ROLE delphina_role;
GRANT SELECT ON ALL TABLES IN SCHEMA <schema_name> TO ROLE delphina_role;
```

**Cover tables created later.** `GRANT SELECT ON ALL TABLES` only covers tables that exist when you run it. Set default privileges **for each user that creates tables** in the schema, such as your dbt, Fivetran, or Airflow users. Redshift applies default privileges per creating user, so one statement doesn't cover everyone.

```sql theme={null}
-- Repeat for each user that creates tables in the schema.
ALTER DEFAULT PRIVILEGES FOR USER <creator_user> IN SCHEMA <schema_name>
  GRANT SELECT ON TABLES TO ROLE delphina_role;
```

**Other data sources.**

| Source | Extra grant |
| - | - |
| **Spectrum external schemas** (Glue / S3) | `GRANT USAGE ON SCHEMA <external_schema> TO ROLE delphina_role;` The IAM role attached to your cluster or namespace must already be able to read the underlying Glue tables and S3 data (and Lake Formation, if you use it). |
| **Datashares** (consumer database) | To read a datashare, send its consumer database as the database in Step 4. Then run `GRANT USAGE ON DATABASE <consumer_database> TO ROLE delphina_role;` If the database was created `WITH PERMISSIONS`, also grant access to its objects: `GRANT USAGE ON SCHEMA <consumer_database>.<schema> TO ROLE delphina_role;` and `GRANT SELECT ON ALL TABLES IN SCHEMA <consumer_database>.<schema> TO ROLE delphina_role;` |

**Give Delphina access to query history.** Delphina learns which tables, joins, and metrics matter from how your team queries them. By default, a non-superuser only sees its own queries in Redshift's query history, so grant the built-in monitoring role. Run this once; it isn't per database.

```sql theme={null}
GRANT ROLE sys:monitor TO ROLE delphina_role;
```

This lets Delphina read the text of every user's queries. You can choose which users' queries Delphina uses during onboarding, but that's a setting in Delphina, not a database permission: the role can still read all of them. If some query text contains values Delphina must not be able to access, talk to your Delphina contact before granting it.

## Step 3: Create the IAM role

<Tabs>
  <Tab title="Serverless">
    Create an IAM role in the AWS account that owns the workgroup, for example `delphina-redshift-access`.

    **Trust policy.** Your Delphina contact provides the Delphina principal ARN and a unique external ID.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "AllowDelphinaAssumeRole",
          "Effect": "Allow",
          "Principal": { "AWS": "<DELPHINA_PRINCIPAL_ARN>" },
          "Action": "sts:AssumeRole",
          "Condition": { "StringEquals": { "sts:ExternalId": "<EXTERNAL_ID>" } }
        }
      ]
    }
    ```

    **Permissions policy.** Replace the placeholders with your region, account ID, and workgroup ID (the UUID in the workgroup ARN).

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "ServerlessCredentials",
          "Effect": "Allow",
          "Action": [
            "redshift-serverless:GetCredentials",
            "redshift-serverless:GetWorkgroup"
          ],
          "Resource": "arn:aws:redshift-serverless:<REGION>:<ACCOUNT_ID>:workgroup/<WORKGROUP_ID>"
        }
      ]
    }
    ```

    **Map the role to the database role.** Add a tag to the IAM role with key `RedshiftDbRoles` and value `delphina_role`. When Delphina connects, Redshift signs it in as the database user `IAMR:delphina-redshift-access` and grants it `delphina_role`.
  </Tab>

  <Tab title="Provisioned">
    Delphina connects as a database user named `delphina_user`. Create it without a password, because Delphina gets short-lived credentials for it through the IAM role, and give it the Delphina role:

    ```sql theme={null}
    CREATE USER delphina_user PASSWORD DISABLE;
    GRANT ROLE delphina_role TO delphina_user;
    ```

    Create an IAM role in the AWS account that owns the cluster, for example `delphina-redshift-access`.

    **Trust policy.** Your Delphina contact provides the Delphina principal ARN and a unique external ID.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "AllowDelphinaAssumeRole",
          "Effect": "Allow",
          "Principal": { "AWS": "<DELPHINA_PRINCIPAL_ARN>" },
          "Action": "sts:AssumeRole",
          "Condition": { "StringEquals": { "sts:ExternalId": "<EXTERNAL_ID>" } }
        }
      ]
    }
    ```

    **Permissions policy.** Replace the placeholders with your region, account ID, cluster identifier, and database name.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "ClusterCredentials",
          "Effect": "Allow",
          "Action": "redshift:GetClusterCredentials",
          "Resource": [
            "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbuser:<CLUSTER_ID>/delphina_user",
            "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbname:<CLUSTER_ID>/<DATABASE>"
          ]
        },
        {
          "Sid": "DescribeCluster",
          "Effect": "Allow",
          "Action": "redshift:DescribeClusters",
          "Resource": "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:cluster:<CLUSTER_ID>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Step 4: Send us the details

<Tabs>
  <Tab title="Serverless">
    | Detail | Example |
    | - | - |
    | Workgroup name | `analytics-wg` |
    | AWS account ID and region | `123456789012`, `us-east-1` |
    | Database | `dev` |
    | Default schema (optional) | `analytics` |
    | Network option | VPC endpoint |
    | IAM role ARN | `arn:aws:iam::123456789012:role/delphina-redshift-access` |
  </Tab>

  <Tab title="Provisioned">
    | Detail | Example |
    | - | - |
    | Cluster identifier | `analytics-cluster` |
    | AWS account ID and region | `123456789012`, `us-east-1` |
    | Node type | `ra3.4xlarge` |
    | Database | `dev` |
    | Default schema (optional) | `analytics` |
    | Network option | VPC endpoint |
    | IAM role ARN | `arn:aws:iam::123456789012:role/delphina-redshift-access` |
  </Tab>
</Tabs>

## Step 5: Verify the connection

Your Delphina contact adds the connection, runs a test query, and sends you the list of schemas Delphina can see. Check it against what you meant to grant: a missing schema usually means a missing grant, and an extra one means a grant is broader than intended.

Once the connection works, onboarding starts. Delphina reads your schema and table metadata and your team's query history to build its [context layer](/context-layer), and your Delphina contact walks you through reviewing it.

## Troubleshooting

| Problem | Fix |
| - | - |
| **Connection times out** | {timeout_0} |
| **`AccessDenied` on `sts:AssumeRole`** | Check the trust policy's principal ARN and external ID match what your Delphina contact provided. |
| **`AccessDenied` on `GetCredentials` or `GetClusterCredentials`** | Check the permissions policy's resource ARNs: workgroup ID (Serverless), or cluster identifier, `delphina_user`, and database name (provisioned). |
| **Connected, but no tables visible** | Serverless: confirm the `RedshiftDbRoles` tag on the IAM role is exactly `delphina_role`. Provisioned: confirm `delphina_role` is granted to `delphina_user`. Then check `USAGE` on the schema and `SELECT` on its tables. |
| **Tables lose access after a dbt run** | Add `ALTER DEFAULT PRIVILEGES` for the user dbt runs as, then re-run `GRANT SELECT ON ALL TABLES IN SCHEMA` to restore access to existing tables. |
| **Spectrum tables fail with a permissions error** | The IAM role attached to your cluster or namespace (not Delphina's role) needs Glue and S3 access to the external data. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.