Upgrade PostgreSQL

TimescaleDB is a PostgreSQL extension. Ensure that you upgrade to compatible versions of TimescaleDB and PostgreSQL.

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

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.

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.

Upgrade your PostgreSQL instance

You use pg_upgrade to upgrade PostgreSQL in-place. pg_upgrade allows you to retain the data files of your current PostgreSQL installation while binding the new PostgreSQL binary runtime to them.

Find the location of the PostgreSQL binary
Set the OLD_BIN_DIR environment variable to the folder holding the postgres binary. For example, which postgres returns something like /usr/lib/postgresql/16/bin/postgres.
```
export OLD_BIN_DIR=/usr/lib/postgresql/16/bin
```
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 location of the PostgreSQL data folder
Set the OLD_DATA_DIR environment variable to the value returned by the following:
```
psql -d "$SOURCE" -c "SHOW data_directory ;"
```
PostgreSQL returns something like:
```
----------------------------
/home/postgres/pgdata/data
(1 row)
```

Choose the new locations for the PostgreSQL binary and data folders

For example:


export NEW_BIN_DIR=/usr/lib/postgresql/17/bin
export NEW_DATA_DIR=/home/postgres/pgdata/data-17

Using psql, perform the upgrade:


pg_upgrade -b $OLD_BIN_DIR -B $NEW_BIN_DIR -d $OLD_DATA_DIR -D $NEW_DATA_DIR

If you are moving data to a new physical instance of PostgreSQL, you can use pg_dump and pg_restore to dump your data from the old database, and then restore it into the new, upgraded, database. For more information, see the backup and restore section.

Upgrade PostgreSQL

Try for free on Timescale

Prerequisites

Plan your upgrade path

Upgrade your PostgreSQL instance

Related Content