Install, update, and uninstall TimescaleDB Toolkit

Some hyperfunctions are included by default in TimescaleDB. For additional hyperfunctions, you need to install the TimescaleDB Toolkit PostgreSQL extension.

If you’re hosting the TimescaleDB extension on your self-hosted database, you can install Toolkit by:

• Using the TimescaleDB high-availability Docker image
• Using a package manager such as yum, apt, or brew on platforms where pre-built binaries are available
• Building from source. For more information, see the Toolkit developer documentation

Docker

Install TimescaleDB Toolkit

The Toolkit extension is pre-installed and pre-enabled when you install the TimescaleDB HA docker image from a Docker container. Once you start the container, the extension is already active in your database and ready to use. No additional installation steps are required.

Update TimescaleDB Toolkit

To get the latest version of Toolkit, update the TimescaleDB HA docker image.

Uninstall TimescaleDB Toolkit

Toolkit is included in the TimescaleDB HA Docker image and cannot be uninstalled separately. To remove Toolkit, you need to remove the entire TimescaleDB container. See Uninstall TimescaleDB from Docker.

To remove the extension from a specific database without removing the container:

1. Connect to your database

   docker exec -it timescaledb psql -U postgres -d <database_name>

2. Drop the Toolkit extension

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Warning

   Using CASCADE drops all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

Kubernetes

Install TimescaleDB Toolkit

The Toolkit extension is pre-installed and pre-enabled when you install TimescaleDB on Kubernetes. Once you start the container, the extension is already active in your database and ready to use. No additional installation steps are required.

Update TimescaleDB Toolkit

To get the latest version of Toolkit, update the TimescaleDB HA Docker image used by your Kubernetes StatefulSet:

1. Update the StatefulSet to use the latest image

   Replace <new-version> with the desired version tag. For example, pg18. You find the available tags on the TimescaleDB HA Docker Hub page.

   kubectl set image statefulset/timescaledb timescaledb=timescale/timescaledb-ha:<new-version> -n tigerdata

   Kubernetes performs a rolling update, replacing the pod with the new image version.

2. Verify the new image is running

   kubectl get statefulset timescaledb -n tigerdata -o jsonpath='{.spec.template.spec.containers[0].image}'

3. Connect to your TimescaleDB pod and verify the extension versions

   kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"
   \dx

Uninstall TimescaleDB Toolkit

Toolkit is included in the TimescaleDB HA Docker image and cannot be uninstalled separately. To remove Toolkit, you need to remove the entire TimescaleDB deployment. See Uninstall TimescaleDB from Kubernetes.

If you only want to remove the extension from a specific database without removing the deployment:

1. Connect to your TimescaleDB pod

   kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"

2. Drop the Toolkit extension

   At the psql prompt:

   DROP EXTENSION timescaledb_toolkit;

   Warning

   Using CASCADE drops all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

Linux

Debian

Install TimescaleDB Toolkit

These instructions use the apt package manager.

1. Update your local repository list

   sudo apt update

2. Install TimescaleDB Toolkit

   sudo apt install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   apt update

2. Install the latest version of TimescaleDB Toolkit

   apt install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   sudo apt remove timescaledb-toolkit-postgresql-18

   Replace 18 with your PostgreSQL version if different.

3. (Optional) Remove dependencies

   To also remove unused dependencies:

   sudo apt autoremove

Ubuntu

Install TimescaleDB Toolkit

These instructions use the apt package manager.

1. Update your local repository list

   sudo apt update

2. Install TimescaleDB Toolkit

   sudo apt install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   apt update

2. Install the latest version of TimescaleDB Toolkit

   apt install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   sudo apt remove timescaledb-toolkit-postgresql-18

   Replace 18 with your PostgreSQL version if different.

3. (Optional) Remove dependencies

   To also remove unused dependencies:

   sudo apt autoremove

Red Hat

Install TimescaleDB Toolkit

These instructions use the yum package manager.

1. Update your local repository list

   sudo yum update

2. Install TimescaleDB Toolkit

   sudo yum install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   yum update

2. Install the latest version of TimescaleDB Toolkit

   yum install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   sudo yum remove timescaledb-toolkit-postgresql-18

   Replace 18 with your PostgreSQL version if different.

3. (Optional) Remove dependencies

   To also remove unused dependencies:

   sudo yum autoremove

Fedora

Install TimescaleDB Toolkit

These instructions use the yum package manager.

1. Update your local repository list

   sudo yum update

2. Install TimescaleDB Toolkit

   sudo yum install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   yum update

2. Install the latest version of TimescaleDB Toolkit

   yum install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   sudo yum remove timescaledb-toolkit-postgresql-18

   Replace 18 with your PostgreSQL version if different.

3. (Optional) Remove dependencies

   To also remove unused dependencies:

   sudo yum autoremove

RockyLinux

Install TimescaleDB Toolkit

These instructions use the dnf package manager.

1. Update your local repository list

   sudo dnf update

2. Install TimescaleDB Toolkit

   sudo dnf install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   sudo dnf update

2. Install the latest version of TimescaleDB Toolkit

   sudo dnf install timescaledb-toolkit-postgresql-18

3. Connect to the database where you want to use Toolkit

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   sudo dnf remove timescaledb-toolkit-postgresql-18

   Replace 18 with your PostgreSQL version if different.

3. (Optional) Remove dependencies

   To also remove unused dependencies:

   sudo dnf autoremove

macOS

Install TimescaleDB Toolkit

These instructions use the brew package manager. For more information on installing or using Homebrew, see the brew homepage.

1. Tap the Tiger Data formula repository

   This also contains formulae for TimescaleDB and timescaledb-tune.

   brew tap timescale/tap

2. Update your local brew installation

   brew update

3. Install TimescaleDB Toolkit

   brew install timescaledb-toolkit

4. Connect to PostgreSQL

   psql postgres

5. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

   Warning

   If you encounter an error like could not access file "$libdir/timescaledb_toolkit-X.XX.X", you may need to create a symlink from .so to .dylib format:

   ln -sf $(pg_config --pkglibdir)/timescaledb_toolkit-*.so \
          $(pg_config --pkglibdir)/timescaledb_toolkit-*.dylib

   This is due to a known issue in the Homebrew formula where the library is installed with a .so extension, but PostgreSQL on macOS expects a .dylib extension.

Update TimescaleDB Toolkit

Update Toolkit by installing the latest version and running ALTER EXTENSION.

1. Update your local repository list

   brew update

2. Install the latest version of TimescaleDB Toolkit

   brew upgrade timescaledb-toolkit

3. Connect to PostgreSQL

   psql postgres

4. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Note

   For some Toolkit versions, you might need to disconnect and reconnect active sessions.

Uninstall TimescaleDB Toolkit

If you no longer need Toolkit, you can remove it without uninstalling TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.

2. Uninstall the Toolkit package

   brew uninstall timescaledb-toolkit

3. (Optional) Remove manual symlinks

   If you created a manual .dylib symlink as a workaround during installation, remove it:

   rm $(pg_config --pkglibdir)/timescaledb_toolkit-*.dylib 2>/dev/null || true

Source

Install TimescaleDB Toolkit

To install Toolkit from source:

1. Build the extension from the latest source code

   Follow the build instructions in the TimescaleDB Toolkit GitHub repository to download and build the latest version.

2. Connect to your database

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

3. Create the Toolkit extension in the database

   CREATE EXTENSION timescaledb_toolkit;

Update TimescaleDB Toolkit

To update Toolkit installed from source:

1. Build the extension from the latest source code

   Follow the build instructions in the TimescaleDB Toolkit GitHub repository to download and build the latest version.

2. Connect to your database

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

3. Update the Toolkit extension in the database

   ALTER EXTENSION timescaledb_toolkit UPDATE;

Uninstall TimescaleDB Toolkit

If you installed Toolkit by building from source, you can uninstall it without removing TimescaleDB or PostgreSQL.

1. Drop the Toolkit extension from your databases

   Connect to each database where Toolkit is enabled and remove the extension:

   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

   At the psql prompt:

   DROP EXTENSION IF EXISTS timescaledb_toolkit CASCADE;

   Repeat this for all databases with Toolkit enabled. To exit psql, type \q.

   Warning

   Using CASCADE will drop all objects that depend on the Toolkit extension. Ensure you have backed up any data you want to keep.