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.
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
, andpg_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:
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>"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)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:
- Upgrade TimescaleDB to 2.10
- Upgrade PostgreSQL to 15
- Upgrade TimescaleDB to 2.17.2.
You may need to upgrade to the latest PostgreSQL version before you upgrade TimescaleDB.
Version number | PostgreSQL 17 | PostgreSQL 16 | PostgreSQL 15 | PostgreSQL 14 | PostgreSQL 13 | PostgreSQL 12 | PostgreSQL 11 | PostgreSQL 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.
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>"Connect to your PostgreSQL deployment
psql -d $SOURCESave your policy statistics settings to a
.csv
fileCOPY (SELECT * FROM timescaledb_information.policy_stats)TO policy_stats.csv csv headerSave your continuous aggregates settings to a
.csv
fileCOPY (SELECT * FROM timescaledb_information.continuous_aggregate_stats)TO continuous_aggregate_stats.csv csv headerSave your drop chunk policies to a
.csv
fileCOPY (SELECT * FROM timescaledb_information.drop_chunks_policies)TO drop_chunk_policies.csv csv headerSave your reorder policies to a
.csv
fileCOPY (SELECT * FROM timescaledb_information.reorder_policies)TO reorder_policies.csv csv headerExit your psql session
\q;
You cannot upgrade TimescaleDB and PostgreSQL at the same time. You upgrade each product in the following steps:
Upgrade TimescaleDB
psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"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.
If your migration path dictates it, upgrade TimescaleDB again
psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"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 continuous aggregate policy jobs
SELECT * FROM timescaledb_information.jobsWHERE application_name LIKE 'Refresh Continuous%';Postgres returns something like:
-[ RECORD 1 ]-----+--------------------------------------------------job_id | 1001application_name | Refresh Continuous Aggregate Policy [1001]schedule_interval | 01:00:00max_runtime | 00:00:00max_retries | -1retry_period | 01:00:00proc_schema | _timescaledb_internalproc_name | policy_refresh_continuous_aggregateowner | postgresscheduled | tconfig | {"start_offset": "20 days", "end_offset": "10days", "mat_hypertable_id": 2}next_start | 2020-10-02 12:38:07.014042-04hypertable_schema | _timescaledb_internalhypertable_name | _materialized_hypertable_2Verify 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.Verify that all jobs are scheduled and running as expected
SELECT * FROM timescaledb_information.job_statsWHERE job_id = 1001;Postgres returns something like:
-[ RECORD 1 ]----------+------------------------------hypertable_schema | _timescaledb_internalhypertable_name | _materialized_hypertable_2job_id | 1001last_run_started_at | 2020-10-02 09:38:06.871953-04last_successful_finish | 2020-10-02 09:38:06.932675-04last_run_status | Successjob_status | Scheduledlast_run_duration | 00:00:00.060722next_scheduled_run | 2020-10-02 10:38:06.932675-04total_runs | 1total_successes | 1total_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.