From acaddab9ab83da479589ecef49892c5823042770 Mon Sep 17 00:00:00 2001
From: Dragos Andriciuc <dragos.andriciuc@percona.com>
Date: Fri, 22 Aug 2025 13:40:27 +0300
Subject: [PATCH] PG-1858 Document backing up with WAL with encrypt enabled
 (#534)

- add new topic called # Backing up with WAL encryption enabled
- add two suptopics for other wal methods and restore backup created with wal encrypt
- reword to short form option flags
---
 .../docs/how-to/backup-wal-enabled.md         | 44 +++++++++++++++++++
 contrib/pg_tde/documentation/mkdocs.yml       |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md

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
new file mode 100644
index 00000000000..25a5342b1b4
--- /dev/null
+++ b/contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md
@@ -0,0 +1,44 @@
+# Backup with WAL encryption enabled
+
+To create a backup with WAL encryption enabled:
+
+1. Copy the `pg_tde` directory from the source server’s data directory, for example `/var/lib/postgresql/data/pg_tde/`, including the `wal_keys` and `1664_providers` files, to the backup destination directory where `pg_basebackup` will write the backup.
+
+Also copy any external files referenced by your providers configuration (such as certificate or key files) into the same relative paths under the backup destination, so that they are located and validated by `pg_basebackup -E`.
+
+2. Run:
+
+    ```bash
+    pg_basebackup -D /path/to/backup -E
+    ```
+
+    Where:
+
+    - `-D /path/to/backup` specifies the backup location where you have to copy `pg_tde`
+    - `-E` (or `--encrypt-wal`) enables WAL encryption and validates that the copied `pg_tde` and provider files are present and that the server key is accessible (required)
+
+!!! note
+    - The `-E` flag only works with the `-X stream` option (default). It is not compatible with `-X none` or `-X fetch`. For more information, see [the other WAL methods topic](#other-wal-methods).
+    - The `-E` flag is only supported with the plain output format (`-F p`). It cannot be used with the tar output format (`-F t`).
+
+## Restore a backup created with WAL encryption
+
+When you want to restore a backup created with `pg_basebackup -E`:
+
+1. Ensure all external files referenced by your providers configuration (such as certificates or key files) are also present and accessible at the same relative paths.
+2. Start PostgreSQL with the restored data directory.
+
+## Other WAL methods
+
+The `-X fetch` option works with encrypted WAL without requiring any additional flags.  
+The `-X none` option excludes WAL from the backup and is unaffected by WAL encryption.
+
+If the source server has `pg_tde/wal_keys`, running `pg_basebackup` with `-X none` or `-X fetch` produces warnings such as:
+
+```sql
+pg_basebackup: warning: the source has WAL keys, but no WAL encryption configured for the target backups
+pg_basebackup: detail: This may lead to exposed data and broken backup
+pg_basebackup: hint: Run pg_basebackup with -E to encrypt streamed WAL
+```
+
+You can safely ignore these warnings when using `-X none` or `-X fetch`, since in both cases WAL is not streamed.
diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml
index 388d3672fd9..5ffd25e3236 100644
--- a/contrib/pg_tde/documentation/mkdocs.yml
+++ b/contrib/pg_tde/documentation/mkdocs.yml
@@ -204,6 +204,7 @@ nav:
     - "Configure Multi-tenancy": how-to/multi-tenant-setup.md
     - "Encryption Enforcement": how-to/enforcement.md
     - "Decrypt an Encrypted Table": how-to/decrypt.md
+    - "Backup with WAL encryption enabled": how-to/backup-wal-enabled.md
     - "Restore an encrypted pg_tde backup": how-to/restore-backups.md
   - faq.md
   - "Release notes":