From aa9927504f334235f9959149d04afb8d1ef33e9e Mon Sep 17 00:00:00 2001 From: Markus Wanner Date: Thu, 21 Nov 2024 10:59:13 +0100 Subject: [PATCH] Add hints on what's potentially generic upgrade instructions --- .../docs/pgd/5.6/upgrades/manual_overview.mdx | 38 +++++++++++++++++++ .../docs/pgd/5.6/upgrades/tpa_overview.mdx | 4 ++ 2 files changed, 42 insertions(+) diff --git a/product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx b/product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx index 4acf528f201..f789c76205e 100644 --- a/product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx +++ b/product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx @@ -2,6 +2,8 @@ title: "Upgrading PGD clusters manually" --- +[//]: # (generic, not specific to manual upgrade) + Because EDB Postgres Distributed consists of multiple software components, the upgrade strategy depends partially on the components that are being upgraded. @@ -16,6 +18,8 @@ mixed versions of software and therefore is the simplest. However, it incurs downtime and we don't recommend it unless you can't perform the rolling upgrade for some reason. +[//]: # (generic, not specific to manual upgrade - warning from TPA side should go together with this) + To upgrade an EDB Postgres Distributed cluster: 1. Plan the upgrade. @@ -23,6 +27,8 @@ To upgrade an EDB Postgres Distributed cluster: 3. Upgrade the server software. 4. Check and validate the upgrade. +[//]: # (generic, not specific to manual upgrade - even with TPA, both approaches may be possible) + ## Upgrade planning There are broadly two ways to upgrade each node: @@ -34,6 +40,8 @@ There are broadly two ways to upgrade each node: You can use both of these approaches in a rolling manner. +[//]: # (generic, not specific to manual upgrade) + ### Rolling upgrade considerations While the cluster is going through a rolling upgrade, mixed versions of software @@ -68,10 +76,14 @@ we don't support mixing PostgreSQL, EDB Postgres Extended, and EDB Postgres Advanced Server in one cluster. So you can't use this approach to change the Postgres variant. +[//]: # (generic, important for TPA as well) + !!! Warning Downgrades of EDB Postgres Distributed aren't supported. They require that you manually rebuild the cluster. +[//]: # (generic content) + ### Rolling server software upgrades A rolling upgrade is where the [server software @@ -88,6 +100,8 @@ During the upgrade process, you can switch the application over to a node that's currently not being upgraded to provide continuous availability of the database for applications. +[//]: # (generic, important for TPA as well) + ### Rolling upgrade using node join The other method to upgrade the server software is to join a new node @@ -102,6 +116,9 @@ the newer Postgres version until all nodes are upgraded to the newer and same release of Postgres. This is especially true for any new DDL syntax that was added to a newer release of Postgres. +[//]: # (generic - however, to speed up, one could use bdr_init_physical to +[//]: # (join a node with bdr_init_physical, , then upgrade) + !!! Note `bdr_init_physical` makes a byte-by-byte copy of the source node so you can't use it while upgrading from one major Postgres version @@ -109,6 +126,8 @@ new DDL syntax that was added to a newer release of Postgres. PGD version of the source and the joining node be exactly the same. You can't use it for rolling upgrades by way of joining a new node method. Instead, use a logical join. +[//]: # (specific to manual - should probably be disallowed for TPA?) + ### Upgrading a CAMO-enabled cluster Upgrading a CAMO-enabled cluster requires upgrading CAMO groups one by one while @@ -137,6 +156,8 @@ constitute a CAMO pair to PGD 5.0: 1. If necessary, allow clients to connect to the CAMO-protected nodes again. +[//]: # (generic, important for TPA as well) + ## Upgrade preparation Each major release of the software contains several changes that might affect @@ -146,6 +167,8 @@ recommend considering these changes and making any needed adjustments in advance See individual changes mentioned in the [release notes](../rel_notes/) and any version-specific upgrade notes. +[//]: # (here the specifics for manual upgrade starts, I think) + ## Server software upgrade Upgrading EDB Postgres Distributed on individual nodes happens in place. @@ -161,11 +184,16 @@ During the upgrade of binary packages, it's usually best to stop the running Postgres server first. Doing so ensures that mixed versions don't get loaded in case of an unexpected restart during the upgrade. +[//]: # (usually best? I think we should recommend that, otherwise we're on +[//]: # (the hook to explain other methods.) + #### Upgrade packages The first step in the upgrade is to install the new version of the BDR packages. This installation installs both the new binary and the extension SQL script. This step is specific to the operating system. +[//]: # (package level dependencies of BDR may pull in new patch versions of Postgres) + #### Start Postgres Once packages are upgraded, you can start the Postgres instance. The BDR @@ -183,12 +211,20 @@ Upgrading to a new minor version of Postgres is similar to [upgrading the BDR extension](#bdr-extension-upgrade). Stopping Postgres, upgrading packages, and starting Postgres again is typically all that's needed. +[//]: # (...and should be done together with the BDR upgrade, i.e. only a) +[//]: # (single Postgres restart is needed. Sometimes, BDR packages even) +[//]: # (force this as mentioned above.) + However, sometimes more steps, like reindexing, might be recommended for specific minor version upgrades. Refer to the release notes of the version of Postgres you're upgrading to. #### Major version Postgres upgrade +[//]: # (While it's true that it's more complicated, let's also compare with) +[//]: # (single node Postgres and highlight the feature that PGD allows for) +[//]: # (zero downtime major version upgrades.) + Upgrading to a new major version of Postgres is more complicated than upgrading to a minor version. EDB Postgres Distributed provides a bdr_pg_upgrade command line utility, @@ -199,6 +235,8 @@ which you can use to do [in-place Postgres major version upgrades](bdr_pg_upgrad BDR extension, and others, it's always important to ensure your application is compatible with the target version of the software you're upgrading. +[//]: # (generic again, applies to TPA driven upgrades, too) + ## Upgrade check and validation After you upgrade your PGD node, you can verify the current diff --git a/product_docs/docs/pgd/5.6/upgrades/tpa_overview.mdx b/product_docs/docs/pgd/5.6/upgrades/tpa_overview.mdx index d3e4c6e2f3e..25813253813 100644 --- a/product_docs/docs/pgd/5.6/upgrades/tpa_overview.mdx +++ b/product_docs/docs/pgd/5.6/upgrades/tpa_overview.mdx @@ -12,6 +12,8 @@ If you used TPA to install your cluster, you can also use TPA to upgrade it. The You can read more about the capabilities of TPA upgrades in [Upgrading your cluster](/tpa/latest/tpaexec-upgrade/) in the TPA documentation. +[//]: # (generic) + !!! Warning Always test first If possible, always test upgrade processes in a QA environment first. This helps to ensure that there are no unexpected factors to take into account. TPA's ability to reproducibly deploy a PGD configuration makes it much easier to build a test environment to work with. !!! @@ -50,6 +52,8 @@ TPA first tests the cluster and then the nodes. Each node is then isolated from the cluster, upgraded, and returned to operation within the cluster. +[//]: # (this is an explanation of what TPA does, right? Please clarify) + ### TPA upgrades - step by step * Checks that all preconditions for upgrading the cluster are met.