Upgrade Postgres

Tiger Cloud: Performance, Scale, Enterprise

Self-hosted products

MST

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

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

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.

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.

Upgrade your Postgres instance

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

Find the location of the Postgres 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 Postgres data folder
Set the OLD_DATA_DIR environment variable to the value returned by the following:
```
psql -d "$SOURCE" -c "SHOW data_directory ;"
```
Postgres returns something like:
```
----------------------------
/home/postgres/pgdata/data
(1 row)
```

Choose the new locations for the Postgres 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 Postgres, 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 Postgres

Try for free on Tiger Cloud

Prerequisites

Plan your upgrade path

Upgrade your Postgres instance

Related Content