# Manual installation in your database ## Introduction This guide contains the steps to install the [CARTO Analytics Toolbox for Redshift](https://docs.carto.com/analytics-toolbox-redshift/overview/getting-started/). 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. {% hint style="info" %} The Analytics Toolbox for Redshift is available for CARTO customers. Please get in touch with [**support@carto.com**](mailto:support@carto.com) in order to get the installation package. {% endhint %} ## 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. Extract the package (if not auto-extracted by your browser) unzip carto-at-redshift-.zip # 2. Navigate to package directory cd carto-at-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 step 1. {% 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 myschema ``` {% 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. 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**: `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**: `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` ## 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 | at-gateway-asia-northeast1 | arn:aws:lambda:ap-northeast-1:000955892807:function:at-gateway-asia-northeast1 | | ap-southeast-2 | at-gateway-australia-southeast1 | arn:aws:lambda:ap-southeast-2:000955892807:function:at-gateway-australia-southeast1 | | eu-west-1 | at-gateway-europe-west1 | arn:aws:lambda:eu-west-1:000955892807:function:at-gateway-europe-west1 | | eu-central-1 | at-gateway-europe-central2 | arn:aws:lambda:eu-central-1:000955892807:function:at-gateway-europe-central2 | | us-east-1 | at-gateway-us-east1 | arn:aws:lambda:us-east-1:000955892807:function:at-gateway-us-east1 | | us-west-1 | at-gateway-us-west1 | 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`: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::000955892807:role/CartoFunctionsRole", "Sid": "AssumeCartoFunctionsRole" } ] } ``` 2. Go to **IAM > Roles > Create Role**, and create a role for Redshift with the `CartoFunctionsRolePolicy` attached. Name it `CartoFunctionsRedshiftRole`. 3. Ensure the trust relationship allows Redshift to assume the role: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "redshift.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` 4. Go to **Amazon Redshift > your cluster > Properties > Cluster permissions > Associated IAM roles**, and associate the new IAM role to your Redshift cluster. 5. 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](https://docs.carto.com/carto-user-manual/developers/api-base-url). 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](https://docs.carto.com/carto-user-manual/developers/api-access-tokens).
### Interactive Mode Run the installer and answer the prompts when asked about gateway configuration: ```bash python scripts/install.py ``` ### Non-Interactive Mode Use the `--non-interactive` flag with all gateway parameters: ```bash python scripts/install.py \ --non-interactive \ --setup-gateway \ --gateway-lambda at-gateway-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: ```sql CALL carto.SETUP('{ "lambda": "at-gateway-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" }'); ``` {% hint style="warning" %} Replace `XXXXXXXXXXXX` with your AWS account ID and use the Lambda name that matches your Redshift cluster's region from the table above. {% endhint %} **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) | {% hint style="info" %} 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. {% endhint %} ## Examples **Interactive Mode** (default - with prompts): ```bash python scripts/install.py ``` **Non-Interactive with Auto-Created Roles**: ```bash 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**: ```bash 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**: ```bash 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. {% hint style="info" %} 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. {% endhint %} Now you can start using the functions in the [SQL reference](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/overview/) ## 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**: * **Support**: