--- title: Upgrade PostgreSQL | Tiger Data Docs description: Upgrade PostgreSQL to a new version compatible with your self-hosted TimescaleDB installation --- 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](https://github.com/timescale/timescaledb/releases) for the version of TimescaleDB that you are upgrading to. - [Perform a backup](/docs/deploy/self-hosted/backup-and-restore/index.md) 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](/docs/deploy/self-hosted/tooling/install-toolkit/index.md), 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.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](https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/) 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`](https://www.postgresql.org/docs/current/pgupgrade.html) 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`. Terminal window ``` 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: Terminal window ``` export SOURCE="postgres://:@:/" ``` 3. **Retrieve the location of the PostgreSQL data folder** Set the `OLD_DATA_DIR` environment variable to the value returned by the following: Terminal window ``` psql -d "$SOURCE" -c "SHOW data_directory ;" ``` PostgreSQL returns something like: Terminal window ``` ---------------------------- /home/postgres/pgdata/data (1 row) ``` 4. **Choose the new locations for the PostgreSQL binary and data folders** For example: Terminal window ``` 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](/docs/deploy/self-hosted/backup-and-restore/index.md).