3579 feedback page self hostedlatestupgradesminor upgrade

_partials/_install-self-hosted-docker-based.mdx

@@ -12,7 +12,7 @@ In Terminal:
     [TimescaleDB Toolkit](https://github.com/timescale/timescaledb-toolkit), and support for PostGIS and Patroni.
     The lighter-weight `timescale/timescaledb:latest-pg17` non-ha image uses [Alpine][alpine].
 
-    TimescaleDB is pre-created in the default Postgres database in both the -ha and non-ha docker images.
+    TimescaleDB is pre-created in the default PostgreSQL database in both the -ha and non-ha docker images.
     By default, TimescaleDB is added to any new database you create in these images.
 
 1. **Run the container**

_partials/_migrate_dump_postgresql.md

@@ -1,6 +1,6 @@
 import MigrationSetupFirstSteps from "versionContent/_partials/_migrate_set_up_database_first_steps.mdx";
 import MigrationSetupDBConnectionPostgresql from "versionContent/_partials/_migrate_set_up_align_db_extensions_postgres_based.mdx";
-import MigrationProcedureDumpSchemaPostgres from "versionContent/_partials/_migrate_dump_roles_schema_data_postgres.mdx";
+import MigrationProcedureDumpSchemaPostgreSQL from "versionContent/_partials/_migrate_dump_roles_schema_data_postgres.mdx";
 import MigrationValidateRestartApp from "versionContent/_partials/_migrate_validate_and_restart_app.mdx";
 
 ## Prepare to migrate

_partials/_migrate_install_psql_ec2_instance.md

@@ -60,7 +60,7 @@
    ```sh
    export SOURCE="postgres://<Master username>:<Master password>@<Endpoint>:<Port>/<DB name>"
    ```
-   The value of `Master password` was supplied when this Postgres RDS instance was created.
+   The value of `Master password` was supplied when this PostgreSQL RDS instance was created.
 
 1. Test your connection:
    ```sh
@@ -71,4 +71,4 @@
 </Procedure>
 
 [about-hypertables]: /use-timescale/:currentVersion:/hypertables/about-hypertables/
-[data-compression]: /use-timescale/:currentVersion:/compression/about-compression/
+[data-compression]: /use-timescale/:currentVersion:/compression/about-compression/

_partials/_migrate_live_setup_connection_strings.md

@@ -2,8 +2,8 @@ These variables hold the connection information for the source database and targ
 In Terminal on your migration machine, set the following:
 
 ```bash
-export SOURCE=postgres://<user>:<password>@<source host>:<source port>/<db_name>
-export TARGET=postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require
+export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+export TARGET="postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require"
 ```
 You find the connection information for your Timescale Cloud service in the configuration file you
-downloaded when you created the service.
+downloaded when you created the service.

_partials/_migrate_prerequisites.md

@@ -19,7 +19,6 @@ Before you migrate your data:
 [all available extensions]: /migrate/:currentVersion:/troubleshooting/#extension-availability
 [tablespaces]: /migrate/:currentVersion:/troubleshooting/#tablespaces
 [no-superuser-for-timescale-instance]: /migrate/:currentVersion:/troubleshooting/#superuser-privileges
-[upgrade instructions]: /self-hosted/:currentVersion:/upgrades/about-upgrades/
 [pg_hbaconf]: https://www.timescale.com/blog/5-common-connection-errors-in-postgresql-and-how-to-solve-them/#no-pg_hbaconf-entry-for-host
 [create-ec2-instance]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance
 [adjust-maintenance-window]: /use-timescale/:currentVersion:/upgrades/#adjusting-your-maintenance-window

_partials/_migrate_self_postgres_check_versions.md

@@ -0,0 +1,36 @@
+<Procedure>
+
+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:
+
+   ```bash
+   export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+   ```
+
+2. **Retrieve the version of PostgreSQL that you are running**
+    ```shell
+    psql -X -d $SOURCE -c "SELECT version();"
+    ```
+   PostgreSQL returns something like:
+    ```shell
+    -----------------------------------------------------------------------------------------------------------------------------------------
+    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)
+    ```
+
+1. **Retrieve the version of TimescaleDB that you are running**
+    ```sql
+    psql -X -d $SOURCE -c "\dx timescaledb;"
+    ```
+   PostgreSQL returns something like:
+    ```shell
+        Name     | Version |   Schema   |                             Description
+    -------------+---------+------------+---------------------------------------------------------------------
+    timescaledb | 2.17.2   | public     | Enables scalable inserts and complex queries for time-series data
+    (1 row)
+    ```     
+
+</Procedure> 

_partials/_migrate_self_postgres_implement_migration_path.md

@@ -0,0 +1,37 @@
+<Procedure>
+
+You cannot upgrade TimescaleDB and PostgreSQL at the same time. You upgrade each product in
+the following steps:
+
+1. **Upgrade TimescaleDB**
+
+    ```sql
+   psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"
+   ```
+
+1. **If your migration path dictates it, upgrade PostgreSQL**
+
+   Follow the procedure in [Upgrade PostgreSQL][upgrade-pg]. The version of TimescaleDB installed
+   in your PostgreSQL deployment must be the same before and after the PostgreSQL upgrade.
+
+1. **If your migration path dictates it, upgrade TimescaleDB again**
+
+    ```sql
+   psql -X -d $SOURCE -c "ALTER EXTENSION timescaledb UPDATE TO '<version number>';"
+   ```
+
+1. **Check that you have upgraded to the correct version of TimescaleDB**
+
+    ```sql
+    psql -X -d $SOURCE -c "\dx timescaledb;"
+    ```
+    PostgreSQL returns something like:
+    ```shell
+    Name     | Version | Schema |                                      Description                                      
+    -------------+---------+--------+---------------------------------------------------------------------------------------
+    timescaledb | 2.17.2  | public | Enables scalable inserts and complex queries for time-series data (Community Edition)
+    ```
+
+</Procedure> 
+
+[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-your-postgresql-instance

_partials/_migrate_self_postgres_plan_migration_path.md

@@ -0,0 +1,23 @@
+
+import SupportMatrix from "versionContent/_partials/_migrate_self_postgres_timescaledb_compatibility.mdx";
+
+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 2.13 on PostgreSQL 13 to TimescaleDB 2.17.2 you need to:
+1. Upgrade TimescaleDB to 2.16
+1. Upgrade PostgreSQL to 14 or higher
+1. Upgrade TimescaleDB to 2.17.2.
+
+You may need to [upgrade to the latest PostgreSQL version][upgrade-pg] before you upgrade TimescaleDB. Also,
+if you use [Timescale Toolkit][toolkit-install], ensure the `timescaledb_toolkit` extension is >=  
+v1.6.0 before you upgrade TimescaleDB extension.
+
+<SupportMatrix />
+
+[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-your-postgresql-instance
+[timescale-toolkit]:https://github.com/timescale/timescaledb-toolkit
+[toolkit-install]: /self-hosted/:currentVersion:/tooling/install-toolkit/

_partials/_migrate_self_postgres_timescaledb_compatibility.md

@@ -0,0 +1,24 @@
+
+| Version number            |PostgreSQL 17|PostgreSQL 16|PostgreSQL 15|PostgreSQL 14|PostgreSQL 13|PostgreSQL 12|PostgreSQL 11|PostgreSQL 10|
+|---------------------------|-|-|-|-|-|-|-|-|
+| TimescaleDB<br/> 2.17.x   |✅|✅|✅|✅|❌|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.16.x   |❌|✅|✅|✅|✅|❌|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.15.x   |❌|✅|✅|✅|✅|❌|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.14.x   |❌|✅|✅|✅|✅|❌|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.13.x   |❌|✅|✅|✅|✅|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.12.x   |❌|❌|✅|✅|✅|❌|❌|❌|❌|
+| TimescaleDB<br/> 2.10.x   |❌|❌|✅|✅|✅|✅|❌|❌|❌|
+| TimescaleDB<br/> 2.5 - 2.9 |❌|❌|❌|✅|✅|✅|❌|❌|❌|
+| TimescaleDB<br/> 2.4      |❌|❌|❌|❌|✅|✅|❌|❌|❌|
+| TimescaleDB<br/> 2.1 - 2.3 |❌|❌|❌|❌|✅|✅|✅|❌|❌|
+| TimescaleDB<br/> 2.0      |❌|❌|❌|❌|❌|✅|✅|❌|❌
+| TimescaleDB<br/> 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][postgres-breaking-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](https://console.cloud.timescale.com/) and platform packages for Linux, Windows, MacOS,
+Docker, and Kubernetes are unaffected.
+
+[postgres-breaking-change]: https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/

_partials/_migrate_set_up_database_first_steps.md

@@ -8,8 +8,8 @@
    These variables hold the connection information for the source database and target Timescale Cloud service:
 
    ```bash
-   export SOURCE=postgres://<user>:<password>@<source host>:<source port>/<db_name>
-   export TARGET=postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require
+   export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+   export TARGET="postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require"
    ```
    You find the connection information for your Timescale Cloud Service in the configuration file you
    downloaded when you created the service.

_partials/_migrate_set_up_source_and_target.md

@@ -5,7 +5,7 @@ databases are referred to as `$SOURCE` and `$TARGET` throughout this guide.
 This can be set in your shell, for example:
 
 ```bash
-export SOURCE=postgres://<user>:<password>@<source host>:<source port>/<db_name>
-export TARGET=postgres://<user>:<password>@<target host>:<target port>/<db_name>
+export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+export TARGET="postgres://<user>:<password>@<target host>:<target port>/<db_name>"
 ```
 </Highlight>

_partials/_migrate_to_upload_to_target.md

@@ -10,8 +10,8 @@
    These variables hold the connection information for the source database and target Timescale Cloud service:
 
    ```bash
-   export SOURCE=postgres://<user>:<password>@<source host>:<source port>/<db_name>
-   export TARGET=postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require
+   export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+   export TARGET="postgres://tsdbadmin:<PASSWORD>@<HOST>:<PORT>/tsdb?sslmode=require"
    ```
    You find the connection information for your Timescale Cloud Service in the configuration file you
    downloaded when you created the service.

_partials/_plan_upgrade.md

@@ -1,19 +1,11 @@
-You can upgrade your self-hosted Timescale installation in-place. This means
-that you do not need to dump and restore your data. However, it is still
-important that you plan for your upgrade ahead of time.
 
-Before you upgrade:
-
-*   Read [the release notes][relnotes] for the Timescale version you are
-    upgrading to.
-*   Check which PostgreSQL version you are currently running. You might need to
-    [upgrade to the latest PostgreSQL version][upgrade-pg]
-    before you begin your Timescale upgrade.
-*   [Perform a backup][backup] of your database. While Timescale
+- Install the PostgreSQL client tools on your migration machine. This includes `psql`, and `pg_dump`.
+- Read [the release notes][relnotes] for the version of TimescaleDB that you are upgrading to.
+- [Perform a backup][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.
 
 [relnotes]: https://github.com/timescale/timescaledb/releases
-[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/
+[upgrade-pg]: /self-hosted/:currentVersion:/upgrade-pg/#upgrade-your-postgresql-instance
 [backup]: /self-hosted/:currentVersion:/backup-and-restore/

self-hosted/install/installation-source.md

@@ -77,5 +77,5 @@ And that is it! You have TimescaleDB running on a database on a self-hosted inst
 [config]: /self-hosted/:currentVersion:/configuration/
 [postgres-download]: https://www.postgresql.org/download/
 [cmake-download]: https://cmake.org/download/
-[compatibility-matrix]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/
+[compatibility-matrix]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#plan-your-upgrade-path
 [postgres-breaking-change]: https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/

self-hosted/page-index/page-index.js

@@ -270,37 +270,32 @@ module.exports = [
         href: "upgrades",
         children: [
           {
-            title: "About upgrades",
-            href: "about-upgrades",
-            excerpt: "Learn about upgrading self-hosted TimescaleDB",
-          },
-          {
-            title: "Minor upgrades",
+            title: "Upgrade TimescaleDB to a minor version",
             href: "minor-upgrade",
             excerpt:
-              "Upgrade to a new minor version of self-hosted TimescaleDB",
+              "Upgrade self-hosted TimescaleDB to a new minor version",
           },
           {
-            title: "Major upgrades",
+            title: "Upgrade TimescaleDB to a major version",
             href: "major-upgrade",
             excerpt:
-              "Upgrade to a new major version of self-hosted TimescaleDB",
-          },
-          {
-            title: "Downgrade self-hosted TimescaleDB",
-            href: "downgrade",
-            excerpt: "Downgrade a self-hosted TimescaleDB version",
+              "Upgrade self-hosted TimescaleDB to a new major version",
           },
           {
-            title: "Upgrade within Docker",
+            title: "Upgrade TimescaleDB running in Docker",
             href: "upgrade-docker",
             excerpt:
-              "Upgrade to a new minor version of self-hosted TimescaleDB within a Docker container",
+              "Upgrade self-hosted TimescaleDB running in a Docker container to a new minor version",
           },
           {
             title: "Upgrade PostgreSQL",
             href: "upgrade-pg",
-            excerpt: "Upgrade to a new version of PostgreSQL",
+            excerpt: "Upgrade PostgreSQL to a new version",
+          },
+          {
+            title: "Downgrade TimescaleDB to a minor version",
+            href: "downgrade",
+            excerpt: "Downgrade self-hosted TimescaleDB to the previous minor version",
           },
         ],
       },

self-hosted/tooling/install-toolkit.md

@@ -44,7 +44,7 @@ The recommended way to install the Toolkit is to use the
 To get Toolkit, use the high availability image, `timescaledb-ha`:
 
 ```bash
-docker pull timescale/timescaledb-ha:pg16
+docker pull timescale/timescaledb-ha:pg17
 ```
 
 For more information on running TimescaleDB using Docker, see the section on

self-hosted/upgrades/downgrade.md

@@ -1,13 +1,13 @@
 ---
 title: Downgrade to a previous version of TimescaleDB
-excerpt: Roll back to an older version of TimescaleDB
+excerpt: Downgrade self-hosted TimescaleDB to the previous minor version
 products: [self_hosted]
 keywords: [upgrades]
 ---
 
 import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx";
 
-# Downgrade to a previous version of TimescaleDB
+# Downgrade TimescaleDB to a minor version
 
 If you upgrade to a new TimescaleDB version and encounter problems, you can roll
 back to a previously installed version. This works in the same way as a minor
@@ -42,28 +42,41 @@ Before you downgrade:
 ## Downgrade TimescaleDB to a previous minor version
 
 This downgrade uses the PostgreSQL `ALTER EXTENSION` function to downgrade to
-the latest version of the TimescaleDB extension. TimescaleDB supports having
+a previous version of the TimescaleDB extension. TimescaleDB supports having
 different extension versions on different databases within the same PostgreSQL
 instance. This allows you to upgrade and downgrade extensions independently on
 different databases. Run the `ALTER EXTENSION` function on each database to
 downgrade them individually.
 
 <Highlight type="important">
+
 The downgrade script is tested and supported for single-step downgrades. That
 is, downgrading from the current version, to the previous minor version.
 Downgrading might not work if you have made changes to your database between
 upgrading and downgrading.
+
 </Highlight>
 
 <Procedure>
 
-### Downgrading the TimescaleDB extension
+1. **Set your connection string**
+
+   This variable holds the connection information for the database to upgrade:
+
+   ```bash
+   export SOURCE="postgres://<user>:<password>@<source host>:<source port>/<db_name>"
+   ```
 
-1.  Connect to psql using the `-X` flag. This prevents any `.psqlrc` commands
-   from accidentally triggering the load of a previous TimescaleDB version on
-   session startup.
-1.  At the psql prompt, downgrade the TimescaleDB extension. This must be the
-   first command you execute in the current session:
+2. **Connect to your database instance**
+    ```shell
+    psql -X -d $SOURCE
+    ```
+
+   The `-X` flag prevents any `.psqlrc` commands from accidentally triggering the load of a 
+   previous TimescaleDB version on session startup.
+
+1. **Downgrade the TimescaleDB extension** 
+    This must be the first command you execute in the current session:
 
     ```sql
     ALTER EXTENSION timescaledb UPDATE TO '<PREVIOUS_VERSION>';
@@ -72,14 +85,19 @@ upgrading and downgrading.
     For example:
 
     ```sql
-    ALTER EXTENSION timescaledb UPDATE TO '2.5.1';
+    ALTER EXTENSION timescaledb UPDATE TO '2.17.0';
     ```
 
-1.  Check that you have downgraded to the correct version of the extension with
-   the `\dx` command. The output should show the downgraded version number.
+1. **Check that you have downgraded to the correct version of TimescaleDB**
 
     ```sql
-    \dx timescaledb
+    \dx timescaledb;
+    ```
+   Postgres returns something like:
+    ```shell
+    Name     | Version | Schema |                                      Description                                      
+    -------------+---------+--------+---------------------------------------------------------------------------------------
+    timescaledb | 2.17.0  | public | Enables scalable inserts and complex queries for time-series data (Community Edition)
     ```
 
 </Procedure>