TimescaleDB is a PostgreSQL extension for time series and demanding workloads that ingest and query high volumes of data. You can install a TimescaleDB instance on any local system, from source.

Want to skip these steps?

Deploy a Timescale service in the cloud. We tune your database for performance and handle scalability, high availability, backups and management so you can relax.

Try for free

This section shows you how to:

To install TimescaleDB from source, you need:

  • A supported version of PostgreSQL installed on your developer environment

    For PostgreSQL installation instructions, see the PostgreSQL documentation.

  • Build tools:

    • CMake version 3.11 or later

    • C language compiler for your operating system, such as gcc or clang.

      Note

      If you are using a Microsoft Windows system, you can install Visual Studio 2015 or later instead of CMake and a C language compiler. Ensure you install the Visual Studio components for CMake and Git when you run the installer.

This section shows you how to install the latest version of PostgreSQL and TimescaleDB on a supported platform using source supplied by Timescale.

  1. Install the latest PostgreSQL source

    1. At the command prompt, clone the TimescaleDB GitHub repository:

      git clone https://github.com/timescale/timescaledb
    2. Change into the cloned directory:

      cd timescaledb
    3. Checkout the latest release. You can find the latest release tag on our [Releases page][gh-releases]:

      git checkout 2.15.1

      This command produces an error that you are now in detached head state. It is expected behavior, and it occurs because you have checked out a tag, and not a branch. Continue with the steps in this procedure as normal.

  2. Build the source

    1. Bootstrap the build system:

      For installation on Microsoft Windows, you might need to add the pg_config and cmake file locations to your path. In the Windows Search tool, search for system environment variables. The path for pg_config should be C:\Program Files\PostgreSQL\<version>\bin. The path for cmake is within the Visual Studio directory.

    2. Build the extension:

  3. Install TimescaleDB

  4. Configure PostgreSQL

    If you have more than one version of PostgreSQL installed, TimescaleDB can only be associated with one of them. The TimescaleDB build scripts use pg_config to find out where PostgreSQL stores its extension files, so you can use pg_config to find out which PostgreSQL installation TimescaleDB is using.

    1. Locate the postgresql.conf configuration file:

      psql -d postgres -c "SHOW config_file;"
    2. Open the postgresql.conf file and update shared_preload_libraries to:

      shared_preload_libraries = 'timescaledb'

      If you use other preloaded libraries, make sure they are comma separated.

    3. Tune your PostgreSQL instance for TimescaleDB

      sudo timescaledb-tune

      This script is included with the timescaledb-tools package when you install TimescaleDB. For more information, see configuration.

    4. Restart the PostgreSQL instance:

  5. Set the user password

    1. Login to PostgreSQL as postgres

      sudo -u postgres psql

      You are in the psql shell.

    2. Set the password for postgres

      \password postgres

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

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:

    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 | Schema | Description
    -------------+---------+------------+---------------------------------------------------------------------------------------
    plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
    timescaledb | 2.15.1 | public | Enables scalable inserts and complex queries for time-series data (Community Edition)

    Press q to exit the list of extensions.

And that is it! You have TimescaleDB running on a database on a self-hosted instance of PostgreSQL.

Now you have TimescaleDB running, have a look at the:

  • Tutorials: walk through a variety of business scenarios using example datasets.
  • Use Timescale: browse the features available with TimescaleDB.

Keywords

Found an issue on this page?Report an issue or Edit this page in GitHub.