Skip to content
Search ⌘K
Get started

Install self-hosted TimescaleDB

Install TimescaleDB on Linux, macOS, Windows, Docker, Kubernetes, or from source

TimescaleDB is an open-source PostgreSQL extension that powers Tiger Cloud. Designed for running real-time analytics on time-series data, it supercharges ingest, query, storage, and analytics performance.

Note

The following instructions are for development and testing installations. For a production environment, we strongly recommend that you implement the following, many of which you can achieve using PostgreSQL tooling:

  • Incremental backup and database snapshots, with efficient point-in-time recovery.
  • High availability replication, ideally with nodes across multiple availability zones.
  • Automatic failure detection with fast restarts, for both non-replicated and replicated deployments.
  • Asynchronous replicas for scaling reads when needed.
  • Connection poolers for scaling client connections.
  • Zero-down-time minor version and extension upgrades.
  • Forking workflows for major version upgrades and other feature testing.
  • Monitoring and observability.

Install TimescaleDB based on your distribution.

Warning

If you have previously installed PostgreSQL, you may encounter errors following these install instructions. Best practice is to fully remove any existing PostgreSQL installations before you begin. To keep your current PostgreSQL installation, install from source.

  1. Install the latest PostgreSQL packages
    Terminal window
    sudo apt install gnupg postgresql-common apt-transport-https lsb-release wget
  2. Run the PostgreSQL package setup script
    Terminal window
    sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
  3. Add the TimescaleDB package
    Terminal window
    echo "deb https://packagecloud.io/timescale/timescaledb/debian/ $(lsb_release -c -s) main" | sudo tee /etc/apt/sources.list.d/timescaledb.list
  4. Install the TimescaleDB GPG key
    Terminal window
    wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/timescaledb.gpg
  5. Update your local repository list
    Terminal window
    sudo apt update
  6. Install TimescaleDB
    Terminal window
    sudo apt install timescaledb-2-postgresql-18 postgresql-client-18

    To install a specific TimescaleDB release, set the version. For example:

    sudo apt-get install timescaledb-2-postgresql-14='2.6.0*' timescaledb-2-loader-postgresql-14='2.6.0*'

    Older versions of TimescaleDB may not support all the OS versions listed on this page.

  7. Tune your PostgreSQL instance for TimescaleDB
    Terminal window
    sudo timescaledb-tune

    By default, this script is included with the timescaledb-tools package when you install TimescaleDB. Use the prompts to tune your development or production environment. For more information on manual configuration, see Configuration. If you have an issue, run sudo apt install timescaledb-tools.

  8. Restart PostgreSQL
    Terminal window
    sudo systemctl restart postgresql
  9. Log in to PostgreSQL as postgres
    Terminal window
    sudo -u postgres psql

    You are in the psql shell.

  10. Set the password for postgres
    Terminal window
    \password postgres

    When you have set the password, type \q to exit psql.

Add the TimescaleDB extension to your database

Section titled “Add the TimescaleDB extension to your database”

For improved performance, you enable TimescaleDB on each database on your self-hosted PostgreSQL instance. This section shows you how to enable TimescaleDB for a new database in PostgreSQL using psql from the command line.

  1. Connect to a database on your PostgreSQL instance

    In PostgreSQL, the default user and database are both postgres. To use a different database, set <database-name> to the name of that database:

    Terminal window
    psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"
  2. Add TimescaleDB to the database
    CREATE EXTENSION IF NOT EXISTS timescaledb;
  3. Check that TimescaleDB is installed
    \dx

    You see the list of installed extensions:

                                                             List of installed extensions
    Name     | Version | Default version |   Schema   |                                      Description
    -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
    plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
    timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
    (2 rows)

    Press \q to exit the list of extensions.

Supported platforms

Section titled “Supported platforms”
Operation systemVersion
Debian13 Trixe, 12 Bookworm, 11 Bullseye
Ubuntu24.04 Noble Numbat, 22.04 LTS Jammy Jellyfish
Red Hat EnterpriseLinux 9, Linux 8
FedoraFedora 35, Fedora 34, Fedora 33
Rocky LinuxRocky Linux 9 (x86_64), Rocky Linux 8
ArchLinux (community-supported)Check the available packages