Upgrade PostgreSQL

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

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 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 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.x on PostgreSQL 13 to TimescaleDB 2.25.x:

1. Upgrade TimescaleDB to 2.15.x (last version fully supporting PostgreSQL 13)
2. Upgrade PostgreSQL to 15, 16, 17, or 18
3. Upgrade TimescaleDB to 2.25.x

Older TimescaleDB versions may not be available in package repositories. If you need a specific intermediate version that is no longer packaged, you can build from source or upgrade directly to the latest version that supports your current PostgreSQL version before upgrading PostgreSQL.

You may need to upgrade to the latest PostgreSQL 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.

Warning

PostgreSQL 15 support is deprecated and will be removed from TimescaleDB in June 2026.

TimescaleDB version	PostgreSQL 18	PostgreSQL 17	PostgreSQL 16	PostgreSQL 15	PostgreSQL 14	PostgreSQL 13	PostgreSQL 12	PostgreSQL 11	PostgreSQL 10
2.26.x	✅	✅	✅	✅	❌	❌	❌	❌	❌
2.25.x	✅	✅	✅	✅	❌	❌	❌	❌	❌
2.24.x	✅	✅	✅	✅	❌	❌	❌	❌	❌
2.23.x	✅	✅	✅	✅	❌	❌	❌	❌	❌
2.22.x	❌	✅	✅	✅	❌	❌	❌	❌	❌
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 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 Tiger 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.

1. 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

2. 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>"

3. 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)

4. 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

5. Perform the upgrade using pg_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.