How to Install TimescaleDB on Ubuntu 26.04 (Step-by-Step)

TimescaleDB adds time series superpowers to PostgreSQL: automatic time partitioning, compression, continuous aggregates and retention policies, all while keeping standard SQL. This guide installs PostgreSQL and TimescaleDB on Ubuntu 26.04 LTS, tunes the configuration, creates your first hypertable, secures remote access and sets up backups.

Not sure TimescaleDB is the right choice? Read InfluxDB vs Prometheus vs TimescaleDB first.

Table of Contents

1. What You Will Build
2. Prerequisites
3. Choosing Versions
4. Step 1: Update the System
5. Step 2: Add the PostgreSQL (PGDG) Repository
6. Step 3: Add the TimescaleDB Repository
7. Step 4: Install PostgreSQL and TimescaleDB
8. Step 5: Tune and Enable the Extension
9. Step 6: Create a Database, User and Hypertable
10. Step 7: Compression, Retention and Continuous Aggregates
11. Step 8: Enable Secure Remote Access
12. Step 9: Connect Grafana and Telegraf
13. Backup and Restore
14. Upgrading TimescaleDB
15. Alternative: Docker
16. Useful Commands
17. Troubleshooting
18. FAQ
19. Conclusion

---

1. What You Will Build

  ┌────────────┐  INSERT / COPY     ┌───────────────────────────────────────┐
  │ Apps, IoT, │ ─────────────────► │ Ubuntu 26.04 LTS                      │
  │ Telegraf   │   (scram-sha-256)  │                                       │
  └────────────┘                    │  ┌─────────────────────────────────┐  │
                                    │  │ PostgreSQL :5432                │  │
  ┌────────────┐   SQL              │  │  └─ TimescaleDB extension       │  │
  │ Grafana /  │ ◄───────────────── │  │      ├─ hypertable "conditions" │  │
  │ BI / psql  │                    │  │      │    └─ chunks (by time)   │  │
  └────────────┘                    │  │      ├─ compression policy      │  │
                                    │  │      ├─ retention policy        │  │
  ┌────────────┐                    │  │      └─ continuous aggregates   │  │
  │ Backups    │ ◄── pg_dump ────── │  └─────────────────────────────────┘  │
  └────────────┘                    └───────────────────────────────────────┘

2. Prerequisites

Requirement	Recommendation
OS	Ubuntu 26.04 LTS
CPU / RAM	2 vCPU and 4 GB RAM minimum for a lab; size RAM to your working set in production
Disk	SSD storage; keep the data directory on its own volume for production
Access	A user with sudo privileges
Network	Outbound HTTPS to apt.postgresql.org and packagecloud.io

3. Choosing Versions

TimescaleDB packages are built per PostgreSQL major version, and a given TimescaleDB release supports only certain PostgreSQL versions. Ubuntu’s own repositories and the official PostgreSQL (PGDG) repository may offer different majors. Decide the PostgreSQL version first, then confirm TimescaleDB supports it.

Item	Guidance
PostgreSQL major	Choose a version listed as supported in Timescale’s installation docs. Newer majors are sometimes supported a few releases after PostgreSQL ships them.
Package name	timescaledb-2-postgresql-<major>
Editions	The community edition includes compression, continuous aggregates and more under the Timescale License; the Apache 2 edition has fewer features. Self-hosting the community edition is free.

The commands below use a shell variable, so you only change one line:

export PG_VER=17      # set to a PostgreSQL major supported by the current TimescaleDB release

4. Step 1: Update the System

sudo apt update && sudo apt upgrade -y
sudo apt install -y gnupg postgresql-common apt-transport-https lsb-release wget curl ca-certificates
sudo timedatectl set-ntp true

Accurate time matters for time series data, so confirm NTP is active with timedatectl status.

5. Step 2: Add the PostgreSQL (PGDG) Repository

The postgresql-common package ships a helper script that configures the official PostgreSQL repository for your release:

sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y

This gives you access to several PostgreSQL major versions side by side, which is useful because TimescaleDB may support a version different from the newest one.

6. Step 3: Add the TimescaleDB Repository

echo "deb [signed-by=/usr/share/keyrings/timescaledb.gpg] https://packagecloud.io/timescale/timescaledb/ubuntu/ $(lsb_release -c -s) main" \
  | sudo tee /etc/apt/sources.list.d/timescaledb.list

wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/timescaledb.gpg

sudo apt update

Verify that the package is visible:

apt-cache policy timescaledb-2-postgresql-${PG_VER}

If nothing is found: Timescale publishes packages per Ubuntu codename, and a brand new release can lag behind. If apt update reports that the repository has no Release file for your codename, or the package does not appear, use the Docker method in Section 15 until packages are published.

7. Step 4: Install PostgreSQL and TimescaleDB

sudo apt install -y postgresql-${PG_VER} timescaledb-2-postgresql-${PG_VER} postgresql-client-${PG_VER}

On Debian-based systems, PostgreSQL starts automatically after installation. Confirm the cluster is online:

pg_lsclusters
sudo systemctl status postgresql --no-pager

Expected output shows the cluster as online on port 5432.

8. Step 5: Tune and Enable the Extension

TimescaleDB must be preloaded by PostgreSQL. The bundled timescaledb-tune utility edits postgresql.conf for you, adding shared_preload_libraries = 'timescaledb' and sizing memory and worker settings based on your hardware.

sudo timescaledb-tune --quiet --yes
sudo systemctl restart postgresql

If it cannot find your configuration file automatically, point it there:

sudo timescaledb-tune --conf-path=/etc/postgresql/${PG_VER}/main/postgresql.conf --quiet --yes

Review what changed:

sudo grep -nE "shared_preload_libraries|shared_buffers|effective_cache_size|max_worker_processes|timescaledb" \
  /etc/postgresql/${PG_VER}/main/postgresql.conf

Set the postgres superuser password and verify the extension is available:

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'ChangeMe_UseALongPassword!';"
sudo -u postgres psql -c "SELECT name, default_version FROM pg_available_extensions WHERE name = 'timescaledb';"

9. Step 6: Create a Database, User and Hypertable

Never build applications on the postgres superuser. Create a dedicated database and role:

sudo -u postgres psql <<'SQL'
CREATE ROLE tsuser WITH LOGIN PASSWORD 'AnotherStrongPassword!';
CREATE DATABASE metrics OWNER tsuser;
\c metrics
CREATE EXTENSION IF NOT EXISTS timescaledb;
SQL

CREATE EXTENSION requires superuser rights, so it is done here as postgres. The application role then owns the database and its tables.

Connect as the new user and confirm the extension:

psql -h 127.0.0.1 -U tsuser -d metrics

\dx
SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';

Create a regular table, then convert it

CREATE TABLE conditions (
    time        TIMESTAMPTZ       NOT NULL,
    device_id   TEXT              NOT NULL,
    temperature DOUBLE PRECISION,
    humidity    DOUBLE PRECISION
);

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

CREATE INDEX ON conditions (device_id, time DESC);

A hypertable looks like one normal table but is automatically split into chunks by time range. Queries and inserts stay ordinary SQL, while PostgreSQL only touches the relevant chunks.

Insert and query sample data

INSERT INTO conditions (time, device_id, temperature, humidity)
SELECT t, 'sensor-' || (1 + (random()*4)::int),
       20 + random()*10, 40 + random()*20
FROM generate_series(now() - interval '7 days', now(), interval '1 minute') AS t;

SELECT time_bucket('1 hour', time) AS hour,
       device_id,
       round(avg(temperature)::numeric, 2) AS avg_temp
FROM conditions
WHERE time > now() - interval '24 hours'
GROUP BY hour, device_id
ORDER BY hour DESC, device_id
LIMIT 10;

time_bucket() is the TimescaleDB function you will use constantly. It works like date_trunc but supports arbitrary intervals such as 5 minutes or 15 minutes.

10. Step 7: Compression, Retention and Continuous Aggregates

These three features are what make TimescaleDB practical for long-term data.

Compression

ALTER TABLE conditions SET (
    timescaledb.compress,
    timescaledb.compress_segmentby = 'device_id',
    timescaledb.compress_orderby   = 'time DESC'
);

SELECT add_compression_policy('conditions', INTERVAL '7 days');

Chunks older than 7 days are compressed automatically in the background. Compression can shrink time series data dramatically, though the ratio depends on your data.

Recent TimescaleDB releases are renaming this feature to columnstore and introducing new command names. The commands above may still work as aliases, but check the documentation for your installed version.

Retention

SELECT add_retention_policy('conditions', INTERVAL '90 days');

Dropping whole old chunks is fast and avoids the heavy DELETE and vacuum cost of ordinary tables.

Continuous aggregates (automatic rollups)

CREATE MATERIALIZED VIEW conditions_hourly
WITH (timescaledb.continuous) AS
SELECT time_bucket('1 hour', time) AS bucket,
       device_id,
       avg(temperature) AS avg_temp,
       max(temperature) AS max_temp
FROM conditions
GROUP BY bucket, device_id
WITH NO DATA;

SELECT add_continuous_aggregate_policy('conditions_hourly',
    start_offset      => INTERVAL '3 hours',
    end_offset        => INTERVAL '1 hour',
    schedule_interval => INTERVAL '1 hour');

CALL refresh_continuous_aggregate('conditions_hourly', NULL, NULL);

Dashboards can now query conditions_hourly instead of scanning raw data, which is far faster for long time ranges.

Feature	Purpose	Key function
Hypertable	Automatic time partitioning	create_hypertable()
Compression	Reduce storage for older chunks	add_compression_policy()
Retention	Drop data past its useful life	add_retention_policy()
Continuous aggregate	Incrementally maintained rollups	add_continuous_aggregate_policy()
Time bucketing	Group by arbitrary time windows	time_bucket()

11. Step 8: Enable Secure Remote Access

By default PostgreSQL listens only on localhost. To allow application servers to connect:

1. Listen on the server address. Edit /etc/postgresql/${PG_VER}/main/postgresql.conf:

listen_addresses = 'localhost,10.10.10.5'     # replace with the server's private IP
password_encryption = scram-sha-256

2. Allow only specific clients. Edit /etc/postgresql/${PG_VER}/main/pg_hba.conf:

# TYPE   DATABASE   USER     ADDRESS           METHOD
hostssl  metrics    tsuser   10.10.10.0/24     scram-sha-256

3. Restart and open the firewall for the trusted subnet only:

sudo systemctl restart postgresql
sudo ufw allow OpenSSH
sudo ufw allow from 10.10.10.0/24 to any port 5432 proto tcp
sudo ufw enable

4. Use TLS. Ubuntu’s PostgreSQL package generates a self-signed certificate (the “snakeoil” certificate) and enables ssl = on by default. For production, replace it with a certificate from your CA by setting ssl_cert_file and ssl_key_file, and connect with sslmode=verify-full.

Test from a client machine:

psql "host=10.10.10.5 dbname=metrics user=tsuser sslmode=require"

Never expose port 5432 to the public internet. Keep it inside a private network or behind a VPN.

12. Step 9: Connect Grafana and Telegraf

Grafana

Add a PostgreSQL data source (not a separate TimescaleDB type) and turn on the TimescaleDB toggle so Grafana can use time bucket macros.

Setting	Value
Host	10.10.10.5:5432
Database	metrics
User	A read-only role, for example grafana_ro
TLS/SSL mode	require or verify-full
TimescaleDB	Enabled

Create a read-only role for dashboards:

CREATE ROLE grafana_ro WITH LOGIN PASSWORD 'ReadOnlyStrongPassword!';
GRANT CONNECT ON DATABASE metrics TO grafana_ro;
GRANT USAGE ON SCHEMA public TO grafana_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO grafana_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO grafana_ro;

A typical Grafana panel query:

SELECT $__timeGroupAlias(time, $__interval),
       device_id AS metric,
       avg(temperature) AS temperature
FROM conditions
WHERE $__timeFilter(time)
GROUP BY 1, 2
ORDER BY 1;

Telegraf (optional)

Telegraf includes a PostgreSQL output plugin that can write metrics to TimescaleDB. Configure it with a connection string that points to your database, and consult the plugin documentation for its TimescaleDB-specific table templates.

13. Backup and Restore

Logical backup with pg_dump

sudo mkdir -p /backup/timescaledb && sudo chown postgres: /backup/timescaledb
sudo -u postgres pg_dump -Fc -d metrics -f /backup/timescaledb/metrics-$(date +%F).dump

Restore

TimescaleDB requires special handling when restoring a dump into a new database:

sudo -u postgres createdb metrics_restored
sudo -u postgres psql -d metrics_restored <<'SQL'
CREATE EXTENSION IF NOT EXISTS timescaledb;
SELECT timescaledb_pre_restore();
SQL

sudo -u postgres pg_restore -Fc -d metrics_restored /backup/timescaledb/metrics-2026-09-21.dump

sudo -u postgres psql -d metrics_restored -c "SELECT timescaledb_post_restore();"

Some errors about already-existing extension objects can appear during restore and are expected. Always test a restore on a spare server before you rely on it.

Nightly schedule and off-host copy

sudo tee /etc/cron.d/timescaledb-backup > /dev/null <<'EOF'
30 2 * * * postgres pg_dump -Fc -d metrics -f /backup/timescaledb/metrics-$(date +\%F).dump && find /backup/timescaledb -name '*.dump' -mtime +7 -delete
EOF

For large databases, physical backups with pg_basebackup plus WAL archiving (or a tool such as pgBackRest) allow point-in-time recovery and are faster than pg_dump.

14. Upgrading TimescaleDB

sudo apt update
sudo apt install --only-upgrade timescaledb-2-postgresql-${PG_VER}
sudo systemctl restart postgresql

After the package upgrade, update the extension inside each database. Run this in a fresh session using the -X flag so no startup files interfere:

sudo -u postgres psql -X -d metrics -c "ALTER EXTENSION timescaledb UPDATE;"

Always take a backup first, and read the release notes before upgrading across major changes.

15. Alternative: Docker

Docker is a good fallback when the APT repository does not yet support your Ubuntu release, and it is handy for labs. See Docker on Ubuntu 26.04 (verify slug) for installing Docker itself.

docker run -d --name timescaledb --restart unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_PASSWORD='ChangeMe_UseALongPassword!' \
  -v timescaledb_data:/var/lib/postgresql/data \
  timescale/timescaledb:latest-pg17

Check the image tags on Docker Hub for the versions currently published, pin an exact tag in production, and note that the data path for newer PostgreSQL images can differ by version. The container image ships with the extension available; run CREATE EXTENSION IF NOT EXISTS timescaledb; in your database.

16. Useful Commands

Task	Command
List clusters	pg_lsclusters
Service control	`sudo systemctl status
Main config	/etc/postgresql/${PG_VER}/main/postgresql.conf
Client auth rules	/etc/postgresql/${PG_VER}/main/pg_hba.conf
Log file	/var/log/postgresql/postgresql-${PG_VER}-main.log
Data directory	/var/lib/postgresql/${PG_VER}/main
List hypertables	SELECT * FROM timescaledb_information.hypertables;
List chunks	SELECT * FROM timescaledb_information.chunks;
List background jobs	SELECT * FROM timescaledb_information.jobs;
Hypertable size	SELECT hypertable_size('conditions');
Extension version	SELECT extversion FROM pg_extension WHERE extname='timescaledb';

17. Troubleshooting

Symptom	Likely cause	Fix
E: Unable to locate package timescaledb-2-postgresql-17	Repository missing, apt update not run, or wrong PG major	Recheck /etc/apt/sources.list.d/timescaledb.list, run apt update, confirm the supported PG version
Repository has no Release file for your codename	Timescale has not published packages for the new Ubuntu release yet	Wait, or use the Docker method in Section 15
could not access file "timescaledb": No such file or directory	Extension package not installed for that PG major	Install timescaledb-2-postgresql-<major> matching the running cluster
extension "timescaledb" must be preloaded	shared_preload_libraries not set or PostgreSQL not restarted	Run timescaledb-tune or add the setting manually, then restart
permission denied to create extension "timescaledb"	Not superuser	Run CREATE EXTENSION as postgres
pg_lsclusters shows down	Config error or port conflict	Read /var/log/postgresql/postgresql-${PG_VER}-main.log
FATAL: no pg_hba.conf entry for host	Client not allowed in pg_hba.conf	Add a matching hostssl line and reload PostgreSQL
Remote connection refused	listen_addresses still localhost, or firewall closed	Set the server IP, restart, and allow port 5432 from the client subnet
password authentication failed	Wrong password or old MD5 hash after changing encryption	Reset the password after setting password_encryption = scram-sha-256
Restore fails or hangs on TimescaleDB objects	Restore run without pre/post restore functions	Follow the timescaledb_pre_restore() and timescaledb_post_restore() sequence in Section 13
ALTER EXTENSION UPDATE has no effect	Old library loaded in an existing session	Restart PostgreSQL, then run the update in a new session with psql -X
Compression policy does not run	Background workers too few	Check timescaledb_information.jobs and max_worker_processes
Queries scan too many chunks	Time filter missing in the WHERE clause	Always filter on the time column, and check the query plan with EXPLAIN

18. FAQ

Is TimescaleDB free?
Yes for self-hosting the community edition. Some features fall under the Timescale License rather than Apache 2, which restricts offering the software as a competing managed database service. Timescale also sells a managed cloud service.

Do I need to change my application to use TimescaleDB?
Barely. It is standard PostgreSQL, so existing drivers, ORMs and SQL continue to work. You convert tables to hypertables and use extra functions such as time_bucket where they help.

Can I convert an existing table with data into a hypertable?
Yes, using create_hypertable(..., migrate_data => true), although large tables can take time and locks. Test on a copy first.

How much RAM should I give it?
Start with what timescaledb-tune recommends for your machine, then monitor cache hit ratio and adjust. Time series workloads benefit from memory that holds the most recent chunks.

Which is better, TimescaleDB or InfluxDB?
It depends on your workload and skills. TimescaleDB fits teams that want SQL and joins with relational data; InfluxDB fits teams that want a purpose-built store with its own UI. See the full comparison.

Does it support high availability?
Since it is PostgreSQL, you can use streaming replication and standard HA tooling such as Patroni. Test failover procedures before going to production.

19. Conclusion

You now have PostgreSQL with TimescaleDB running on Ubuntu 26.04, tuned for your hardware, with a hypertable, compression, retention and continuous aggregates configured, secure remote access, Grafana connectivity and a tested backup approach. Next steps worth taking are setting retention that matches your business needs, building continuous aggregates for your most common dashboard queries, and putting monitoring on PostgreSQL itself.