Promscale Extension

This Postgres extension contains support functions to improve the performance of Promscale.

Promscale 0.11.0 and higher require that the Promscale extension is installed. Check the release notes for more details.

Requirements

To run the extension:

• PostgreSQL version 12 or newer.

To compile the extension (see instructions below):

• Rust compiler
• PGX framework

Installation

Precompiled OS Packages

You can install the Promscale extension using precompiled packages for Debian and RedHat-based distributions (RHEL-7 only).

The packages can be found in the Timescale repository.

While the extension declares a dependency on Postgres 12-14, it can be run on TimescaleDB 2.x as well, which fulfills the requirement on Postgres indirectly. You can find the installation instructions for TimescaleDB here

Debian Derivatives

1. Install Postgres or TimescaleDB Instructions for installing TimescaleDB and Postgres can be found here, and here respectively.

2. Install the Promscale extension

   wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | apt-key add -
   apt update
   apt install promscale-extension-postgresql-14
   

RHEL/CentOS

See the Postgres documentation for more information.

1. Install TimescaleDB or Postgres Instructions for installing TimescaleDB and Postgres can be found here, and here respectively.

2. Install the extension (on CentOS 7)

   yum install https://download.postgresql.org/pub/repos/yum/reporpms/EL-$(rpm -E %{centos})-x86_64/pgdg-redhat-repo-latest.noarch.rpm
   tee /etc/yum.repos.d/timescale_timescaledb.repo <<EOL
   [timescale_timescaledb]
   name=timescale_timescaledb
   baseurl=https://packagecloud.io/timescale/timescaledb/el/$(rpm -E %{rhel})/\$basearch
   repo_gpgcheck=1
   gpgcheck=0
   enabled=1
   gpgkey=https://packagecloud.io/timescale/timescaledb/gpgkey
   sslverify=1
   sslcacert=/etc/pki/tls/certs/ca-bundle.crt
   metadata_expire=300
   EOL
   yum update
   yum install -y promscale-extension-postgresql-14
   

Docker images

• Official HA. This very image is available at Timescale Cloud. They are updated along with tagged releases.
• HA-based CI image - used in the GitHub Actions CI pipeline. Use at your own peril. It could be handy to play with pre-release versions.
• alpine - legacy and local development -- Avoid if you can. It will eat your laundry collation.
• quick and package building images are not published anywhere and are used for local development and building packages

Compile From Source

The extension is installed by default on the timescaledev/promscale-extension:latest-pg12 docker image.

For bare-metal installations, the full instructions for setting up PostgreSQL, TimescaleDB, and the Promscale Extension are:

1. Install some necessary dependencies

   sudo apt-get install -y wget curl gnupg2 lsb-release

2. Add the PostgreSQL APT repository (Ubuntu)

   echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -c -s)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
   wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

3. Add the TimescaleDB APT repository

   echo "deb [signed-by=/usr/share/keyrings/timescale.keyring] https://packagecloud.io/timescale/timescaledb/ubuntu/ $(lsb_release -c -s) main" | sudo tee /etc/apt/sources.list.d/timescaledb.list
   wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/timescale.keyring

4. Install PostgreSQL with TimescaleDB

   sudo apt-get update
   sudo apt-get install -y timescaledb-2-postgresql-14

5. Tune the PostgreSQL installation

   sudo timescaledb-tune --quiet --yes
   sudo service postgresql restart

6. Install dependencies for the PGX framework and promscale_extension

   sudo apt-get install -y build-essential clang libssl-dev pkg-config libreadline-dev zlib1g-dev postgresql-server-dev-14

7. Install rust.

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env

8. Install the PGX framework

   cargo install cargo-pgx --git https://github.com/timescale/pgx --branch promscale-staging

9. Initialize the PGX framework using the PostgreSQL 14 installation

   cargo pgx init --pg14=/usr/lib/postgresql/14/bin/pg_config

10. Download this repo and change directory into it

    sudo apt-get install -y git
    git clone https://github.com/timescale/promscale_extension
    cd promscale_extension
    git checkout 0.5.0

11. Compile and install

    make package
    sudo make install

12. Create a PostgreSQL user and database for promscale (use an appropriate password!)

    sudo -u postgres psql -c "CREATE USER promscale SUPERUSER PASSWORD 'promscale';"
    sudo -u postgres psql -c "CREATE DATABASE promscale OWNER promscale;"

13. Download and run promscale (it will install the extension in the PostgreSQL database)

    LATEST_VERSION=$(curl -s https://api.github.com/repos/timescale/promscale/releases/latest | grep "tag_name" | cut -d'"' -f4)
    curl -L -o promscale "https://github.com/timescale/promscale/releases/download/${LATEST_VERSION}/promscale_${LATEST_VERSION}_Linux_x86_64"
    chmod +x promscale
    ./promscale --db-name promscale --db-password promscale --db-user promscale --db-ssl-mode allow --install-extensions

This extension will be created via CREATE EXTENSION automatically by the Promscale connector and should not be created manually.

Common Compilation Issues

• cargo: No such file or directory means the Rust compiler is not installed

Development

To understand more about how to write SQL migration files for this extension, consult this guide.