Upgrade TimescaleDB to a new minor version

Tiger Cloud: Performance, Scale, Enterprise

Self-hosted products

MST

A minor upgrade is when you update from TimescaleDB <major version>.x to TimescaleDB <major version>.y. A major upgrade is when you update from TimescaleDB X.<minor version> to Y.<minor version>.
You can run different versions of TimescaleDB on different databases within the same Postgres instance. This process uses the Postgres ALTER EXTENSION function to upgrade TimescaleDB independently on different databases.

Try for free on Tiger Cloud

Tiger Cloud is a fully managed service with automatic backup and restore, high availability with replication, seamless scaling and resizing, and much more. You can try Tiger Cloud free for thirty days.

Try for free

This page shows you how to perform a minor upgrade, for major upgrades, see Upgrade TimescaleDB to a major version.

Prerequisites

Install the Postgres client tools on your migration machine. This includes psql, and pg_dump.
Read the release notes for the version of TimescaleDB that you are upgrading to.
Perform a backup of your database. While TimescaleDB upgrades are performed in-place, upgrading is an intrusive operation. Always make sure you have a backup on hand, and that the backup is readable in the case of disaster.

Check the TimescaleDB and Postgres versions

To see the versions of Postgres and TimescaleDB running in a self-hosted database instance:

Set your connection string
This variable holds the connection information for the database to upgrade:
```
export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
```

Retrieve the version of Postgres that you are running


psql -X -d $SOURCE -c "SELECT version();"

Postgres returns something like:


-----------------------------------------------------------------------------------------------------------------------------------------
PostgreSQL 17.2 (Ubuntu 17.2-1.pgdg22.04+1) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit
(1 row)

Retrieve the version of TimescaleDB that you are running


psql -X -d $SOURCE -c "\dx timescaledb;"

Postgres returns something like:


Name     | Version |   Schema   |                             Description
-------------+---------+------------+---------------------------------------------------------------------
timescaledb | 2.17.2   | public     | Enables scalable inserts and complex queries for time-series data
(1 row)

Plan your upgrade path

Best practice is to always use the latest version of TimescaleDB. Subscribe to our releases on GitHub or use Tiger Cloud and always run the latest update without any hassle.

Check the following support matrix against the versions of TimescaleDB and Postgres that you are running currently and the versions you want to update to, then choose your upgrade path.

For example, to upgrade from TimescaleDB 2.13 on Postgres 13 to TimescaleDB 2.18.2 you need to:

Upgrade TimescaleDB to 2.15
Upgrade Postgres to 14, 15 or 16.
Upgrade TimescaleDB to 2.18.2.

You may need to upgrade to the latest Postgres version before you upgrade TimescaleDB. Also, if you use TimescaleDB Toolkit, ensure the timescaledb_toolkit extension is >=
v1.6.0 before you upgrade TimescaleDB extension.

TimescaleDB version	Postgres 17	Postgres 16	Postgres 15	Postgres 14	Postgres 13	Postgres 12	Postgres 11	Postgres 10
2.21.x	✅	✅	✅	❌	❌	❌	❌	❌
2.20.x	✅	✅	✅	❌	❌	❌	❌	❌
2.17 - 2.19	✅	✅	✅	✅	❌	❌	❌	❌
2.16.x	❌	✅	✅	✅	❌	❌	❌	❌
2.13 - 2.15	❌	✅	✅	✅	✅	❌	❌	❌
2.12.x	❌	❌	✅	✅	✅	❌	❌	❌
2.10.x	❌	❌	✅	✅	✅	✅	❌	❌
2.5 - 2.9	❌	❌	❌	✅	✅	✅	❌	❌
2.4	❌	❌	❌	❌	✅	✅	❌	❌
2.1 - 2.3	❌	❌	❌	❌	✅	✅	✅	❌
2.0	❌	❌	❌	❌	❌	✅	✅	❌
1.7	❌	❌	❌	❌	❌	✅	✅	✅

We recommend not using TimescaleDB with Postgres 17.1, 16.5, 15.9, 14.14, 13.17, 12.21.
These minor versions introduced a breaking binary interface change that, once identified, was reverted in subsequent minor Postgres versions 17.2, 16.6, 15.10, 14.15, 13.18, and 12.22. When you build from source, best practice is to build with Postgres 17.2, 16.6, etc and higher. Users of Tiger Cloud and platform packages for Linux, Windows, MacOS, Docker, and Kubernetes are unaffected.

Implement your upgrade path

You cannot upgrade TimescaleDB and Postgres at the same time. You upgrade each product in the following steps:

Upgrade TimescaleDB


psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"

If your migration path dictates it, upgrade Postgres
Follow the procedure in Upgrade Postgres. The version of TimescaleDB installed in your Postgres deployment must be the same before and after the Postgres upgrade.

If your migration path dictates it, upgrade TimescaleDB again


psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"

Check that you have upgraded to the correct version of TimescaleDB


psql -X -d $SOURCE -c "\dx timescaledb;"

Postgres returns something like:


Name     | Version | Schema |                                      Description                                      
-------------+---------+--------+---------------------------------------------------------------------------------------
timescaledb | 2.17.2  | public | Enables scalable inserts and complex queries for time-series data (Community Edition)

You are running a shiny new version of TimescaleDB.

Upgrade TimescaleDB to a new minor version

Try for free on Tiger Cloud

Prerequisites

Check the TimescaleDB and Postgres versions

Plan your upgrade path

Implement your upgrade path

Related Content