diff --git a/_partials/_install-self-hosted-docker-based.mdx b/_partials/_install-self-hosted-docker-based.mdx index 00440a4d6c..4457fe5d2a 100644 --- a/_partials/_install-self-hosted-docker-based.mdx +++ b/_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** diff --git a/_partials/_migrate_dump_postgresql.md b/_partials/_migrate_dump_postgresql.md index c33c1a736c..8661f3cb25 100644 --- a/_partials/_migrate_dump_postgresql.md +++ b/_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 diff --git a/_partials/_migrate_install_psql_ec2_instance.md b/_partials/_migrate_install_psql_ec2_instance.md index e668e824c5..00f0d5326c 100644 --- a/_partials/_migrate_install_psql_ec2_instance.md +++ b/_partials/_migrate_install_psql_ec2_instance.md @@ -60,7 +60,7 @@ ```sh export SOURCE="postgres://:@:/" ``` - 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 @@ [about-hypertables]: /use-timescale/:currentVersion:/hypertables/about-hypertables/ -[data-compression]: /use-timescale/:currentVersion:/compression/about-compression/ \ No newline at end of file +[data-compression]: /use-timescale/:currentVersion:/compression/about-compression/ diff --git a/_partials/_migrate_live_setup_connection_strings.md b/_partials/_migrate_live_setup_connection_strings.md index 6707b5ae2a..0f14a70fcb 100644 --- a/_partials/_migrate_live_setup_connection_strings.md +++ b/_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://:@:/ -export TARGET=postgres://tsdbadmin:@:/tsdb?sslmode=require +export SOURCE="postgres://:@:/" +export TARGET="postgres://tsdbadmin:@:/tsdb?sslmode=require" ``` You find the connection information for your Timescale Cloud service in the configuration file you -downloaded when you created the service. \ No newline at end of file +downloaded when you created the service. diff --git a/_partials/_migrate_prerequisites.md b/_partials/_migrate_prerequisites.md index ccb8d3e880..56d5c0bc74 100644 --- a/_partials/_migrate_prerequisites.md +++ b/_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 diff --git a/_partials/_migrate_self_postgres_check_versions.md b/_partials/_migrate_self_postgres_check_versions.md new file mode 100644 index 0000000000..286750ec97 --- /dev/null +++ b/_partials/_migrate_self_postgres_check_versions.md @@ -0,0 +1,36 @@ + + +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://:@:/" + ``` + +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) + ``` + + diff --git a/_partials/_migrate_self_postgres_implement_migration_path.md b/_partials/_migrate_self_postgres_implement_migration_path.md new file mode 100644 index 0000000000..37973edae1 --- /dev/null +++ b/_partials/_migrate_self_postgres_implement_migration_path.md @@ -0,0 +1,37 @@ + + +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 '';" + ``` + +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 '';" + ``` + +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) + ``` + + + +[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-your-postgresql-instance diff --git a/_partials/_migrate_self_postgres_plan_migration_path.md b/_partials/_migrate_self_postgres_plan_migration_path.md new file mode 100644 index 0000000000..0ecb649776 --- /dev/null +++ b/_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. + + + +[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/ diff --git a/_partials/_migrate_self_postgres_timescaledb_compatibility.md b/_partials/_migrate_self_postgres_timescaledb_compatibility.md new file mode 100644 index 0000000000..671064db8a --- /dev/null +++ b/_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
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][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/ diff --git a/_partials/_migrate_set_up_database_first_steps.md b/_partials/_migrate_set_up_database_first_steps.md index 13a36eecfc..19562516e4 100644 --- a/_partials/_migrate_set_up_database_first_steps.md +++ b/_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://:@:/ - export TARGET=postgres://tsdbadmin:@:/tsdb?sslmode=require + export SOURCE="postgres://:@:/" + export TARGET="postgres://tsdbadmin:@:/tsdb?sslmode=require" ``` You find the connection information for your Timescale Cloud Service in the configuration file you downloaded when you created the service. diff --git a/_partials/_migrate_set_up_source_and_target.md b/_partials/_migrate_set_up_source_and_target.md index 3fa5e5c8ac..13a09236c9 100644 --- a/_partials/_migrate_set_up_source_and_target.md +++ b/_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://:@:/ -export TARGET=postgres://:@:/ +export SOURCE="postgres://:@:/" +export TARGET="postgres://:@:/" ``` diff --git a/_partials/_migrate_to_upload_to_target.md b/_partials/_migrate_to_upload_to_target.md index 426ff16755..33ea3e121d 100644 --- a/_partials/_migrate_to_upload_to_target.md +++ b/_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://:@:/ - export TARGET=postgres://tsdbadmin:@:/tsdb?sslmode=require + export SOURCE="postgres://:@:/" + export TARGET="postgres://tsdbadmin:@:/tsdb?sslmode=require" ``` You find the connection information for your Timescale Cloud Service in the configuration file you downloaded when you created the service. diff --git a/_partials/_plan_upgrade.md b/_partials/_plan_upgrade.md index e579123a00..83bc96aa9d 100644 --- a/_partials/_plan_upgrade.md +++ b/_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/ diff --git a/self-hosted/install/installation-source.md b/self-hosted/install/installation-source.md index bff5757ba0..374efd6bda 100644 --- a/self-hosted/install/installation-source.md +++ b/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/ diff --git a/self-hosted/page-index/page-index.js b/self-hosted/page-index/page-index.js index 1cbaeba80c..80b601a3b0 100644 --- a/self-hosted/page-index/page-index.js +++ b/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", }, ], }, diff --git a/self-hosted/tooling/install-toolkit.md b/self-hosted/tooling/install-toolkit.md index bcf48ab8d7..852888ebda 100644 --- a/self-hosted/tooling/install-toolkit.md +++ b/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 diff --git a/self-hosted/upgrades/downgrade.md b/self-hosted/upgrades/downgrade.md index 4e32bb8705..5d69c93d9d 100644 --- a/self-hosted/upgrades/downgrade.md +++ b/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. + 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. + -### Downgrading the TimescaleDB extension +1. **Set your connection string** + + This variable holds the connection information for the database to upgrade: + + ```bash + export SOURCE="postgres://:@:/" + ``` -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 ''; @@ -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) ``` diff --git a/self-hosted/upgrades/index.md b/self-hosted/upgrades/index.md index b80ca9fbd6..3c1e88c576 100644 --- a/self-hosted/upgrades/index.md +++ b/self-hosted/upgrades/index.md @@ -9,35 +9,20 @@ import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; # Upgrade TimescaleDB -You can upgrade your on-premise TimescaleDB installation in-place. +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 upgrade your self-hosted TimescaleDB installation in-place. -A major upgrade is when you upgrade from one major version of TimescaleDB, to -the next major version. For example, when you upgrade from TimescaleDB 1, -to TimescaleDB 2. - -A minor upgrade is when you upgrade within your current major version of -TimescaleDB. For example, when you upgrade from TimescaleDB 2.5, to -TimescaleDB 2.6. - -If you originally installed TimescaleDB using Docker, you can upgrade from -within the Docker container. For more information, and instructions, see the -[Upgrading with Docker section][upgrade-docker]. - -You can also downgrade your TimescaleDB installation to a previous version, if -you need to. + -* [Learn about upgrades][about-upgrades] to understand how it works - before you begin your upgrade. -* Upgrade to the next [minor version][upgrade-minor] of TimescaleDB. -* Upgrade to the next [major version][upgrade-major] of TimescaleDB. -* [Downgrade][downgrade] to a previous version of TimescaleDB. -* Upgrade TimescaleDB using [Docker][upgrade-docker]. -* Upgrade the version of [PostgreSQL][upgrade-pg] your TimescaleDB - installation uses. +This section shows you how to: - +* Upgrade self-hosted TimescaleDB to a new [minor version][upgrade-minor]. +* Upgrade self-hosted TimescaleDB to a new [major version][upgrade-major]. +* Upgrade self-hosted TimescaleDB running in a [Docker container][upgrade-docker] to a new minor version. +* Upgrade [PostgreSQL][upgrade-pg] to a new version. +* Downgrade self-hosted TimescaleDB to the [previous minor version][downgrade]. -[about-upgrades]: /self-hosted/:currentVersion:/upgrades/about-upgrades/ [downgrade]: /self-hosted/:currentVersion:/upgrades/downgrade/ [upgrade-docker]: /self-hosted/:currentVersion:/upgrades/upgrade-docker/ [upgrade-major]: /self-hosted/:currentVersion:/upgrades/major-upgrade/ diff --git a/self-hosted/upgrades/major-upgrade.md b/self-hosted/upgrades/major-upgrade.md index 818522e5f4..98da5552d2 100644 --- a/self-hosted/upgrades/major-upgrade.md +++ b/self-hosted/upgrades/major-upgrade.md @@ -1,37 +1,67 @@ --- title: Major TimescaleDB upgrades -excerpt: Upgrade from one major of TimescaleDB to the next major version +excerpt: Upgrade self-hosted TimescaleDB to a new major version products: [self_hosted] keywords: [upgrades] --- import PlanUpgrade from "versionContent/_partials/_plan_upgrade.mdx"; import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; +import CheckVersions from "versionContent/_partials/_migrate_self_postgres_check_versions.mdx"; +import SupportMatrix from "versionContent/_partials/_migrate_self_postgres_timescaledb_compatibility.mdx"; +import ImplementMigrationPath from "versionContent/_partials/_migrate_self_postgres_implement_migration_path.mdx"; -# Major TimescaleDB upgrades +# Upgrade TimescaleDB to a major version -A major upgrade is when you upgrade from one major version of TimescaleDB, to -the next major version. For example, when you upgrade from TimescaleDB 1, -to TimescaleDB 2. +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. -For upgrading within your current major version, for example upgrading from -TimescaleDB 2.5 to TimescaleDB 2.6, see the -[minor upgrades section][upgrade-minor]. +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. -## Plan your upgrade +This page shows you how to perform a major upgrade. For minor upgrades, see +[Upgrade TimescaleDB to a minor version][upgrade-minor]. + +## Prerequisites -## Breaking changes +## Check the TimescaleDB and PostgreSQL versions + + + +## Plan your upgrade path + +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 +1. Upgrade PostgreSQL to 15 +1. Upgrade TimescaleDB to 2.17.2. + +You may need to [upgrade to the latest PostgreSQL version][upgrade-pg] before you upgrade TimescaleDB. + + -When you upgrade from TimescaleDB 1, to TimescaleDB 2, scripts +## 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 +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. @@ -39,103 +69,83 @@ 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. -## Upgrade TimescaleDB to the next major version - -To perform this major upgrade: +## Export your policy settings -1. Export your TimescaleDB 1 policy settings -1. Upgrade the TimescaleDB extension -1. Verify updated policy settings and jobs + -When you perform the upgrade, new policies are automatically configured based on -your current configuration. This upgrade process allows you to export your -policy settings before performing the upgrade, so that you can verify them after -the upgrade is complete. +1. **Set your connection string** -This upgrade uses the PostgreSQL `ALTER EXTENSION` function to upgrade to the -latest version of the TimescaleDB extension. TimescaleDB supports having -different extension versions on different databases within the same PostgreSQL -instance. This allows you to upgrade extensions independently on different -databases. Run the `ALTER EXTENSION` function on each database to upgrade them -individually. + This variable holds the connection information for the database to upgrade: - + ```bash + export SOURCE="postgres://:@:/" + ``` -### Exporting TimescaleDB 1 policy settings +1. **Connect to your PostgreSQL deployment** + ```bash + psql -d $SOURCE + ``` -1. At the psql prompt, use this command to save the current settings for your - policy statistics to a `.csv` file: +1. **Save your policy statistics settings to a `.csv` file** ```sql COPY (SELECT * FROM timescaledb_information.policy_stats) TO policy_stats.csv csv header ``` -1. Use this command to save the current settings for your continuous aggregates - to a `.csv` file: +1. **Save your continuous aggregates settings to a `.csv` file** ```sql COPY (SELECT * FROM timescaledb_information.continuous_aggregate_stats) TO continuous_aggregate_stats.csv csv header ``` -1. Use this command to save the current settings for your drop chunk policies to - a `.csv` file: +1. **Save your drop chunk policies to a `.csv` file** ```sql COPY (SELECT * FROM timescaledb_information.drop_chunks_policies) TO drop_chunk_policies.csv csv header ``` -1. Use this command to save the current settings for your reorder policies - to a `.csv` file: +1. **Save your reorder policies to a `.csv` file** ```sql COPY (SELECT * FROM timescaledb_information.reorder_policies) TO reorder_policies.csv csv header ``` - +1. **Exit your psql session** + ```sql + \q; + ``` - + -### Upgrading the TimescaleDB extension -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, upgrade the TimescaleDB extension. This must be the first - command you execute in the current session: - ```sql - ALTER EXTENSION timescaledb UPDATE; - ``` +## Implement your upgrade path -1. Check that you have upgraded to the latest version of the extension with the - `\dx` command. The output should show the upgraded version number. + - ```sql - \dx timescaledb - ``` - - To upgrade TimescaleDB in a Docker container, see the - [Docker container upgrades](/self-hosted/latest/upgrades/upgrade-docker) - section. - + +To upgrade TimescaleDB in a Docker container, see the +[Docker container upgrades](/self-hosted/latest/upgrades/upgrade-docker) +section. + - +## Verify the updated policy settings and jobs -### Verifying updated policy settings and jobs - -1. Use this query to verify the continuous aggregate policy jobs: +1. **Verify the continuous aggregate policy jobs** ```sql SELECT * FROM timescaledb_information.jobs WHERE application_name LIKE 'Refresh Continuous%'; - + ``` + Postgres returns something like: + ```shell -[ RECORD 1 ]-----+-------------------------------------------------- job_id | 1001 application_name | Refresh Continuous Aggregate Policy [1001] @@ -154,35 +164,40 @@ individually. hypertable_name | _materialized_hypertable_2 ``` -1. 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. -1. Verify that all jobs are scheduled and running as expected using the new - `timescaledb_information.job_stats` view: - -```sql -SELECT * FROM timescaledb_information.job_stats - WHERE job_id = 1001; -``` - -The output looks like this: - -```sql --[ 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 -``` +1. **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. + +1. **Verify that all jobs are scheduled and running as expected** + + ```sql + SELECT * FROM timescaledb_information.job_stats + WHERE job_id = 1001; + ``` + Postgres returns something like: + ```sql + -[ 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. + [upgrade-minor]: /self-hosted/:currentVersion:/upgrades/minor-upgrade/ +[relnotes]: https://github.com/timescale/timescaledb/releases +[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-postgresql +[backup]: /self-hosted/:currentVersion:/backup-and-restore/ +[export-policy-settings]: /self-hosted/:currentVersion:/upgrades/major-upgrade/#export-your-policy-settings diff --git a/self-hosted/upgrades/minor-upgrade.md b/self-hosted/upgrades/minor-upgrade.md index 388ab55f84..02da60f6c8 100644 --- a/self-hosted/upgrades/minor-upgrade.md +++ b/self-hosted/upgrades/minor-upgrade.md @@ -1,66 +1,48 @@ --- title: Minor TimescaleDB upgrades -excerpt: Upgrade within the same major version of TimescaleDB +excerpt: Upgrade self-hosted TimescaleDB to a new minor version products: [self_hosted] keywords: [upgrades] --- import PlanUpgrade from "versionContent/_partials/_plan_upgrade.mdx"; import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; +import CheckVersions from "versionContent/_partials/_migrate_self_postgres_check_versions.mdx"; +import PlanMigrationPath from "versionContent/_partials/_migrate_self_postgres_plan_migration_path.mdx"; +import ImplementMigrationPath from "versionContent/_partials/_migrate_self_postgres_implement_migration_path.mdx"; -# Minor TimescaleDB upgrades +# Upgrade TimescaleDB to a new minor version -A minor upgrade is when you upgrade within your current major version of -TimescaleDB. For example, when you upgrade from TimescaleDB 2.5, to -TimescaleDB 2.6. - -For upgrading to a new major version, for example upgrading from -TimescaleDB 1 to TimescaleDB 2, see the -[major upgrades section][upgrade-major]. +A minor upgrade is when you update from TimescaleDB `.x` to TimescaleDB `.y`. +A major upgrade is when you update from TimescaleDB `X.` to `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. -## Plan your upgrade - - +This page shows you how to perform a minor upgrade, for major upgrades, see [Upgrade TimescaleDB to a major version][upgrade-major]. -## Upgrade TimescaleDB to the next minor version +## Prerequisites -This upgrade uses the PostgreSQL `ALTER EXTENSION` function to upgrade to the -latest version of the TimescaleDB extension. TimescaleDB supports having -different extension versions on different databases within the same PostgreSQL -instance. This allows you to upgrade extensions independently on different -databases. Run the `ALTER EXTENSION` function on each database to upgrade them -individually. + - +## Check the TimescaleDB and PostgreSQL versions -### Upgrading the TimescaleDB extension + -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, upgrade the TimescaleDB extension. This must be the first - command you execute in the current session: +## Plan your upgrade path - ```sql - ALTER EXTENSION timescaledb UPDATE; - ``` + -1. Check that you have upgraded to the latest version of the extension with the - `\dx` command. The output should show the upgraded version number. - ```sql - \dx timescaledb - ``` +## Implement your upgrade path - - To upgrade TimescaleDB in a Docker container, see the - [Docker container upgrades](/self-hosted/latest/upgrades/upgrade-docker) - section. - + - +You are running a shiny new version of TimescaleDB. +[relnotes]: https://github.com/timescale/timescaledb/releases +[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-postgresql [upgrade-major]: /self-hosted/:currentVersion:/upgrades/major-upgrade/ - +[backup]: /self-hosted/:currentVersion:/backup-and-restore/ diff --git a/self-hosted/upgrades/upgrade-docker.md b/self-hosted/upgrades/upgrade-docker.md index 8598ae0a9a..ed1c5ead52 100644 --- a/self-hosted/upgrades/upgrade-docker.md +++ b/self-hosted/upgrades/upgrade-docker.md @@ -1,26 +1,30 @@ --- title: Upgrades within a Docker container -excerpt: Upgrade TimescaleDB within a Docker container +excerpt: Upgrade self-hosted TimescaleDB running in a Docker container to a new minor version products: [self_hosted] keywords: [upgrades, Docker] --- import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; -# Upgrades within a Docker container +# Upgrade TimescaleDB running in Docker -If you originally installed TimescaleDB using Docker, you can upgrade from -within the Docker container. This allows you to upgrade to the latest -TimescaleDB version, while retaining your data. +If you originally installed TimescaleDB using Docker, you can upgrade from within the Docker +container. This allows you to upgrade to the latest TimescaleDB version while retaining your data. - -In this section, the examples use a Docker instance called `timescaledb`. If you -have given your Docker instance a different name, replace it when you issue the -commands. - +The `timescale/timescaledb-ha*` images have the files necessary to run previous versions. Patch releases +only contain bugfixes so should always be safe. Non-patch releases may rarely require some extra steps. +These steps are mentioned in the [release notes][relnotes] for the version of TimescaleDB +that you are upgrading to. + +After you upgrade the docker image, you run `ALTER EXTENSION` for all databases using TimescaleDB. +The examples in this page use a Docker instance called `timescaledb`. If you +have given your Docker instance a different name, replace it when you issue the +commands. + ## Determine the mount point type When you start your upgraded Docker container, you need to be able to point the @@ -79,12 +83,12 @@ data. ### Upgrading TimescaleDB within Docker 1. Pull the latest TimescaleDB image. This command pulls the image for - PostgreSQL 14. If you're using another PostgreSQL version, look for the - relevant tag in the + TimescaleDB 2.17.x running on PostgreSQL 17. If you're using another PostgreSQL version, + look for the relevant tag in the [TimescaleDB HA Docker Hub repository](https://hub.docker.com/r/timescale/timescaledb-ha/tags). ```bash - docker pull timescale/timescaledb-ha:pg16 + docker pull timescale/timescaledb-ha:pg17 ``` 1. Stop the old container, and remove it: @@ -150,3 +154,4 @@ If you have multiple databases, you need to update each database separately. [toolkit]: /self-hosted/:currentVersion:/tooling/install-toolkit/ +[relnotes]: https://github.com/timescale/timescaledb/releases diff --git a/self-hosted/upgrades/upgrade-pg.md b/self-hosted/upgrades/upgrade-pg.md index 4e9ffa6481..d1ebf79494 100644 --- a/self-hosted/upgrades/upgrade-pg.md +++ b/self-hosted/upgrades/upgrade-pg.md @@ -1,100 +1,87 @@ --- title: Upgrade PostgreSQL -excerpt: Upgrade the PostgreSQL installation associated with TimescaleDB +excerpt: Upgrade PostgreSQL to a new version products: [self_hosted] keywords: [upgrades, PostgreSQL, versions, compatibility] --- +import PlanUpgrade from "versionContent/_partials/_plan_upgrade.mdx"; import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; +import PlanMigrationPath from "versionContent/_partials/_migrate_self_postgres_plan_migration_path.mdx"; # Upgrade PostgreSQL -Because TimescaleDB is a PostgreSQL extension, you need to ensure you keep your -underlying PostgreSQL installation up to date. When you upgrade your TimescaleDB -extension to a new version, always take the time to check if you need to also -upgrade your PostgreSQL version. If you are running an older version of -PostgreSQL, you need to upgrade it first, before you upgrade your TimescaleDB -extension. +TimescaleDB is a PostgreSQL extension. Ensure that you upgrade to compatible versions of TimescaleDB and PostgreSQL. -TimescaleDB supports these PostgreSQL releases. If you are not running a -compatible PostgreSQL version, make sure you upgrade PostgreSQL before you -upgrade TimescaleDB: - -||PostgreSQL 17|PostgreSQL 16|PostgreSQL 15|PostgreSQL 14|PostgreSQL 13|PostgreSQL 12|PostgreSQL 11|PostgreSQL 10|PostgreSQL 9.6| -|-|-|-|-|-|-|-|-|-| -|TimescaleDB 2.17 and higher|✅|✅|✅|✅|❌|❌|❌|❌|❌| -|TimescaleDB 2.16 and higher|❌|✅|✅|✅|✅|❌|❌|❌|❌|❌| -|TimescaleDB 2.15 and higher|❌|✅|✅|✅|✅|❌|❌|❌|❌|❌| -|TimescaleDB 2.14 and higher|❌|✅|✅|✅|✅|❌|❌|❌|❌|❌| -|TimescaleDB 2.13 and higher|❌|✅|✅|✅|✅|❌|❌|❌|❌| -|TimescaleDB 2.12 and higher|❌|❌|✅|✅|✅|❌|❌|❌|❌| -|TimescaleDB 2.10 and higher|❌|❌|✅|✅|✅|✅|❌|❌|❌| -|TimescaleDB 2.5 to 2.9|❌|❌|❌|✅|✅|✅|❌|❌|❌| -|TimescaleDB 2.4|❌|❌|❌|❌|✅|✅|❌|❌|❌| -|TimescaleDB 2.1 to 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][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. - -You cannot upgrade TimescaleDB and PostgreSQL at the same time. You upgrade each product in -the following steps: - -1. Upgrade TimescaleDB to the desired version in your current PostgreSQL installation. -2. Upgrade PostgreSQL to the desired version. - -The version of TimescaleDB installed in your PostgreSQL deployment must be the same before -and after the PostgreSQL upgrade. - -## Plan your upgrade - -You can upgrade your PostgreSQL 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][pg-relnotes] for the PostgreSQL version you are - upgrading to. -* [Perform a backup][backup] of your database. While PostgreSQL and - 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. - -## Upgrade PostgreSQL - -You can use the [`pg_upgrade`][pg_upgrade] tool to upgrade PostgreSQL in-place. -This means that you do not need to dump and restore your data. Instead, -`pg_upgrade` allows you to retain the data files of your current PostgreSQL -installation while binding the new PostgreSQL binary runtime to them. This is -supported for PostgreSQL 8.4 and higher. + +## Prerequisites + + + +## Plan your upgrade path + + + +## Upgrade your PostgreSQL instance + +You use [`pg_upgrade`][pg_upgrade] to upgrade PostgreSQL in-place. `pg_upgrade` allows you to retain +the data files of your current PostgreSQL installation while binding the new PostgreSQL binary runtime +to them. -### Upgrading PostgreSQL +1. **Find the location of the PostgreSQL binary** -1. Before you begin, determine the location of the PostgreSQL binary and your - data directory on your local system. -1. At the psql prompt, perform the upgrade: + Set the `OLD_BIN_DIR` environment variable to the folder holding the `postgres` binary. + For example, `which postgres` returns something like `/usr/lib/postgresql/16/bin/postgres`. + ```bash + export OLD_BIN_DIR=/usr/lib/postgresql/16/bin + ``` + +1. **Set your connection string** + + This variable holds the connection information for the database to upgrade: + + ```bash + export SOURCE="postgres://:@:/" + ``` + +1. **Retrieve the location of the PostgreSQL data folder** + + Set the `OLD_DATA_DIR` environment variable to the value returned by the following: + ```shell + psql -d "$SOURCE" -c "SHOW data_directory ;" + ``` + PostgreSQL returns something like: + ```shell + ---------------------------- + /home/postgres/pgdata/data + (1 row) + ``` + +1. **Choose the new locations for the PostgreSQL binary and data folders** + + For example: + ```shell + export NEW_BIN_DIR=/usr/lib/postgresql/17/bin + export NEW_DATA_DIR=/home/postgres/pgdata/data-17 + ``` +1. Using psql, perform the upgrade: ```sql - pg_upgrade -b -B -d -D + pg_upgrade -b $OLD_BIN_DIR -B $NEW_BIN_DIR -d $OLD_DATA_DIR -D $NEW_DATA_DIR ``` -If you are moving data to a new physical instance of PostgreSQL, you can use the -`pg_dump` and `pg_restore` tools to dump your data from the old database, and -then restore it into the new, upgraded, database. For more information, see the [backup and restore section][backup]. +If you are moving data to a new physical instance of PostgreSQL, you can use `pg_dump` and `pg_restore` +to dump your data from the old database, and then restore it into the new, upgraded, database. For more +information, see the [backup and restore section][backup]. [backup]: /self-hosted/:currentVersion:/backup-and-restore/ [pg-relnotes]: https://www.postgresql.org/docs/release/ [pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html [postgres-breaking-change]: https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/ +[upgrade-pg]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/#upgrade-postgresql