# Manual installation

## Introduction

This guide contains the steps to perform a manual installation of the [CARTO Analytics Toolbox for Oracle](https://docs.carto.com/analytics-toolbox-oracle/overview/getting-started/).

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

{% hint style="info" %}
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.
{% endhint %}

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:

```sql
-- 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

{% hint style="info" %}
The package is only available to CARTO customers. Please contact [**support@carto.com**](mailto:support@carto.com) to get an installation package.
{% endhint %}

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

{% hint style="info" %}
Use **Run Script** (F5) rather than **Run Statement** (Ctrl+Enter) to execute the entire file at once.
{% endhint %}

{% hint style="info" %}
For scripted or automated installations, [SQLcl](https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/) is also supported. Download your wallet from the OCI Console under **Database connection → Download wallet**, then:

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

{% endhint %}

{% hint style="danger" %}
WARNING: This script will remove all previous Analytics Toolbox functions and procedures in the schema.
{% endhint %}

### Setup AT Gateway (optional)

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

```sql
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"}');
```

{% hint style="info" %}
The JSON must be a single line. Contact CARTO support for the AT Gateway endpoint URL.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## Granting access to users

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

```sql
-- 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;
```

{% hint style="info" %}
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`.
{% endhint %}

## Congratulations!

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