Manual installation

Introduction

This guide contains the steps to perform a manual installation of the CARTO Analytics Toolbox for Oracle.

Setup

This step consists of setting up the Oracle database where we want to install the toolbox.

An Oracle database is required (Autonomous Database, on-premises, RDS, Azure, etc.). The Analytics Toolbox has been tested with Oracle Database 19c and later versions.

Creating the schema

Oracle schemas are tied to database users. We recommend creating a dedicated user to host the Analytics Toolbox functions.

For the sake of documenting the process, we'll assume a schema named CARTO and an admin user named ADMIN. You can use different names, but remember to adapt the code snippets accordingly.

Connect to your Oracle database as a user with administrative privileges (e.g., ADMIN) using Database Actions (SQL Worksheet, available in every Oracle Autonomous Database) or SQLcl, and run the following script:

-- Create the carto user/schema
CREATE USER CARTO NO AUTHENTICATION;

-- Grant object creation privileges
GRANT CREATE PROCEDURE TO CARTO;  -- Covers both procedures and functions
GRANT CREATE TABLE TO CARTO;      -- Required for map, statistics, tiler modules
GRANT CREATE VIEW TO CARTO;       -- Required for LDS and data modules
GRANT UNLIMITED TABLESPACE TO CARTO;

-- Grant network ACL permissions (required for AT Gateway features)
BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host => '*',
    ace  => xs$ace_type(
      privilege_list => xs$name_list('connect', 'resolve'),
      principal_name => 'CARTO',
      principal_type => xs_acl.ptype_db
    )
  );
  COMMIT;
END;
/

Installation

Once the setup is completed, we can proceed with the installation of the toolbox. This step will be performed the first time and every time we want to install an updated version.

Download the package

This ZIP file contains the scripts to install the Analytics Toolbox. Unzip the content in your local storage. This package will contain:

• LICENSE file

• modules.sql file

The package is only available to CARTO customers. Please contact [e-mail] to get an installation package.

Execute the script

1. Open the OCI Console and navigate to your Autonomous Database instance

2. Click Database Actions → SQL to open the SQL Worksheet

3. Open modules.sql locally, copy its contents, and paste them into the SQL Worksheet

4. Click Run Script (F5) to execute the full script

Use Run Script (F5) rather than Run Statement (Ctrl+Enter) to execute the entire file at once.

For scripted or automated installations, SQLcl is also supported. Download your wallet from the OCI Console under Database connection → Download wallet, then:

export TNS_ADMIN=/path/to/wallet
sql admin_user/password@yourdb_high @modules.sql

WARNING: This script will remove all previous Analytics Toolbox functions and procedures in the schema.

Setup AT Gateway (optional)

To use features that connect to CARTO services (geocoding, Create Builder Map, etc.), run the SETUP procedure:

CALL CARTO.SETUP('{"endpoint":"https://at-gateway-xxx.run.app","api_base_url":"https://gcp-us-east1.api.carto.com","api_access_token":"your_token"}');

The JSON must be a single line. Contact CARTO support for the AT Gateway endpoint URL.

If using AT Gateway features, always run SETUP before GRANT_ACCESS. The SETUP procedure replaces internal stub functions, which temporarily invalidates dependent objects. Running GRANT_ACCESS afterwards ensures all objects receive the correct permissions.

Granting access to users

After installation, grant permissions to users who will use the Analytics Toolbox:

-- Connect as administrative user (e.g., ADMIN)

-- Grant EXECUTE on all Analytics Toolbox functions/procedures
CALL CARTO.GRANT_ACCESS('app_user');

-- Grant INHERIT PRIVILEGES (required for AUTHID CURRENT_USER procedures)
GRANT INHERIT PRIVILEGES ON USER app_user TO CARTO;

After updating to a new Analytics Toolbox version, repeat the installation steps in order: run modules.sql, then SETUP (if using AT Gateway), then GRANT_ACCESS.

Congratulations!

You have successfully installed the CARTO Analytics Toolbox in your Oracle database and configured user access.