How to Install TimescaleDB: A Comprehensive Step-by-Step Guide

TimescaleDB is a powerful open-source time-series database built as an extension on PostgreSQL. It enhances PostgreSQL with capabilities to handle time-series data efficiently, making it ideal for monitoring, IoT, financial data, and more.

Prerequisites

A machine running Linux (Ubuntu/Debian recommended) or macOS. Windows users should consider WSL (Windows Subsystem for Linux) or Docker.
PostgreSQL installed and running (version 11 or later recommended).
Basic command-line knowledge.
Internet access to fetch packages and repository keys.

Step 1: Install PostgreSQL (If Not Already Installed)

If you don’t have PostgreSQL installed, run the following commands for Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify the installation:

psql --version

Step 2: Add TimescaleDB’s Repository and Its GPG Key

TimescaleDB provides an APT repository for easy installation. Run the following commands to add the repository for Ubuntu 22.04 as an example (adjust for your distro):

sudo add-apt-repository "deb https://packagecloud.io/timescale/timescaledb/ubuntu/ jammy main"
wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo apt-key add -
sudo apt update

Step 3: Install TimescaleDB Extension

Now install the TimescaleDB extension package:

sudo apt install timescaledb-postgresql-14

Replace 14 with your PostgreSQL major version if different.

Step 4: Configure PostgreSQL to Use TimescaleDB

Edit PostgreSQL configuration to preload TimescaleDB:

sudo nano /etc/postgresql/14/main/postgresql.conf

Find the line starting with shared_preload_libraries and update it as follows:

shared_preload_libraries = 'timescaledb'

Save and exit the file, then restart PostgreSQL:

sudo systemctl restart postgresql

Step 5: Enable TimescaleDB in Your Database

Connect to your PostgreSQL instance:

sudo -u postgres psql

Create a database (optional, or use existing):

CREATE DATABASE my_timescaledb;
\c my_timescaledb

Enable TimescaleDB extension:

CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;

Verify TimescaleDB is enabled:

\dx

Troubleshooting Tips

Issue: TimescaleDB extension does not load after restart.
Solution: Check that the PostgreSQL version matches the TimescaleDB package version and that shared_preload_libraries is correctly set.
Issue: Missing GPG key error when adding repository.
Solution: Verify network connectivity and that the key URL is correct.
Issue: Permission issues running psql commands.
Solution: Use sudo -u postgres or configure user access in PostgreSQL accordingly.

Summary Checklist

PostgreSQL installed and running (version 11+)
TimescaleDB APT repo added and updated
TimescaleDB package installed compatible with PostgreSQL version
PostgreSQL configured with shared_preload_libraries='timescaledb'
PostgreSQL restarted to apply changes
TimescaleDB extension enabled in your database
Tested extension with \dx command inside psql

For a detailed step-by-step on installing other databases, check our guide on How to Install OrientDB: Step-by-Step Tutorial.

By following these instructions, you can harness the power of TimescaleDB for efficient time-series data management on your system. Enjoy your journey with this robust, scalable time-series database!