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.

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

This page shows you how to perform a major upgrade. For minor upgrades, see Upgrade TimescaleDB to a minor version.

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

To see the versions of PostgreSQL and TimescaleDB running in a self-hosted database instance:

  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)

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

Version numberPostgreSQL 17PostgreSQL 16PostgreSQL 15PostgreSQL 14PostgreSQL 13PostgreSQL 12PostgreSQL 11PostgreSQL 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.

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.

  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;

You cannot upgrade TimescaleDB and PostgreSQL at the same time. You upgrade each product in the following steps:

  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.

  1. Verify the continuous aggregate policy jobs

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

    Postgres 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;

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

Keywords

Found an issue on this page?Report an issue or Edit this page in GitHub.