Manual installation in your database

Introduction

This guide contains the steps to install the CARTO Analytics Toolbox for Redshift. The installation uses an interactive Python installer that deploys Lambda functions to your AWS account and creates the necessary SQL functions in your Redshift database.

The Analytics Toolbox for Redshift is available for CARTO customers. Please get in touch with [email protected] in order to get the installation package.

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. Extract the package (if not auto-extracted by your browser)
unzip carto-at-redshift-<version>.zip

# 2. Navigate to package directory
cd carto-at-redshift-<version>

# 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 step 1.

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 myschema

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. Can be comma-separated for role chaining

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

Gateway Configuration

For packages with LDS, IMPORT, or HTTP_REQUEST modules, you need to configure gateway services to enable these functionalities:

• Creation of isolines, geocoding and routing require making calls to CARTO LDS API

• Some functionalities like HTTP Request or Create Builder Map require making requests to the CARTO Platform backend

Available AT Gateway Lambda Functions

Redshift external functions require calling a Lambda function deployed in the same region as your cluster. CARTO provides Lambda functions in the following regions:

AWS Region	Lambda name	Lambda ARN
ap-northeast-1	lds-function-ap-northeast-1	arn:aws:lambda:ap-northeast-1:000955892807:function:at-gateway-asia-northeast1
ap-southeast-2	lds-function-ap-southeast-2	arn:aws:lambda:ap-southeast-2:000955892807:function:at-gateway-australia-southeast1
eu-west-1	lds-function-eu-west-1	arn:aws:lambda:eu-west-1:000955892807:function:at-gateway-europe-west1
eu-central-1	lds-function-eu-central-1	arn:aws:lambda:eu-central-1:000955892807:function:at-gateway-europe-central2
us-east-1	lds-function-us-east1	arn:aws:lambda:us-east-1:000955892807:function:at-gateway-us-east1
us-west-1	lds-function-us-west-1	arn:aws:lambda:us-west-1:000955892807:function:at-gateway-us-west1

Select the Lambda function that matches your Redshift cluster's region and note the Lambda name for use in the SETUP procedure.

IAM Role for Gateway Access

To use CARTO's AT Gateway Lambda functions, you need to create an IAM role that can assume CARTO's role. Follow these steps:

1. Go to IAM > Policies > Create Policy, and create a JSON policy named CartoFunctionsRolePolicy:

{
    "Version": "2012-10-17",
    "Statement": [
      {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": "arn:aws:iam::000955892807:role/CartoFunctionsRole",
          "Sid": "AssumeCartoFunctionsRole"
      }
    ]
}

1. Go to IAM > Roles > Create Role, and create a role for Redshift with the CartoFunctionsRolePolicy attached. Name it CartoFunctionsRedshiftRole.

2. Ensure the trust relationship allows Redshift to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
      {
          "Effect": "Allow",
          "Principal": {
              "Service": "redshift.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
      }
    ]
}

1. Go to Amazon Redshift > your cluster > Properties > Cluster permissions > Associated IAM roles, and associate the new IAM role to your Redshift cluster.

2. Note the IAM roles value for the SETUP procedure. It should look like:

arn:aws:iam::XXXXXXXXXXXX:role/CartoFunctionsRedshiftRole,arn:aws:iam::000955892807:role/CartoFunctionsRole

Getting Your API Credentials

1. API Base URL: Go to the "Developers" section in the CARTO Platform and copy the value. For more information, check the documentation.

2. API Access Token: Go to the "Developers" section and create a new API Access Token with LDS API enabled. For more information, check the documentation.

Interactive Mode

Run the installer and answer the prompts when asked about gateway configuration:

python scripts/install.py

Non-Interactive Mode

Use the --non-interactive flag with all gateway parameters:

python scripts/install.py \
  --non-interactive \
  --setup-gateway \
  --gateway-lambda lds-function-us-east1 \
  --gateway-roles "arn:aws:iam::XXXXXXXXXXXX:role/CartoFunctionsRedshiftRole,arn:aws:iam::000955892807:role/CartoFunctionsRole" \
  --gateway-api-base-url https://gcp-us-east1.api.carto.com \
  --gateway-api-access-token "your_token" \
  ...

Manual Configuration

You can also configure the gateway manually after installation by running the SETUP procedure:

CALL carto.SETUP('{
    "lambda": "lds-function-us-east1",
    "roles": "arn:aws:iam::XXXXXXXXXXXX:role/CartoFunctionsRedshiftRole,arn:aws:iam::000955892807:role/CartoFunctionsRole",
    "api_base_url": "https://gcp-us-east1.api.carto.com",
    "api_access_token": "your_token"
}');

Replace XXXXXXXXXXXX with your AWS account ID and use the Lambda name that matches your Redshift cluster's region from the table above.

Parameters:

Parameter	Description
lambda	Gateway Lambda function name or ARN (required)
roles	IAM role ARN(s) for Redshift to invoke Lambda (required)
api_base_url	CARTO API base URL (required)
api_access_token	CARTO API access token (required)

If the SETUP procedure is not executed, the LDS functions will return an informative message, but the rest of the toolbox will be completely functional.

Examples

Interactive Mode (default - with prompts):

python scripts/install.py

Non-Interactive with Auto-Created Roles:

python scripts/install.py \
  --non-interactive \
  --aws-profile dev \
  --rs-lambda-prefix mycompany- \
  --rs-host cluster.region.redshift.amazonaws.com \
  --rs-database mydb \
  --rs-user myuser \
  --rs-password "secret" \
  --rs-schema myschema

Non-Interactive with Existing Roles:

python scripts/install.py \
  --non-interactive \
  --aws-profile prod \
  --rs-lambda-prefix carto-at- \
  --rs-lambda-execution-role arn:aws:iam::123:role/ProdLambdaRole \
  --rs-lambda-invoke-role arn:aws:iam::123:role/ProdRedshiftRole \
  --rs-host cluster.region.redshift.amazonaws.com \
  --rs-database prod_db \
  --rs-user produser \
  --rs-password "secret" \
  --rs-schema carto

Non-Interactive with Explicit Credentials:

python scripts/install.py \
  --non-interactive \
  --aws-access-key-id $AWS_ACCESS_KEY_ID \
  --aws-secret-access-key $AWS_SECRET_ACCESS_KEY \
  --rs-lambda-prefix myprefix- \
  --rs-host $REDSHIFT_HOST \
  --rs-database $REDSHIFT_DB \
  --rs-user $REDSHIFT_USER \
  --rs-password "$REDSHIFT_PASSWORD" \
  --rs-schema myschema

Congratulations!

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

After an installation or update of the Analytics Toolbox is performed, the CARTO connection needs to be refreshed by the owner of the connection by clicking on the refresh button on the connection's card.

Now you can start using the functions in the SQL reference

Upgrade

In order to upgrade your Analytics Toolbox installation, simply run the installer again with the same configuration. The new functions and procedures will replace their previous versions.

Support

• Documentation: https://docs.carto.com/analytics-toolbox

• Support: [email protected]