Skip to content

Backup with WAL encryption enabled

Danger

Do not rotate encryption keys while a backup is running. This may result in an inconsistent backup and restore failure. This applies to all backup tools.

For more details, see Limitations of open_pg_tde.

To create a backup with WAL encryption enabled:

  1. Copy the open_pg_tde directory from the source server’s data directory, for example /var/lib/postgresql/data/open_pg_tde/, including the wal_keys and 1664_providers files, to the backup destination directory where open_pg_tde_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 open_pg_tde_basebackup -E.

  2. Run:

    open_pg_tde_basebackup -D /path/to/backup -E [aes_128|aes_256]

    Where:

    • -D /path/to/backup specifies the backup location where you have to copy open_pg_tde.
    • -E (or --encrypt-wal) enables WAL encryption and validates that the copied open_pg_tde and provider files are present and that the server key is accessible (required). The -E option accepts a cipher argument. The currently supported values are aes_128 and aes_256. If -E is not specified, open_pg_tde_basebackup attempts to determine the cipher from the server’s key. If no cipher can be determined, open_pg_tde_basebackup defaults to aes_128.

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 backup method compatibility with WAL encryption.
  • The -E flag is only supported with the plain output format (-F p). It cannot be used with the tar output format (-F t).

Key rotation during backups

Danger

Do not rotate encryption keys while a backup is in progress. This applies to all backup tools.

Backups created during key rotation may fail to start during WAL replay and may lead to corruption of encrypted data (tables, indexes, and other relations).

For example, you may see errors such as:

FATAL: failed to retrieve principal key "database_keyXXXX" from key provider "providerYYYY"
CONTEXT: WAL redo at ... ROTATE_PRINCIPAL_KEY ...

To ensure standby recoverability, plan key rotations outside backup windows or take a new full backup after rotation completes.

Restore a backup created with WAL encryption

When you want to restore a backup created with open_pg_tde_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.

Key availability when restoring encrypted backups

A backup created with an earlier key stays encrypted on disk. To restore it, the principal key that was active when the backup was made must still be available in your Key Management System (KMS). open_pg_tde retrieves that principal key from the KMS and uses it to decrypt the internal keys, which then decrypt the table data.

The internal keys are stored within the backup. The principal keys are not; they remain in the KMS.

Note

If the required key or keys are missing, the backup cannot be read.

If the keys still exist but the KMS configuration has changed, use open_pg_tde_change_key_provider to update the configuration.

If the keys were deleted from all accessible KMS sources, the encrypted backup is unrecoverable.

Backup method compatibility with WAL encryption

Tar format (-F t):

  • Works with -X fetch.
  • Does not support -X stream when WAL encryption is enabled. Using open_pg_tde_basebackup -F t -X stream will create a broken replica.

Streaming mode (-X stream):

  • Must specify -E (--encrypt-wal).
  • Without -E, backups may contain decrypted WAL while wal_encryption=on remains in postgresql.conf and open_pg_tde/wal_keys are copied. This leads to startup failures and compromised data in the backup.

Fetch mode (-X fetch):

  • Compatible with encrypted WAL without requiring any additional flags.

None (-X none):

  • Excludes WAL from the backup and is unaffected by WAL encryption.

Note

If the source server has open_pg_tde/wal_keys, running open_pg_tde_basebackup with -X none or -X fetch produces warnings such as:

open_pg_tde_basebackup: warning: the source has WAL keys, but no WAL encryption configured for the target backups
open_pg_tde_basebackup: detail: This may lead to exposed data and broken backup
open_pg_tde_basebackup: hint: Run open_pg_tde_basebackup with -E to encrypt streamed WAL

You can safely ignore the warnings with -X none or -X fetch, since no WAL streaming occurs.