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

# 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

On macOS, browsers may auto-extract the ZIP. If the folder already exists, skip the unzip step.

If you have a previously installed version of the Analytics Toolbox, you can check the installed version by running SELECT carto.VERSION_CORE().

Installation Methods

Option 1: Interactive Installation (Recommended)

The installer guides you through configuration with prompts:

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:

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

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.

Get Help

See all available options:

python scripts/install.py --help

CLI Parameters Reference

AWS Authentication (Choose one method)

Method 1: AWS Profile (Recommended)

--aws-profile default

Method 2: Explicit Credentials

--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)

--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:

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.

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.

# 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