From 0f7aca07cbc27f4899997e40075ac675bd44b921 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 28 Aug 2025 18:06:18 +0300 Subject: [PATCH 1/2] update warnings for basebackup --- .../pg_tde/documentation/docs/how-to/backup-wal-enabled.md | 4 ++-- .../documentation/docs/release-notes/release-notes-v2.0.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md b/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md index 97c2804b40ff2..b8c6bfb70df2b 100644 --- a/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md +++ b/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md @@ -24,9 +24,9 @@ Also copy any external files referenced by your providers configuration (such as ## Key rotation during backups !!! warning - Do not rotate SMGR or WAL encryption keys while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay. + Do not create, change, or rotate global key providers (or their keys) while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay. -Rotations during a base backup can leave the standby in an inconsistent state where it cannot retrieve the correct key history. +Creating, changing, or rotating global key providers (or their keys) during a base backup can leave the standby in an inconsistent state where it cannot retrieve the correct key history. For example, you may see errors such as: diff --git a/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md b/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md index 22c74ba52d346..aa588b793ef1c 100644 --- a/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md +++ b/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md @@ -30,9 +30,9 @@ Clusters that did not use WAL encryption in beta can be upgraded normally. ## Known issues -* Rotating encryption keys while `pg_basebackup` is running may cause standbys or standalone clusters initialized from the backup to fail during WAL replay. +* Creating, changing, or rotating global key providers (or their keys) while `pg_basebackup` is running may cause standbys or standalone clusters initialized from the backup to fail during WAL replay. - Avoid key rotations during backups. Run a new full backup after completing a rotation. + Avoid making these actions during backup windows. Run a new full backup after completing a rotation or provider update. * Using `pg_basebackup` with `--wal-method=fetch` produces warnings. From 836c0f639f89c678b1180c5ac92cec197604fa57 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 28 Aug 2025 18:49:40 +0300 Subject: [PATCH 2/2] update with more corrupt data info to warnings --- contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md | 2 +- .../documentation/docs/release-notes/release-notes-v2.0.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md b/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md index b8c6bfb70df2b..7b51bbbd176ea 100644 --- a/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md +++ b/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md @@ -24,7 +24,7 @@ Also copy any external files referenced by your providers configuration (such as ## Key rotation during backups !!! warning - Do not create, change, or rotate global key providers (or their keys) while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay. + Do not create, change, or rotate global key providers (or their keys) while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay and may also lead to the corruption of encrypted data (tables, indexes, and other relations). Creating, changing, or rotating global key providers (or their keys) during a base backup can leave the standby in an inconsistent state where it cannot retrieve the correct key history. diff --git a/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md b/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md index aa588b793ef1c..5a11ed3300d0b 100644 --- a/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md +++ b/contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md @@ -30,7 +30,7 @@ Clusters that did not use WAL encryption in beta can be upgraded normally. ## Known issues -* Creating, changing, or rotating global key providers (or their keys) while `pg_basebackup` is running may cause standbys or standalone clusters initialized from the backup to fail during WAL replay. +* Creating, changing, or rotating global key providers (or their keys) while `pg_basebackup` is running may cause standbys or standalone clusters initialized from the backup to fail during WAL replay and may also lead to the corruption of encrypted data (tables, indexes, and other relations). Avoid making these actions during backup windows. Run a new full backup after completing a rotation or provider update.