Skip to content

Edits for DDL replication/Mixed version prohibition #6851

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.

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

Open
wants to merge 7 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions product_docs/docs/pgd/5.8/ddl/ddl-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,9 @@ When using the [`bdr.replicate_ddl_command`](/pgd/5.8/reference/functions#bdrrep
parameter directly with the third argument, using the specified
[`bdr.ddl_locking`](/pgd/5.8/reference/pgd-settings#bdrddl_locking) setting only for the DDL commands passed to that
function.

## DDL and mixed PostgreSQL versions

PGD does not support DDL replication between different major Postgres versions in a cluster. Most of the time, this is not an issue because clusters will be running the same major version of Postgres. This is not the case though when performing a rolling upgrade of a cluster from one major version to another. In this case, DDL replication is not supported until all nodes have been upgraded to the same major version and should not be used.

Special care should be taken in the upgrade process when updating extensions as the scripts may trigger DDL replication. In this case, if the scripts must be run before upgrading is complete, `bdr.ddl_replication` setting should be set to `off` while running the script. See the [Rolling upgrade guide](/pgd/5.8/upgrades/upgrading_major_rolling) for more information on how to perform a rolling upgrade of a PGD cluster.
24 changes: 19 additions & 5 deletions product_docs/docs/pgd/5.8/upgrades/upgrading_major_rolling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Doing the same for an EDB Postgres Distributed (PGD) cluster is essentially the
The rolling upgrade process allows updating individual cluster nodes to a new major Postgres version while maintaining cluster availability and operational continuity.
This approach minimizes downtime and ensures data integrity by allowing the rest of the cluster to remain operational as each node is upgraded sequentially.

While the upgrade process is in progress, the cluster will have mixed Postgres major versions running on different nodes. DDL replication is not supported between different major versions of Postgres, so you must ensure that no DDL changes are made to the cluster while the upgrade is in progress. That includes not running the `ALTER EXTENSION` commands generated by the upgrade processes until all nodes in the cluster are upgraded to the same major version.

The following overview of the general instructions and [worked example](#worked-example) help to provide a smooth and controlled upgrade process.

!!!Note
Expand All @@ -40,11 +42,11 @@ Then you want to find out which node is the write leader in each subgroup:
sudo -u postgres pgd group <group_name> show --summary
```

This command shows you information about the pgd group tokened by your `<group_name>` running in your cluster, including which node is the write leader.
To maintain operational continuity, you need to switch write leaders over to another node in their subgroup before you can upgrade them.
To keep the number of planned switchovers to a minimum, when upgrading a subgroup of nodes, upgrade the writer leaders last.
This command shows you information about the pgd group tokened by your `<group_name>` running in your cluster, including which node is the write leader.
To maintain operational continuity, you need to switch write leaders over to another node in their subgroup before you can upgrade them.
To keep the number of planned switchovers to a minimum, when upgrading a subgroup of nodes, upgrade the writer leaders last.

Even though you verified which node is the current write leader for planning purposes, the write leader of a subgroup could change to another node at any moment for operational reasons before you upgrade that node.
Even though you verified which node is the current write leader for planning purposes, the write leader of a subgroup could change to another node at any moment for operational reasons before you upgrade that node.
Therefore, you still need to verify that a node isn't the write leader just before upgrading that node.

You now have enough information to determine your upgrade order, one subgroup at a time, aiming to upgrade the identified write leader node last in each subgroup.
Expand Down Expand Up @@ -145,12 +147,19 @@ Using the [preliminary order](#prepare-the-upgrade), perform the following steps

`sudo systemctl daemon-reload`


* **Restart Postgres**
* Proceed to restart the PostgreSQL service:

`systemctl start postgres`

* **Update the extensions**
* The upgrade process checks for extension updates and generates a script named `updated_extensions.sql` in the current directory if needed.
This contains `ALTER EXTENSION` commands for any extensions that need updating after the upgrade.

As the script contains are DDL commands, if you have to run the script before all nodes are upgraded, you should [turn off DDL replication temporarily](https://www.enterprisedb.com/docs/pgd/latest/reference/pgd-settings/#bdrddl_replication).
You can do this using `SET bdr.ddl_replication = off;` to avoid issues with mixed major versions, but you will have to ensure that the script keeps DDL replication off during the course of its running. Check for any commands in the script that would change database (such as `\c dbname`) and repeat the `SET bdr.ddl_replication = off;` command.

If you can defer running the script until all nodes are upgraded, it is easier and simpler to run the script on each node after the upgrade of that node is complete.

* **Validate the new Postgres version**
* Verify that your PostgreSQL instance is now upgraded:
Expand Down Expand Up @@ -398,6 +407,7 @@ If you didn't initialize Postgres 17 with checksums using the `--data-checksums`
```bash
old cluster uses data checksums but the new one does not
```

!!!

### Execute the Postgres major version upgrade
Expand Down Expand Up @@ -551,6 +561,10 @@ Start the modified Postgres service:
sudo systemctl start postgres
```

### Update the extensions

After the upgrade, you may need to update the extensions. The upgrade process checks for extension updates and generates a script named `updated_extensions.sql` in the current directory if needed. In this case, no script was generated, so no extensions need updating.

### Validate the new Postgres version

Repeating the first step, check the version of Postgres to confirm that you upgraded kaboom correctly. While still on kaboom, run:
Expand Down
6 changes: 6 additions & 0 deletions product_docs/docs/pgd/6/reference/ddl/ddl-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,9 @@ When using the [`bdr.replicate_ddl_command`](/pgd/latest/reference/tables-views-
parameter directly with the third argument, using the specified
[`bdr.ddl_locking`](/pgd/latest/reference/tables-views-functions/pgd-settings#bdrddl_locking) setting only for the DDL commands passed to that
function.

## DDL and mixed PostgreSQL versions

PGD does not support DDL replication between different major Postgres versions in a cluster. Most of the time, this is not an issue because clusters will be running the same major version of Postgres. This is not the case though when performing a rolling upgrade of a cluster from one major version to another. In this case, DDL replication is not supported until all nodes have been upgraded to the same major version and should not be used.

Special care should be taken in the upgrade process when updating extensions as the scripts may trigger DDL replication. In this case, if the scripts must be run before upgrading is complete, `bdr.ddl_replication` setting should be set to `off` while running the script.
1 change: 1 addition & 0 deletions product_docs/docs/pgd/6/reference/upgrades.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ redirects:
## Upgrading to EDB Postgres Distributed 6

You can't upgrade to EDB Postgres Distributed 6.0.0 from EDB Postgres Distributed 5.x or earlier. This upgrade will be possible in a future release.

Loading