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 a pre-built container.

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 Install and configure TimescaleDB on PostgreSQL.

To connect to a PostgreSQL installation on Docker, you need to install:

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

  1. At the command prompt, run the TimescaleDB Docker image:

    docker pull timescale/timescaledb-ha:pg16

    In this image, the timescaledb extension is pre-created in the default postgres database in both the -ha and non-ha docker images. By default, timescaledb is added to any new database you create in these images.

  1. Run the container:

    docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg16

    If you are running multiple container instances remember to change the port each Docker instance runs on.

  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. 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.

The TimescaleDB HA Docker image includes Ubuntu as its operating system and offers the most complete TimescaleDB experience. It includes the TimescaleDB Toolkit, and support for PostGIS and Patroni. The lighter-weight TimescaleDB (non-HA) timescale/timescaledb:latest-pg16 image uses Alpine.

Warning

If your system uses Linux Uncomplicated Firewall (UFW) for security rules, Docker could override your UFW port binding settings. Docker binds the container on Unix-based systems by modifying the Linux IP tables. If you are relying on UFW rules for network security, consider adding DOCKER_OPTS="--iptables=false" to /etc/default/docker to prevent Docker from overwriting the IP tables. For more information about this vulnerability, see Docker's information about the UFW flaw.

If you want to run the image directly from the container, you can use this command:

docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg16

The -p flag binds the container port to the host port. This means that anything that can access the host port can also access your TimescaleDB container, so it's important that you set a PostgreSQL password using the POSTGRES_PASSWORD environment variable. Without that variable, the Docker container disables password checks for all database users.

If you want to access the container from the host but avoid exposing it to the outside world, you can bind to 127.0.0.1 instead of the public interface, using this command:

docker run -d --name timescaledb -p 127.0.0.1:5432:5432 \
-e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg16

If you don't want to install psql and other PostgreSQL client tools locally, or if you are using a Microsoft Windows host system, you can connect using the version of psql that is bundled within the container with this command:

docker exec -it timescaledb psql -U postgres

Existing containers can be stopped using docker stop and started again with docker start while retaining their volumes and data. When you create a new container using the docker run command, by default you also create a new data volume. When you remove a Docker container with docker rm the data volume persists on disk until you explicitly delete it. You can use the docker volume ls command to list existing docker volumes. If you want to store the data from your Docker container in a host directory, or you want to run the Docker image on top of an existing data directory, you can specify the directory to mount a data volume using the -v flag.

Warning

The two container types store PostgreSQL data dir in different places, make sure you select the correct one to mount:

ContainerPGDATA location
timescaledb-ha/home/postgres/pgdata/data
timescaledb/var/lib/postgresql/data
docker run -d --name timescaledb -p 5432:5432 \
-v /your/data/dir:/home/postgres/pgdata/data \
-e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg16

When you install TimescaleDB using a Docker container, the PostgreSQL settings are inherited from the container. In most cases, you do not need to adjust them. However, if you need to change a setting you can add -c setting=value to your Docker run command. For more information, see the Docker documentation.

The link provided in these instructions is for the latest version of TimescaleDB on PostgreSQL 16. To find other Docker tags you can use, see the Dockerhub repository.

If you have TimescaleDB installed in a Docker container, you can view your logs using Docker, instead of looking in /var/lib/logs or /var/logs. For more information, see the Docker documentation on logs.

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.