Major TimescaleDB upgrades

A major upgrade is when you update from TimescaleDB X.<minor version> to Y.<minor version>. A minor upgrade is when you update from TimescaleDB <major version>.x, to TimescaleDB <major version>.y. 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.

When you perform a major upgrade, new policies are automatically configured based on your current configuration. In order to verify your policies post upgrade, in this upgrade process you export your policy settings before upgrading.

This page shows you how to perform a major upgrade. For minor upgrades, see Upgrade TimescaleDB to a minor 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 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.

Check the TimescaleDB and PostgreSQL versions

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

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

3. 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 Tiger 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 1.7 on PostgreSQL 12 to TimescaleDB 2.17.2 on PostgreSQL 15 you need to:

1. Upgrade TimescaleDB to 2.10
2. Upgrade PostgreSQL to 15
3. Upgrade TimescaleDB to 2.17.2.

You may need to upgrade to the latest PostgreSQL version before you upgrade TimescaleDB.

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

Check for failed retention policies

When you upgrade from TimescaleDB 1 to TimescaleDB 2, scripts automatically configure updated features to work as expected with the new version. However, not everything works in exactly the same way as previously.

Before you begin this major upgrade, check the database log for errors related to failed retention policies that could have occurred in TimescaleDB 1. You can either remove the failing policies entirely, or update them to be compatible with your existing continuous aggregates.

If incompatible retention policies are present when you perform the upgrade, the ignore_invalidation_older_than setting is automatically turned off, and a notice is shown.

Export your policy settings

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

2. Connect to your PostgreSQL deployment

   psql -d $SOURCE

3. Save your policy statistics settings to a .csv file

   COPY (SELECT * FROM timescaledb_information.policy_stats)
   TO policy_stats.csv csv header

4. Save your continuous aggregates settings to a .csv file

   COPY (SELECT * FROM timescaledb_information.continuous_aggregate_stats)
   TO continuous_aggregate_stats.csv csv header

5. Save your drop chunk policies to a .csv file

   COPY (SELECT * FROM timescaledb_information.drop_chunks_policies)
   TO drop_chunk_policies.csv csv header

6. Save your reorder policies to a .csv file

   COPY (SELECT * FROM timescaledb_information.reorder_policies)
   TO reorder_policies.csv csv header

7. Exit your psql session

   \q;

Implement your upgrade path

1. Upgrade TimescaleDB

   psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"

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

3. If your migration path dictates it, upgrade TimescaleDB again

   psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"

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

Note

To upgrade TimescaleDB in a Docker container, see the Docker container upgrades section.

Verify the updated policy settings and jobs

1. Verify the continuous aggregate policy jobs

   SELECT * FROM timescaledb_information.jobs
     WHERE application_name LIKE 'Refresh Continuous%';

   PostgreSQL returns something like:

   -[ RECORD 1 ]-----+--------------------------------------------------
   job_id            | 1001
   application_name  | Refresh Continuous Aggregate Policy [1001]
   schedule_interval | 01:00:00
   max_runtime       | 00:00:00
   max_retries       | -1
   retry_period      | 01:00:00
   proc_schema       | _timescaledb_internal
   proc_name         | policy_refresh_continuous_aggregate
   owner             | postgres
   scheduled         | t
   config            | {"start_offset": "20 days", "end_offset": "10
   days", "mat_hypertable_id": 2}
   next_start        | 2020-10-02 12:38:07.014042-04
   hypertable_schema | _timescaledb_internal
   hypertable_name   | _materialized_hypertable_2

2. Verify the information for each policy type that you exported before you upgraded

   For continuous aggregates, take note of the config information to verify that all settings were converted correctly.

3. Verify that all jobs are scheduled and running as expected

   SELECT * FROM timescaledb_information.job_stats
     WHERE job_id = 1001;

   PostgreSQL returns something like:

   -[ RECORD 1 ]----------+------------------------------
   hypertable_schema      | _timescaledb_internal
   hypertable_name        | _materialized_hypertable_2
   job_id                 | 1001
   last_run_started_at    | 2020-10-02 09:38:06.871953-04
   last_successful_finish | 2020-10-02 09:38:06.932675-04
   last_run_status        | Success
   job_status             | Scheduled
   last_run_duration      | 00:00:00.060722
   next_scheduled_run     | 2020-10-02 10:38:06.932675-04
   total_runs             | 1
   total_successes        | 1
   total_failures         | 0

You are running a shiny new version of TimescaleDB.