It is built in Rust with pgrx and is designed to work with TimescaleDB and plain PostgreSQL data.

Toolkit focuses on the database-engine pieces that are awkward or expensive to rebuild in every application: approximate aggregates, two-step aggregation, counter and gauge analysis, time-weighted averages, state tracking, downsampling, and time-series pipeline utilities. These functions run inside PostgreSQL, so they can be used in SQL queries, materialized views, continuous aggregates, and application-facing database APIs.

• Approximate analytics: tdigest, uddsketch, HyperLogLog, and Count-Min Sketch.
• Time-series aggregates: counter aggregates, gauge aggregates, time-weighted averages, statistical aggregates, heartbeat aggregates, and state aggregates.
• Visualization and reduction helpers: ASAP smoothing and LTTB downsampling.
• Time-vector and pipeline utilities for composing time-series transformations in SQL.
• Upgrade tooling, SQL doctests, and packaging support for PostgreSQL extension releases.

Toolkit is pre-installed on Tiger Cloud and is included in the timescale/timescaledb-ha Docker image.

On a database where the extension is installed, enable it with:

CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit;

Then call Toolkit hyperfunctions from SQL:

SELECT
    average(stats_agg(value)) AS avg_value,
    approx_percentile(0.95, percentile_agg(value)) AS p95_value
FROM metrics;

For the full function reference, see the Toolkit documentation. For self-hosted package installation, see the Tiger Data guide to install Toolkit on self-hosted TimescaleDB.

Toolkit exposes APIs at different maturity levels:

• Stable APIs are intended to remain compatible across releases.
• Deprecated APIs remain available for now but are expected to be removed in a future release.
• Experimental APIs live in the toolkit_experimental schema. They may change, and extension upgrades may drop database objects that depend on them.

See the tag notes for the precise rules. Treat the experimental schema like an extension-development namespace, not a long-term application contract.

The project is regularly tested on:

• x86_64-unknown-linux-gnu on Ubuntu 24.04 before every merge.
• aarch64-unknown-linux-gnu on Ubuntu 24.04 at release time.
• x86_64-apple-darwin on macOS engineering workstations.
• aarch64-apple-darwin on macOS engineering workstations.

Other platforms may work. Patches are welcome.

You need:

• PostgreSQL 15, 16, 17, or 18, including server development headers.
• Rust 1.96.0 with rustfmt and clippy components. The repository includes a rust-toolchain.toml file for rustup.
• clang, make, gcc, pkg-config, and OpenSSL development libraries.
• cargo-pgrx 0.18.1.

On Ubuntu, after configuring the PostgreSQL apt repository, install the common build dependencies with:

sudo apt-get install make gcc pkg-config clang postgresql-server-dev-18 libssl-dev

Install the matching pgrx CLI:

cargo install cargo-pgrx --version 0.18.1 --locked --force

Initialize pgrx for the PostgreSQL version you want to target:

cargo pgrx init --pg18 pg_config

If you update the Rust compiler, reinstall cargo-pgrx with the same compiler.

Clone the repository and install the extension into the PostgreSQL installation reported by pg_config:

git clone https://github.com/timescale/timescaledb-toolkit.git
cd timescaledb-toolkit/extension

cargo pgrx install --release
cargo run --manifest-path ../tools/post-install/Cargo.toml -- pg_config

To build for a non-default PostgreSQL feature, disable default features and select the target version:

cargo pgrx install --release --no-default-features --features pg17

After installation, connect with psql and create the extension:

CREATE EXTENSION timescaledb_toolkit;

On macOS, tools/test-mac can install Toolkit into a pgrx-managed PostgreSQL, ensure TimescaleDB is available, start the server, and open psql:

tools/test-mac -pg18

The Rust workspace contains the PostgreSQL extension in extension/, reusable aggregate and sketch crates in crates/, and release/test utilities in tools/.

Common commands:

# Run Rust crate tests that do not require PostgreSQL.
cargo test --workspace --exclude timescaledb_toolkit

# Run extension tests against a pgrx PostgreSQL target.
cargo pgrx test pg18

# Run clippy with the same shape used by project tooling.
tools/build clippy

# Run SQL documentation tests against a started pgrx server.
tools/build -pg18 test-doc

The helper script tools/build wraps several CI-style tasks:

tools/build -pg18 test-crates
tools/build -pg18 test-extension
tools/build -pg18 install
tools/build -pg18 test-doc

Issues and pull requests are welcome. Good contributions usually include:

• A clear description of the SQL behavior being added or changed.
• Tests for Rust-level logic and PostgreSQL extension behavior where applicable.
• Documentation updates in docs/ for user-visible functions.
• Upgrade-safety consideration for stable SQL objects, serialized aggregate states, and extension update scripts.

For new functionality, check the proposed-feature and feature-request labels before opening a new issue.

Release notes are published on the GitHub releases page, and the project changelog is maintained in Changelog.md.

Toolkit is a PostgreSQL extension, so compatibility is affected by PostgreSQL major version, extension SQL upgrade paths, serialized aggregate state layout, and TimescaleDB integration points such as continuous aggregates.

Unless otherwise stated, source code and binaries built from this repository are licensed under the Timescale License. See LICENSE and NOTICE for details.

Tiger Data builds TimescaleDB and Tiger Cloud for PostgreSQL workloads that need high-ingest time-series storage, operational analytics, and real-time querying. Learn more at tigerdata.com.