How to Install TimescaleDB Using Docker

May 09, 2025

TimescaleDB is an open-source time-series database powered by PostgreSQL. It's built to handle massive volumes of time-stamped data efficiently—perfect for applications like monitoring, IoT, analytics, and financial systems.
If you’re looking to try TimescaleDB quickly without installing it on your local system, Docker is the simplest and fastest way to get started. In this guide, you’ll learn how to install TimescaleDB using Docker, run it in a container, and connect to it using your favorite PostgreSQL tools.

Why Use Docker for TimescaleDB?

Docker lets you run databases like TimescaleDB in isolated containers, without cluttering your system. It’s:

Fast to set up and remove
Great for local testing and development
Cross-platform compatible
Easy to manage and restart

Prerequisites

Before we begin, make sure Docker is installed.

For macOS or Windows:

Install Docker Desktop:
👉 https://www.docker.com/products/docker-desktop

For Ubuntu/Linux:

sudo apt update && sudo apt install docker.io

Check if Docker is installed:

docker --version

Step 1: Pull the TimescaleDB Docker Image

Timescale maintains an official Docker image on Docker Hub.
Run this command to download the latest image:

docker pull timescale/timescaledb:latest-pg14

You can change pg14 to a different version if needed (e.g., pg13).

Step 2: Run TimescaleDB in a Docker Container

Start a container with the following command:

docker run -d \
  --name timescaledb \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  timescale/timescaledb:latest-pg14

Explanation:

--name timescaledb: names the container
-e POSTGRES_PASSWORD: sets the PostgreSQL root password
-p 5432:5432: maps the internal PostgreSQL port to your local machine
-d: runs the container in the background

This gives you a running TimescaleDB instance using PostgreSQL 14.

Step 3: Use Docker Volume (Optional but Recommended)

To keep your data safe between container restarts or removals, use a Docker volume:

docker volume create timescale-data

Then run the container with volume mounting:

docker run -d \
  --name timescaledb \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  -v timescale-data:/var/lib/postgresql/data \
  timescale/timescaledb:latest-pg14

This will ensure your database files are stored persistently.

Step 4: Connect to TimescaleDB

TimescaleDB is PostgreSQL-compatible, so you can connect using any PostgreSQL client.

Using `psql`:

psql -h localhost -p 5432 -U postgres

Enter the password you set (yourpassword), then run:

\l   -- list databases
\c postgres  -- connect to default db

Using a GUI (e.g., DBeaver, DataGrip, pgAdmin)

Use these connection settings:

Host: localhost
Port: 5432
User: postgres
Password: yourpassword
Database: postgres (default)

Once connected, you can start creating tables and time-series data.

Step 5: Create a Hypertable

In TimescaleDB, a hypertable is a time-partitioned table optimized for time-series data.

CREATE TABLE sensor_data (time TIMESTAMPTZ NOT NULL,
  sensor_id INT,
  temperature DOUBLE PRECISION
);

SELECT create_hypertable('sensor_data', 'time');

Then insert and query:

INSERT INTO sensor_data VALUES (now(), 1, 22.5);
SELECT * FROM sensor_data;

This shows how TimescaleDB behaves like PostgreSQL—but optimized for time-based analytics.

Step 6: Managing the Container

Here are some useful commands:

Task	Command
Stop the container	`docker stop timescaledb`
Start it again	`docker start timescaledb`
View logs	`docker logs timescaledb`
Remove container	`docker rm -f timescaledb`
Remove volume	`docker volume rm timescale-data`

Best Practices

Use Docker volumes to persist your data
Use strong passwords for security
Don’t expose the PostgreSQL port publicly without a firewall
Use the latest PostgreSQL version supported by TimescaleDB