This guide explains all the steps to install the Python libraries and the SQL functions and procedures of the toolbox in your PostgreSQL database.
The CARTO Analytics Toolbox contains two packages:
- core: this is the public and open-source package. It contains all the core GIS functions that complement the GIS native functions available in PostgreSQL.
- advanced: this is a premium package only available for CARTO customers. It contains advanced GIS functions to power high-level GIS analytics in PostgreSQL.
This guide explains how to install the core package. To access the advanced features, please contact [email protected].
We can divide the process into two steps: setup and installation. The first one must be done only the first time. The second one must be done every time you want to install a new version of the packages.
This step consists of setting up the PostgreSQL database where we want to install the toolbox. A Postgres database is required (RDS, Aurora, Cloud SQL, Azure, etc.)
Here is the documentation to create a PostgreSQL cluster. Once the cluster is created, save the hostname. This is required to perform the connection to the database.
Once the account and the cluster are created, connect the database to create the
cartoschema. The CARTO Analytics Toolbox will be installed in this schema. We also recommend having a dedicated user called
cartowith the permissions to manage the
To do this, connect to your PostgreSQL database and run the following script:
-- Create the carto schema
CREATE SCHEMA carto;
-- Grant usage to public role
GRANT USAGE ON SCHEMA carto TO public;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA carto TO public;
GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA carto TO public;
This information (database, user and password) will be needed in the installation step.
You can check out the PostgreSQL getting started documentation for further information.
The CARTO Analytics Toolbox makes use of the PostGIS extension. Make sure you have this extension installed in your database. Run the following query to enable the extension.
CREATE EXTENSION postgis;
Some modules require additional extensions. In case you want to make use of them, make sure you have the corresponding extension installed in your database. Run the following query to enable the extensions.
CREATE EXTENSION plv8; -- Required only by H3
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.
If you have a previously installed version of the Analytics Toolbox, you can check the installed version by running
This will work in any operating system: Windows, macOS, and Linux.
- 1.Install Python >= 3.7: https://www.python.org/downloads/
- 2.Create a virtual environment (optional for Linux, macOS):python -m venv envsource env/bin/activate
- 3.Next, install the tool:pip install -U pippip install git+https://github.com/cartodb/[email protected]#subdirectory=tools/installer
Create a config.yml file. We recommend creating it in an empty directory. This file must contain information on the Postgres connection. For example:
Fill the configuration file with the connection information (Postgres database to install the Analytics Toolbox).
This zip file contains the scripts to install the analytics toolbox. Put the zip file in the same directory as the config.yml file. Latest installation package: package file
From the directory containing the config.yaml file, and the zip installation package, open a console and run the Python installer as shown below.
The installer will read both the Configuration file and Analytics Toolbox package and perform the installation of the modules in the specified Postgres database.
The output should look like this:
Reading config file: config.yml
Reading package file: carto-analytics-toolbox-postgres-latest.zip
100%|█████████████████████████████████████| 62/62 [00:09<00:00, 6.45it/s]
This script will remove all the previous functions and procedures in the
Congratulations! you have successfully installed the CARTO Analytics Toolbox in your PostgreSQL database. Now you can start testing the functions in the SQL reference.