# Core version

The Core package contains the open-source modules of the CARTO Analytics Toolbox for Redshift. This guide walks you through installing the Core package in your Redshift database.

## Prerequisites

* **Python**: 3.10+ (tested with 3.10-3.13)
* **AWS**: Account with Lambda and IAM permissions
* **Redshift**: Cluster with admin access

## Quick Start

```bash
# 1. Download and extract the Core package
curl -L -o carto-at-core-redshift-latest.zip \
  https://storage.googleapis.com/carto-analytics-toolbox-core/redshift/carto-analytics-toolbox-core-redshift-latest.zip
unzip carto-at-core-redshift-latest.zip

# 2. Navigate to package directory
cd carto-at-core-redshift-*

# 3. Setup Python environment
python3 -m venv .venv && source .venv/bin/activate
pip install -r scripts/requirements.txt

# 4. Run interactive installer
python scripts/install.py
```

{% hint style="info" %}
On macOS, browsers may auto-extract the ZIP. If the folder already exists, skip the unzip step.
{% endhint %}

{% hint style="info" %}
If you have a previously installed version of the Analytics Toolbox, you can check the installed version by running `SELECT carto.VERSION_CORE()`.
{% endhint %}

## Installation Methods

### Option 1: Interactive Installation (Recommended)

The installer guides you through configuration with prompts:

```bash
python scripts/install.py
```

**Deployment Phases:**

* **Phase 0** (if needed): Auto-creates IAM roles (Lambda execution + Redshift invoke)
* **Phase 1**: Deploys Lambda functions to AWS
* **Phase 2**: Creates external functions in Redshift
* **Phase 3**: Deploys native SQL UDFs

### Option 2: Non-Interactive Installation

For automated deployments (CI/CD, scripts), use the `--non-interactive` flag:

```bash
python scripts/install.py \
  --non-interactive \
  --aws-region us-east-1 \
  --aws-access-key-id AKIAXXXX \
  --aws-secret-access-key XXXX \
  --rs-lambda-prefix mycompany- \
  --rs-host cluster.region.redshift.amazonaws.com \
  --rs-database mydb \
  --rs-user myuser \
  --rs-password "secret" \
  --rs-schema carto
```

{% hint style="warning" %}
The `--non-interactive` (or `-y`) flag is **required** to skip prompts. Without it, the installer will always prompt interactively, even if all parameters are provided via command line.
{% endhint %}

### Get Help

See all available options:

```bash
python scripts/install.py --help
```

## CLI Parameters Reference

### AWS Authentication (Choose one method)

**Method 1: AWS Profile** (Recommended)

```bash
--aws-profile default
```

**Method 2: Explicit Credentials**

```bash
--aws-access-key-id AKIAXXXX
--aws-secret-access-key XXXX
--aws-session-token XXXX  # Optional, for temporary credentials
```

**Method 3: IAM Role** (No parameters needed - automatic on EC2/ECS)

**Method 4: Assume Role** (Cross-account)

```bash
--aws-assume-role-arn arn:aws:iam::ACCOUNT:role/ROLE
```

### AWS Configuration

| Parameter           | Description                     |
| ------------------- | ------------------------------- |
| `--aws-region TEXT` | AWS region (default: us-east-1) |

### Lambda Configuration

| Parameter                                        | Description                                                                                                      |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `--rs-lambda-prefix TEXT`                        | Lambda name prefix (default: carto-at-). Example: `mycompany-` creates functions named `mycompany-function_name` |
| `--rs-lambda-execution-role TEXT`                | Existing Lambda execution role ARN (optional). If not provided, will auto-create during Phase 0                  |
| `--rs-lambda-override / --no-rs-lambda-override` | Override existing Lambdas (default: yes)                                                                         |

### Redshift Configuration

| Parameter                      | Description                                                                                                       |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `--rs-host TEXT`               | Redshift host endpoint (**required**). Example: `cluster.abc123.us-east-1.redshift.amazonaws.com`                 |
| `--rs-database TEXT`           | Redshift database name (**required**)                                                                             |
| `--rs-user TEXT`               | Redshift username (**required**)                                                                                  |
| `--rs-password TEXT`           | Redshift password (**required**)                                                                                  |
| `--rs-schema TEXT`             | Schema for Analytics Toolbox functions (default: carto)                                                           |
| `--rs-lambda-invoke-role TEXT` | Existing Redshift IAM role ARN (optional). If not provided, will auto-create and attach to cluster during Phase 0 |

## IAM Roles

When IAM role ARNs are not provided, the installer will automatically create them during Phase 0.

### Lambda Execution Role

* **Purpose**: Allows Lambda functions to execute and log
* **Name**: `<Prefix>LambdaExecutionRole` (e.g., `CartoATLambdaExecutionRole`)
* **Trust Policy**: Trusts `lambda.amazonaws.com`
* **Permissions**: `AWSLambdaBasicExecutionRole` (CloudWatch Logs)

### Redshift Invoke Role

* **Purpose**: Allows Redshift to invoke Lambda functions
* **Name**: `<Prefix>RedshiftInvokeRole` (e.g., `CartoATRedshiftInvokeRole`)
* **Trust Policy**: Trusts `redshift.amazonaws.com`
* **Permissions**: `lambda:InvokeFunction` on all Lambda functions
* **Auto-attached**: To Redshift cluster (if permissions available)

### Using Existing Roles

To use pre-created roles instead of auto-creation:

```bash
python scripts/install.py \
  --rs-lambda-execution-role arn:aws:iam::ACCOUNT:role/MyLambdaRole \
  --rs-lambda-invoke-role arn:aws:iam::ACCOUNT:role/MyRedshiftRole \
  ...
```

## Required AWS Permissions

**For Auto-Creation (Full Install)**:

* `lambda:CreateFunction`, `lambda:UpdateFunctionCode`, `lambda:UpdateFunctionConfiguration`
* `lambda:GetFunction`, `lambda:AddPermission`
* `iam:CreateRole`, `iam:GetRole`, `iam:PutRolePolicy`, `iam:AttachRolePolicy`
* `redshift:DescribeClusters`, `redshift:ModifyClusterIamRoles`

**For Existing Roles (Minimal)**:

* `lambda:CreateFunction`, `lambda:UpdateFunctionCode`, `lambda:UpdateFunctionConfiguration`
* `lambda:GetFunction`, `lambda:AddPermission`

## Congratulations!

You have successfully installed the CARTO Analytics Toolbox Core in your Redshift database.

Now you can start using the functions from the Core modules in the [SQL reference](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-redshift/sql-reference).

## Upgrade

To upgrade your Analytics Toolbox Core installation, download the latest package and run the installer again with the same configuration. The new functions and procedures will replace their previous versions.

```bash
# Download the latest version
curl -L -o carto-at-core-redshift-latest.zip \
  https://storage.googleapis.com/carto-analytics-toolbox-core/redshift/carto-analytics-toolbox-core-redshift-latest.zip

# Extract and run installer
unzip -o carto-at-core-redshift-latest.zip
cd carto-at-core-redshift-*
python3 -m venv .venv && source .venv/bin/activate
pip install -r scripts/requirements.txt
python scripts/install.py
```