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

# Amazon Redshift

> Connect Amazon Redshift to ClarityQ

## Setup

### Step 1: Gather cluster information

1. Log into [AWS Management Console](https://console.aws.amazon.com/)
2. Navigate to **Amazon Redshift** → **Clusters**
3. Select your cluster
4. Note the following:
   * **Endpoint**: e.g., `mycluster.abc123.us-west-2.redshift.amazonaws.com`
   * **Port**: Usually `5439`
   * **Database**: Your database name

### Step 2: Configure network access

Choose one of the following connection methods:

#### Option 1: Direct IP Access

Allow ClarityQ to connect by configuring your security group:

1. Navigate to **EC2** → **Security Groups**
2. Find the security group attached to your Redshift cluster
3. Add an inbound rule:
   * **Type**: Custom TCP
   * **Port**: 5439
   * **Source**: Add these ClarityQ IP addresses:
     * `44.218.213.75`
     * `54.161.37.107`
     * `54.208.212.67`

#### Option 2: AWS PrivateLink

Establish a private connection without exposing traffic to the public internet:

**Step 2a: Create a Network Load Balancer (if you don't have one)**

If you don't already have a Network Load Balancer for your Redshift cluster:

1. **Navigate to EC2 Load Balancers**
   * In AWS Console, search for "EC2" and select **EC2**
   * In the left navigation pane, under **Load Balancing**, click **Load Balancers**

2. **Create Network Load Balancer**
   * Click **Create Load Balancer**
   * Select **Network Load Balancer** and click **Create**

3. **Configure Load Balancer**
   * **Load balancer name**: Enter a name (e.g., `redshift-nlb`)
   * **Scheme**: Select **Internal** (for private connectivity)
   * **IP address type**: Select **IPv4**
   * **VPC**: Choose the same VPC as your Redshift cluster
   * **Availability Zones**: Select the subnets where your Redshift cluster is accessible

4. **Configure Listener**
   * **Protocol**: TCP
   * **Port**: 5439 (Redshift default port)
   * **Target group**: Create a new target group with:
     * **Target type**: IP addresses
     * **Protocol**: TCP
     * **Port**: 5439
     * **VPC**: Same as your Redshift cluster
     * **Add your Redshift cluster's IP as a target**

5. **Create the Load Balancer**
   * Review settings and click **Create load balancer**
   * Wait for it to become **Active** (takes a few minutes)

**Step 2b: Create an Endpoint Service**

1. **Open AWS Console and navigate to VPC**
   * Go to [AWS Management Console](https://console.aws.amazon.com/)
   * In the search bar, type "VPC" and select **VPC**

2. **Access Endpoint Services**
   * In the left navigation pane, scroll down to **Virtual private cloud**
   * Click **Endpoint services**

3. **Create the Endpoint Service**
   * Click **Create endpoint service**

4. **Configure the Endpoint Service**
   * **Service name**: Leave this empty (AWS will auto-generate)
   * **Load balancer type**: Select **Network**
   * **Available load balancers**: Choose your Network Load Balancer from Step 2a
   * **Require acceptance for endpoint**: Check this box (recommended for security)
   * **Supported IP address types**: Select **IPv4** (default)

5. **Review and Create**
   * Click **Create endpoint service**
   * AWS will generate a service name in the format: `com.amazonaws.vpce.<region>.vpce-svc-<id>`
   * **Important**: Copy this service name - you'll need it for Step 2e

**Step 2c: Authorize ClarityQ Access**

1. In your Endpoint Service settings, add ClarityQ's AWS account as "Allow principals":
   ```
   arn:aws:iam::452271769350:root
   ```

**Step 2d: Configure Security Group for PrivateLink**

If your NLB has an associated security group, you must allow inbound traffic from ClarityQ's VPC CIDR ranges:

1. Navigate to **EC2** → **Security Groups**
2. Find the security group attached to your Network Load Balancer
3. Add inbound rules:
   * **Type**: Custom TCP
   * **Port**: 5439
   * **Source**: Add these ClarityQ VPC CIDR ranges:
     * `10.2.0.0/16` (Production)
     * `10.1.0.0/16` (Staging)
     * `10.0.0.0/16` (Development)

<Note>
  These CIDR ranges are required because PrivateLink traffic appears to originate from ClarityQ's VPC. Without these rules, connections will time out even if the endpoint service is correctly configured.
</Note>

**Step 2e: Note Service Details for ClarityQ Configuration**
You'll need these details when configuring the connection in ClarityQ:

* **Service name**: Your endpoint service name
* **AWS Region**: The region where your service is located
* **Cluster details**: Endpoint, port, database name, and schema

### Step 3: Create a dedicated user

Connect to your Redshift cluster and create a service account:

```sql theme={null}
-- Create user with password
CREATE USER clarityq_user
WITH PASSWORD 'your_secure_password'
CONNECTION LIMIT 10;
```

### Step 4: Grant database permissions

Configure the required permissions for ClarityQ to connect, discover schemas, and query your data:

```sql theme={null}
-- Grant database connection
GRANT CONNECT ON DATABASE your_database TO clarityq_user;

-- Grant schema discovery and usage (for all schemas ClarityQ should access)
GRANT USAGE ON SCHEMA public TO clarityq_user;
GRANT USAGE ON SCHEMA your_schema TO clarityq_user;

-- Grant table read access for data querying
GRANT SELECT ON ALL TABLES IN SCHEMA public TO clarityq_user;
GRANT SELECT ON ALL TABLES IN SCHEMA your_schema TO clarityq_user;
```

### Step 5: Configure connection in ClarityQ

In the ClarityQ interface, fill out the connection form with the following fields:

#### For Option 1 (Direct IP Access):

**Basic Fields:**

* **Connection Name**: Choose a name for this connection (e.g., "Production Redshift")
* **Host**: Your Redshift cluster endpoint (e.g., `mycluster.abc123.us-west-2.redshift.amazonaws.com`)
* **Port**: `5439` (default, pre-filled)
* **Database**: Your database name (e.g., `analytics_db`)
* **User**: `clarityq_user` (the user you created in Step 3)
* **DB Schema**: `public` (default, pre-filled)

#### For Option 2 (AWS PrivateLink):

**Basic Fields:**

* **Connection Name**: Choose a name for this connection (e.g., "Production Redshift PrivateLink")
* **Host**: The DNS name of your VPC Endpoint Service (e.g., `com.amazonaws.vpce.us-west-2.vpce-svc-abc123def456.us-west-2.vpce.amazonaws.com`)
* **Port**: `5439` (default, pre-filled)
* **Database**: Your database name (e.g., `analytics_db`)
* **User**: `clarityq_user` (the user you created in Step 3)
* **DB Schema**: `public` (default, pre-filled)

#### Authentication Method (for both options)

Choose one of the following by toggling "Use IAM Authentication":

**Password Authentication (default):**

* **Password**: Enter the password you set for `clarityq_user`

**IAM Authentication (toggle enabled):**

* **Cluster Identifier**: Your Redshift cluster name (e.g., `mycluster`)
* **Region**: AWS region (e.g., `us-west-2`)
* **Access Key ID**: AWS access key from Step 4 (Method 2)
* **Secret Access Key**: AWS secret key from Step 4 (Method 2)

## IAM authentication setup

For enhanced security, configure IAM-based authentication:

### Step 1: Create IAM policy

Create a policy for Redshift access:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "redshift:GetClusterCredentials"
      ],
      "Resource": [
        "arn:aws:redshift:us-west-2:123456789012:dbuser:mycluster/clarityq_user"
      ]
    }
  ]
}
```

### Step 2: Attach policy to IAM user or role

1. Create or select an IAM user/role
2. Attach the policy created above
3. Generate access keys if using IAM user

### Step 3: Configure in ClarityQ

Use the IAM configuration with:

* `cluster_identifier`: Your cluster name
* `region`: AWS region
* `access_key_id` and `secret_access_key`: AWS credentials for the IAM user/role with the policy created above