From 265799a8ce1759030cb31ba490270c102e1d3746 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Tue, 5 Aug 2025 12:15:26 +0300 Subject: [PATCH 1/3] Add WAL content for 2.0 release --- .../pg_tde/documentation/docs/architecture/architecture.md | 5 +---- .../documentation/docs/command-line-tools/pg-waldump.md | 3 --- contrib/pg_tde/documentation/docs/faq.md | 5 +---- contrib/pg_tde/documentation/docs/functions.md | 3 --- contrib/pg_tde/documentation/docs/index/tde-limitations.md | 1 - contrib/pg_tde/documentation/docs/test.md | 2 +- contrib/pg_tde/documentation/docs/wal-encryption.md | 7 +++---- contrib/pg_tde/documentation/mkdocs.yml | 2 +- 8 files changed, 7 insertions(+), 21 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/architecture/architecture.md b/contrib/pg_tde/documentation/docs/architecture/architecture.md index bc1df2f25df6e..2902d1553898e 100644 --- a/contrib/pg_tde/documentation/docs/architecture/architecture.md +++ b/contrib/pg_tde/documentation/docs/architecture/architecture.md @@ -20,7 +20,7 @@ The following sections break down the key architectural components of this desig * Indexes * Sequences * Temporary tables -* Write Ahead Log (WAL), still in beta. **Do not enable this feature in production environments**. +* Write Ahead Log (WAL) **Extension** means that `pg_tde` should be implemented only as an extension, possibly compatible with any PostgreSQL distribution, including the open source community version. This requires changes in the PostgreSQL core to make it more extensible. Therefore, `pg_tde` currently works only with the [Percona Server for PostgreSQL](https://docs.percona.com/postgresql/17/index.html) - a binary replacement of community PostgreSQL and included in Percona Distribution for PostgreSQL. @@ -82,9 +82,6 @@ Later decisions are made using a slightly modified Storage Manager (SMGR) API: w ### WAL encryption -!!! note - The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. - WAL encryption is controlled globally via a global GUC variable, `pg_tde.wal_encrypt`, that requires a server restart. WAL keys also contain the [LSN](https://www.postgresql.org/docs/17/wal-internals.html) of the first WAL write after key creation. This allows `pg_tde` to know which WAL ranges are encrypted or not and with which key. diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/pg-waldump.md b/contrib/pg_tde/documentation/docs/command-line-tools/pg-waldump.md index 0362eadcef7f0..a3ac50df4df02 100644 --- a/contrib/pg_tde/documentation/docs/command-line-tools/pg-waldump.md +++ b/contrib/pg_tde/documentation/docs/command-line-tools/pg-waldump.md @@ -2,9 +2,6 @@ [`pg_waldump` :octicons-link-external-16:](https://www.postgresql.org/docs/current/pgwaldump.html) is a tool to display a human-readable rendering of the Write-Ahead Log (WAL) of a PostgreSQL database cluster. -!!! warning - The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. - To read encrypted WAL records, `pg_waldump` supports the following additional arguments: * `keyring_path` is the directory where the keyring configuration files for WAL are stored. The following files are included: diff --git a/contrib/pg_tde/documentation/docs/faq.md b/contrib/pg_tde/documentation/docs/faq.md index b244818371144..9e9c88f181a65 100644 --- a/contrib/pg_tde/documentation/docs/faq.md +++ b/contrib/pg_tde/documentation/docs/faq.md @@ -94,9 +94,6 @@ The principal key is used to encrypt the internal keys. The principal key is sto ### WAL encryption -!!! note - WAL encryption is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. - WAL encryption is done globally for the entire database cluster. All modifications to any database within a PostgreSQL cluster are written to the same WAL to maintain data consistency and integrity and ensure that PostgreSQL cluster can be restored to a consistent state. Therefore, WAL is encrypted globally. When you turn on WAL encryption, `pg_tde` encrypts entire WAL files starting from the first WAL write after the server was started with the encryption turned on. @@ -140,7 +137,7 @@ Since the `SET ACCESS METHOD` command drops hint bits and this may affect the pe You must restart the database in the following cases to apply the changes: * after you enabled the `pg_tde` extension -* when enabling WAL encryption, which is currently in beta. **Do not enable this feature in production environments**. +* when enabling WAL encryption After that, no database restart is required. When you create or alter the table using the `tde_heap` access method, the files are marked as those that require encryption. The encryption happens at the storage manager level, before a transaction is written to disk. Read more about [how tde_heap works](index/table-access-method.md#how-tde_heap-works-with-pg_tde). diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 73f2da208faa0..9ef29afcc44fc 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -283,9 +283,6 @@ SELECT pg_tde_set_server_key_using_global_key_provider( ); ``` -!!! warning - The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. -======= The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation: * If set to `true`, a new key must be unique. diff --git a/contrib/pg_tde/documentation/docs/index/tde-limitations.md b/contrib/pg_tde/documentation/docs/index/tde-limitations.md index 8e3376671aea7..10c1627b789ce 100644 --- a/contrib/pg_tde/documentation/docs/index/tde-limitations.md +++ b/contrib/pg_tde/documentation/docs/index/tde-limitations.md @@ -3,6 +3,5 @@ The following are current limitations of `pg_tde`: * System tables, which include statistics data and database statistics, are currently **not encrypted**. -* The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. [View the versions and supported deployments :material-arrow-right:](supported-versions.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/test.md b/contrib/pg_tde/documentation/docs/test.md index be73e73863e76..e4578e6bf6ed3 100644 --- a/contrib/pg_tde/documentation/docs/test.md +++ b/contrib/pg_tde/documentation/docs/test.md @@ -59,4 +59,4 @@ ALTER TABLE table_name SET ACCESS METHOD tde_heap; ## Next steps -[Configure WAL Encryption (tech preview) :material-arrow-right:](wal-encryption.md){.md-button} +[Configure WAL encryption :material-arrow-right:](wal-encryption.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/wal-encryption.md b/contrib/pg_tde/documentation/docs/wal-encryption.md index 33547d0e359c4..6de83230c11de 100644 --- a/contrib/pg_tde/documentation/docs/wal-encryption.md +++ b/contrib/pg_tde/documentation/docs/wal-encryption.md @@ -1,7 +1,4 @@ -# Configure WAL Encryption (tech preview) - -!!! warning - The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. +# Configure WAL encryption Before enabling WAL encryption, follow the steps below to create a principal key and configure it for WAL: @@ -118,3 +115,5 @@ Now WAL files start to be encrypted for both encrypted and unencrypted tables. For more technical references related to architecture, variables or functions, see: [Technical Reference](advanced-topics/tech-reference.md){.md-button} + +💬 Need help customizing this for your infrastructure? [Contact Percona support :octicons-link-external-16:](get-help.md) \ No newline at end of file diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index 43725bb5de5e6..bc97c267b4777 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -185,7 +185,7 @@ nav: - "Keyring file configuration": global-key-provider-configuration/keyring.md - "2.2 Global Principal Key configuration": global-key-provider-configuration/set-principal-key.md - "3. Validate encryption with pg_tde": test.md - - "4. Configure WAL encryption (tech preview)": wal-encryption.md + - "4. Configure WAL encryption": wal-encryption.md - "Technical reference": - "Overview": advanced-topics/tech-reference.md - "Architecture": architecture/architecture.md From c150be42db0a86afb6c98cf955b0459179cf8c36 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 7 Aug 2025 15:09:51 +0300 Subject: [PATCH 2/3] improve functions.md with small text fix and reword introductory paragraph for Global Principal key config - fix a small space in functions and add * to pg_tde_set_ - reworded introductory paragraph in Global Principal Key configuration, added descriptions for the two functions used to config the global principal key - added explanatory paragraph to Next steps for clarity --- contrib/pg_tde/documentation/docs/functions.md | 2 +- .../set-principal-key.md | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 9ef29afcc44fc..cd1241bcdd0d8 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -240,7 +240,7 @@ SELECT pg_tde_create_key_using_database_key_provider( ### pg_tde_create_key_using_global_key_provider -Creates a principal key at a global key provider with the given name. Use this key later with the `pg_tde_set_` series of functions. +Creates a principal key at a global key provider with the given name. Use this key later with the `pg_tde_set_*` series of functions. ```sql SELECT pg_tde_create_key_using_global_key_provider( diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md index 1d4e55788d5df..781ce5869ddba 100644 --- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md @@ -1,10 +1,16 @@ # Global Principal Key configuration -You can configure a default principal key using a global key provider. This key will be used by all databases that do not have their own encryption keys configured. The function **both** sets the principal key and rotates internal keys as needed. +You can configure a default principal key using a global key provider. This key is used by all databases that do not have their own encryption keys configured. + +There are two main functions for this: + +- [pg_tde_create_key_using_global_key_provider()](../functions.md#pg_tde_create_key_using_global_key_provider) creates a principal key at a global key provider +- [pg_tde_set_default_key_using_global_key_provider()](../functions.md#pg_tde_set_default_key_using_global_key_provider) sets the default principal key and rotates the internal encryption key if one is already configured ## Create a default principal key !!! note + The sample output below is for demonstration purposes only. Be sure to replace the key name and provider with your actual values. To create a global principal key, run: @@ -57,6 +63,7 @@ SELECT pg_tde_set_default_key_using_global_key_provider( * `global_vault_provider` is the name of the global key provider you previously configured. !!! note + If no error is reported, the action completed successfully. ## How key generation works @@ -64,8 +71,11 @@ SELECT pg_tde_set_default_key_using_global_key_provider( The key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider. !!! note + This process sets the **default principal key for the entire server**. Any database without a key explicitly configured will fall back to this key. ## Next steps +To confirm that encryption is working as expected, follow the validation steps: + [Validate Encryption with pg_tde :material-arrow-right:](../test.md){.md-button} From 1c12c70064064c98b8be190a17bd1d708ff3aaa9 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 14 Aug 2025 17:53:58 +0300 Subject: [PATCH 3/3] add WAL tool support to limitations, improve flow, add button to setup --- .../docs/index/tde-limitations.md | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/index/tde-limitations.md b/contrib/pg_tde/documentation/docs/index/tde-limitations.md index 10c1627b789ce..902715bc61ca8 100644 --- a/contrib/pg_tde/documentation/docs/index/tde-limitations.md +++ b/contrib/pg_tde/documentation/docs/index/tde-limitations.md @@ -1,7 +1,29 @@ # Limitations of pg_tde -The following are current limitations of `pg_tde`: +The following limitations apply to the current release: -* System tables, which include statistics data and database statistics, are currently **not encrypted**. +* PostgreSQL’s internal system tables, which include statistics and metadata, are not encrypted. +* `pg_createsubscriber` is not supported. + +## WAL encryption tool support + +The following tools and extensions in Percona Distribution for PostgreSQL have been tested and verified to work with `pg_tde` WAL encryption: + +??? note "Click to expand" + * Patroni + * `pg_basebackup` (with `--wal-method=stream`) + * `pg_resetwal` + * `pg_rewind` + * `pg_upgrade` + * `pg_waldump` + * pgBackRest + +## Next steps + +Check which PostgreSQL versions and deployment types are compatible with `pg_tde` before planning your installation. [View the versions and supported deployments :material-arrow-right:](supported-versions.md){.md-button} + +Begin the installation process when you’re ready to set up encryption. + +[Start installing `pg_tde`](../install.md){.md-button}