Upgrade TimescaleDB to a new minor version

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 PostgreSQL instance. This process uses the PostgreSQL ALTER EXTENSION function to upgrade TimescaleDB independently on different databases.

Try for free on Timescale

Timescale is a fully managed service with automatic backup and restore, high availability with replication, seamless scaling and resizing, and much more. You can try Timescale 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 PostgreSQL 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 Timescale 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 PostgreSQL versions

To see the versions of PostgreSQL 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 PostgreSQL that you are running


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

PostgreSQL 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;"

PostgreSQL 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 Timescale Cloud and always get latest update without any hassle.

Check the following support matrix against the versions of TimescaleDB and PostgreSQL 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 PostgreSQL 13 to TimescaleDB 2.17.2 you need to:

Upgrade TimescaleDB to 2.16
Upgrade PostgreSQL to 14 or higher
Upgrade TimescaleDB to 2.17.2.

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

Version number	PostgreSQL 17	PostgreSQL 16	PostgreSQL 15	PostgreSQL 14	PostgreSQL 13	PostgreSQL 12	PostgreSQL 11	PostgreSQL 10
TimescaleDB 2.17.x	✅	✅	✅	✅	❌	❌	❌	❌
TimescaleDB 2.16.x	❌	✅	✅	✅	✅	❌	❌	❌
TimescaleDB 2.15.x	❌	✅	✅	✅	✅	❌	❌	❌
TimescaleDB 2.14.x	❌	✅	✅	✅	✅	❌	❌	❌
TimescaleDB 2.13.x	❌	✅	✅	✅	✅	❌	❌	❌
TimescaleDB 2.12.x	❌	❌	✅	✅	✅	❌	❌	❌
TimescaleDB 2.10.x	❌	❌	✅	✅	✅	✅	❌	❌
TimescaleDB 2.5 - 2.9	❌	❌	❌	✅	✅	✅	❌	❌
TimescaleDB 2.4	❌	❌	❌	❌	✅	✅	❌	❌
TimescaleDB 2.1 - 2.3	❌	❌	❌	❌	✅	✅	✅	❌
TimescaleDB 2.0	❌	❌	❌	❌	❌	✅	✅	❌
TimescaleDB 1.7	❌	❌	❌	❌	❌	✅	✅	✅

We recommend not using TimescaleDB with PostgreSQL 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 PostgreSQL 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 PostgreSQL 17.2, 16.6, etc and higher. Users of Timescale Cloud and platform packages for Linux, Windows, MacOS, Docker, and Kubernetes are unaffected.

Implement your upgrade path

You cannot upgrade TimescaleDB and PostgreSQL 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 PostgreSQL
Follow the procedure in Upgrade PostgreSQL. The version of TimescaleDB installed in your PostgreSQL deployment must be the same before and after the PostgreSQL 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;"

PostgreSQL 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 Timescale

Prerequisites

Check the TimescaleDB and PostgreSQL versions

Plan your upgrade path

Implement your upgrade path

Related Content