From 21fb7cd7d40d3178a095edc5b0486fc8df1dc67e Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 20 May 2026 11:47:29 +0300 Subject: [PATCH 1/2] PG-2384 - Add pg_tde warning note to use pg_tde_upgrade (17) This PR adds a warning note informing the user they need to use pg_tde_upgrade instead of pg_upgrade in their distribution in case pg_tde is used to encrypt the cluster. --- docs/major-upgrade.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/docs/major-upgrade.md b/docs/major-upgrade.md index 516c40aa8..04425db0b 100644 --- a/docs/major-upgrade.md +++ b/docs/major-upgrade.md @@ -2,25 +2,14 @@ This document describes the in-place upgrade of Percona Distribution for PostgreSQL using the `pg_upgrade` tool. -!!! danger "pg_upgrade is not supported with encrypted tables (pg_tde)" - - `pg_upgrade` is not supported for clusters with encrypted tables (`pg_tde`). - - **You are affected if:** - - - You are using `pg_tde`, or - - Your cluster contains encrypted tables - - It corrupts encryption metadata which results in: - - - Missing or empty key files in the `pg_tde/` directory - - Missing or incomplete provider metadata - To ensure a smooth upgrade path, follow these steps: * Upgrade to the latest minor version within your current major version (e.g., from 16.6 to 16.9). * Then, perform the major upgrade to your desired version (e.g., from 16.9 to 17.5). +!!! warning + If your cluster uses `pg_tde`, you **must** use [`pg_tde_upgrade` :octicons-link-external-16:](https://docs.percona.com/pg-tde/command-line-tools/pg-tde-upgrade.html) instead of `pg_upgrade`. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. The server may start successfully but queries against encrypted tables will fail. + !!! note When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following: From 77329634c22911dd751af389afe71320d24e9fa0 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 20 May 2026 16:10:12 +0300 Subject: [PATCH 2/2] Update major-upgrade.md --- docs/major-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/major-upgrade.md b/docs/major-upgrade.md index 04425db0b..2710fbfcc 100644 --- a/docs/major-upgrade.md +++ b/docs/major-upgrade.md @@ -8,7 +8,7 @@ To ensure a smooth upgrade path, follow these steps: * Then, perform the major upgrade to your desired version (e.g., from 16.9 to 17.5). !!! warning - If your cluster uses `pg_tde`, you **must** use [`pg_tde_upgrade` :octicons-link-external-16:](https://docs.percona.com/pg-tde/command-line-tools/pg-tde-upgrade.html) instead of `pg_upgrade`. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. The server may start successfully but queries against encrypted tables will fail. + When doing a major version upgrade from Percona Distribution for PostgreSQL 17, if your cluster uses `pg_tde`, you **must** use [`pg_tde_upgrade` :octicons-link-external-16:](https://docs.percona.com/pg-tde/command-line-tools/pg-tde-upgrade.html) instead of `pg_upgrade`. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. The server may start successfully but queries against encrypted tables will fail. !!! note When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following: