# Self-Hosted TimescaleDB Installation & Configuration Guide

This document provides step-by-step instructions to install and configure TimescaleDB on your self-hosted PostgreSQL server. We'll walk you through the necessary configurations to ensure a smooth setup.

# Introduction

TimescaleDB is an open-source PostgreSQL extension designed for running real-time analytics on time-series data. It provides automatic partitioning of data across time, making it ideal for IoT data, application metrics, financial data, and other time-series use cases.

This guide assumes you have already installed and configured PostgreSQL. If you need to install PostgreSQL first, refer to the PostgreSQL Database Setup Guide (opens new window).

# Prerequisites

Before installing TimescaleDB, ensure you have:

  • PostgreSQL 14, 15, 16, 17, or 18 installed and running
  • Root or sudo access (Linux/macOS)
  • psql command-line client available
  • Internet connection for package downloads

# Step 1: Install TimescaleDB

Select your operating system below to see the installation instructions.

    # Step 2: Enable TimescaleDB Extension

    After installation, enable TimescaleDB on your database:

    1. Connect to your database:
    psql -d "postgres://username:password@host:port/database_name"
    1
    1. Add TimescaleDB to the database:
    CREATE EXTENSION IF NOT EXISTS timescaledb;
    1
    1. Check that TimescaleDB is installed:
    \dx
    1

    Expected output:

                                           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...
    1
    2
    3
    4
    5

    # Step 3: Verify Installation

    # Check TimescaleDB version

    SELECT * FROM timescaledb_version();
    1

    # Check installed extensions

    SELECT extname, extversion FROM pg_extension WHERE extname = 'timescaledb';
    1

    # Create a sample hypertable

    -- Create a sample table
CREATE TABLE sensor_data (
    time TIMESTAMPTZ NOT NULL,
    sensor_id INTEGER NOT NULL,
    temperature DOUBLE PRECISION,
    humidity DOUBLE PRECISION
);

-- Convert to hypertable
SELECT create_hypertable('sensor_data', 'time');

-- Insert sample data
INSERT INTO sensor_data (time, sensor_id, temperature, humidity)
VALUES
    (NOW(), 1, 22.5, 45.0),
    (NOW() - INTERVAL '1 hour', 1, 21.8, 46.2),
    (NOW() - INTERVAL '2 hours', 1, 20.5, 48.1);

-- Query the data
SELECT * FROM sensor_data ORDER BY time DESC;
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

    # Post-Installation Configuration

    # Tune PostgreSQL settings

    Run the TimescaleDB tuning tool:

    sudo timescaledb-tune
    1

    This will optimize PostgreSQL settings for TimescaleDB workloads, including:

    • shared_preload_libraries
    • shared_buffers
    • work_mem
    • maintenance_work_mem
    • And other performance-critical parameters

    # Configure shared_preload_libraries

    If timescaledb-tune did not add TimescaleDB to shared_preload_libraries, manually edit postgresql.conf:

    shared_preload_libraries = 'timescaledb'
    1

    # Restart PostgreSQL

      # Troubleshooting

      # Common Issues

      "extension timescaledb does not exist"

      Ensure shared_preload_libraries = 'timescaledb' is set in postgresql.conf and restart PostgreSQL.

      "could not load library timescaledb.dll" (Windows)

      Ensure OpenSSL v3.x is installed and in your PATH.

      Connection refused

      Verify PostgreSQL is running:

      sudo systemctl status postgresql
      1

      Permission denied

      Ensure the PostgreSQL user has CREATEDB privileges:

      ALTER USER postgres CREATEDB;
      1

      # References

      # Version Information

      Component Version
      TimescaleDB 2.24.0+
      PostgreSQL 14, 15, 16, 17, 18
      Docker Images pg14, pg15, pg16, pg17, pg18

      ← AWS S3 Storage →