Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add hints on what's potentially generic upgrade instructions #6272

Draft
wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft

Add hints on what's potentially generic upgrade instructions #6272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -16,13 +18,17 @@ 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.
2. Prepare for the upgrade.
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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -102,13 +116,18 @@ 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
to another. In fact, currently `bdr_init_physical` requires that even the
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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand Down
4 changes: 4 additions & 0 deletions product_docs/docs/pgd/5.6/upgrades/tpa_overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
!!!
Expand Down Expand Up @@ -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.
Expand Down