--- title: Major TimescaleDB upgrades | Tiger Data Docs description: Upgrade your self-hosted TimescaleDB installation to a new major version --- A major upgrade is when you update from TimescaleDB `X.` to `Y.`. A minor upgrade is when you update from TimescaleDB `.x`, to TimescaleDB `.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](/docs/deploy/self-hosted/upgrades/minor-upgrade/index.md). ## 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. ## Check the TimescaleDB and PostgreSQL versions 1. **Set your connection string** This variable holds the connection information for the database to upgrade: Terminal window ``` export SOURCE="postgres://:@:/" ``` 2. **Retrieve the version of PostgreSQL that you are running** Terminal window ``` psql -X -d $SOURCE -c "SELECT version();" ``` PostgreSQL returns something like: Terminal window ``` ----------------------------------------------------------------------------------------------------------------------------------------- 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: Terminal window ``` 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](/docs/deploy/self-hosted/upgrades/upgrade-pg#upgrade-your-postgresql-instance/index.md) 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](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. ## 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: Terminal window ``` export SOURCE="postgres://:@:/" ``` 2. **Connect to your PostgreSQL deployment** Terminal window ``` 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 '';" ``` 2. **If your migration path dictates it, upgrade PostgreSQL** Follow the procedure in [Upgrade PostgreSQL](/docs/deploy/self-hosted/upgrades/upgrade-pg/index.md). 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 '';" ``` 4. **Check that you have upgraded to the correct version of TimescaleDB** ``` psql -X -d $SOURCE -c "\dx timescaledb;" ``` PostgreSQL returns something like: Terminal window ``` 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](/docs/deploy/self-hosted/upgrades/upgrade-docker/index.md) 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: Terminal window ``` -[ 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.