percona · Andriciuc · Jul 25, 2025 · Jul 11, 2025 · Jul 22, 2025 · Jul 22, 2025
@@ -1,7 +1,7 @@
-# Technical Reference
+# Overview of technical capabilities
 
 This section covers the internal components and tools that power `pg_tde`.
 
 Use it to understand how encryption is implemented, fine-tune a configuration, leverage advanced CLI tools and functions for diagnostics and customization.
 
-[Architecture](../architecture/index.md){.md-button} [GUC Variables](../variables.md){.md-button} [Functions](../functions.md){.md-button}
+[Architecture](../architecture/architecture.md){.md-button} [GUC Variables](../variables.md){.md-button} [Functions](../functions.md){.md-button}
@@ -167,7 +167,7 @@ Key provider configuration or location may change. For example, a service is mov
 
 In certain cases you can't use SQL functions to manage key providers. For example, if the key provider changed while the server wasn't running and is therefore unaware of these changes. The startup can fail if it needs to access the encryption keys.
 
-For such situations, `pg_tde` also provides [command line tools](../command-line-tools/index.md) to recover the database.
+For such situations, `pg_tde` also provides [command line tools](../command-line-tools/cli-tools.md) to recover the database.
 
 ### Sensitive key provider information
 

@@ -1,4 +1,4 @@
-# pg_tde CLI Tools
+# Overview of pg_tde CLI tools
 
 The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. These include:
 

@@ -142,7 +142,7 @@ 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**.
 
-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).
+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).
 
 ## What happens to my data if I lose a principal key?
 

@@ -19,4 +19,4 @@ The following features are available for the extension:
 * Table-level granularity for encryption and access control
 * Multiple [Key management options](global-key-provider-configuration/index.md)
 
-[What is Transparent Data Encryption (TDE)?](index/index.md){.md-button} [Install pg_tde to get started](install.md){.md-button}
+[Learn more about TDE and pg_tde :material-arrow-right:](index/about-tde.md){.md-button} [Get started with installation :material-arrow-right:](install.md){.md-button}
@@ -1,4 +1,4 @@
-# Keyring File Configuration
+# Keyring file configuration
 
 This setup is intended for development and stores the keys unencrypted in the specified data file.
 

@@ -1,4 +1,4 @@
-# Fortanix KMIP Server Configuration
+# Fortanix KMIP server configuration
 
 `pg_tde` is compatible with Fortanix Data Security Manager (DSM) via the KMIP protocol. For a full setup guide, see [the Fortanix KMIP documentation here](https://support.fortanix.com/docs/users-guide-account-client-configurations?highlight=KMIP#23-kmip-clients).
 

@@ -1,4 +1,4 @@
-# Using OpenBao as a Key Provider
+# Using OpenBao as a key provider
 
 You can configure `pg_tde` to use OpenBao as a global key provider for managing encryption keys securely.
 

@@ -1,4 +1,4 @@
-# KMIP Configuration
+# KMIP configuration
 
 To use a Key Management Interoperability Protocol (KMIP) server with `pg_tde`, you must configure it as a global key provider. This setup enables `pg_tde` to securely fetch and manage encryption keys from a centralized key management appliance.
 

@@ -1,4 +1,4 @@
-# Thales KMIP Server Configuration
+# Thales KMIP server configuration
 
 `pg_tde` is compatible with the Thales CipherTrust Manager via the KMIP protocol. For a full setup guide, see [the Thales documentation](https://thalesdocs.com/ctp/cm/2.19/reference/kmip-ref/index.html?).
 

@@ -1,4 +1,4 @@
-# Configure Key Management (KMS)
+# Key management overview
 
 In production environments, storing encryption keys locally on the PostgreSQL server can introduce security risks. To enhance security, `pg_tde` supports integration with external Key Management Systems (KMS) through a Global Key Provider interface.
 
@@ -13,4 +13,6 @@ To use an external KMS with `pg_tde`, follow these two steps:
 
 Select your prefered configuration from the links below:
 
-[KMIP Configuration :material-arrow-right:](kmip-server.md){.md-button} [Vault Configuration :material-arrow-right:](vault.md){.md-button} [Keyring File Configuration (not recommended) :material-arrow-right:](keyring.md){.md-button}
+[KMIP Configuration :material-arrow-right:](kmip-server.md){.md-button}
+[Vault Configuration :material-arrow-right:](vault.md){.md-button}
+[Keyring File Configuration (not recommended) :material-arrow-right:](keyring.md){.md-button}
@@ -1,4 +1,4 @@
-# Global Principal Key Configuration
+# 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.
 

@@ -1,4 +1,4 @@
-# Vault Configuration
+# Vault configuration
 
 You can configure `pg_tde` to use HashiCorp Vault as a global key provider for managing encryption keys securely.
 

@@ -2,9 +2,9 @@
 
 The steps below describe how to set up multi-tenancy with `pg_tde`. Multi-tenancy allows you to encrypt different databases with different keys. This provides granular control over data and enables you to introduce different security policies and access controls for each database so that only authorized users of specific databases have access to the data.
 
-If you don't need multi-tenancy, use the global key provider. See the configuration steps from the [Configure pg_tde](../setup.md) section.
+If you don't need multi-tenancy, use the global key provider. See the configuration steps from the [Configure pg_tde :octicons-link-external-16:](../setup.md) section.
 
-For how to enable WAL encryption, refer to the [Configure WAL Encryption](../wal-encryption.md) section.
+For how to enable WAL encryption, refer to the [Configure WAL Encryption :octicons-link-external-16:](../wal-encryption.md) section.
 
 --8<-- "kms-considerations.md"
 
@@ -32,7 +32,7 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
        sudo systemctl restart postgresql-17
        ```
 
-3. Create the extension using the [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) command. You must have the privileges of a superuser or a database owner to use this command. Connect to `psql` as a superuser for a database and run the following command:
+3. Create the extension using the [CREATE EXTENSION :octicons-link-external-16:](https://www.postgresql.org/docs/current/sql-createextension.html) command. You must have the privileges of a superuser or a database owner to use this command. Connect to `psql` as a superuser for a database and run the following command:
 
     ```
     CREATE EXTENSION pg_tde;
@@ -50,15 +50,15 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
 
 ## Key provider configuration
 
-You must do these steps for every database where you have created the extension. For more information on configurations, please see the [Configure Key Management (KMS)](../global-key-provider-configuration/index.md) topic.
+You must do these steps for every database where you have created the extension. For more information on configurations, please see the [Configure Key Management (KMS) :octicons-link-external-16:](../global-key-provider-configuration/overview.md) topic.
 
 1. Set up a key provider.
 
     === "With KMIP server"
 
         The KMIP server setup is out of scope of this document. 
 
-        Make sure you have obtained the root certificate for the KMIP server and the keypair for the client. The client key needs permissions to create / read keys on the server. Find the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine).
+        Make sure you have obtained the root certificate for the KMIP server and the keypair for the client. The client key needs permissions to create / read keys on the server. Find the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine :octicons-link-external-16:](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine).
 
         For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.
 

@@ -6,6 +6,6 @@ Percona Transparent Data Encryption for PostgreSQL (`pg_tde`) is an open source,
     There is no safe upgrade path from the previous versions, such as Release Candidate 2, to the General Availability (GA) version of `pg_tde`.  
     We recommend starting with a **clean installation** for GA deployments. Avoid using RC environments in production.
 
-[Overview](index/index.md){.md-button}
-[Get Started](install.md){.md-button}
-[What's new in pg_tde {{release}}](release-notes/release-notes.md){.md-button}
+[Learn more about TDE and pg_tde :material-arrow-right:](index/about-tde.md){.md-button}
+[Get started with installation :material-arrow-right:](install.md){.md-button}
+[Check out what's new in pg_tde {{release}} :material-arrow-right:](release-notes/release-notes.md){.md-button}
@@ -0,0 +1,12 @@
+# About Transparent Data Encryption
+
+Transparent Data Encryption (TDE) protects your data at rest by ensuring that even if the underlying storage is compromised, the data remains unreadable without the correct decryption keys. This is especially critical for environments handling sensitive, regulated, or high-value information.
+
+This process runs transparently in the background, with minimal impact on database operations.
+
+Use the links below to explore how `pg_tde` helps secure your PostgreSQL deployments:
+
+[Discover the benefits of pg_tde :material-arrow-right:](how-tde-helps.md){.md-button}
+[Understand pg_tde limitations :material-arrow-right:](tde-limitations.md){.md-button}
+[View the full feature list :material-arrow-right:](../features.md){.md-button}
+[Get started with installation :material-arrow-right:](../install.md){.md-button}
@@ -1,4 +1,4 @@
-# How TDE Works
+# How pg_tde works
 
 To encrypt the data, two types of keys are used:
 
@@ -7,7 +7,7 @@ To encrypt the data, two types of keys are used:
 
 !!! note
 
-    For more information on managing and storing principal keys externally, see [Configure Global Key Provider](../global-key-provider-configuration/index.md).
+    For more information on managing and storing principal keys externally, see [Configure Global Key Provider](../global-key-provider-configuration/overview.md).
 
 You have the following options to store and manage principal keys externally:
 
@@ -24,4 +24,4 @@ The internal key itself is encrypted using the principal key. The principal key
 
 Similarly when the user queries the encrypted table, the principal key is retrieved from the key store to decrypt the internal key. Then the same unique internal key for that table is used to decrypt the data, and unencrypted data gets returned to the user. So, effectively, every TDE table has a unique key, and each table key is encrypted using the principal key.
 
-[Encrypted Data Scope](tde-encrypts.md){.md-button}
+[Understand the encrypted data scope :material-arrow-right:](tde-encrypts.md){.md-button}
@@ -1,4 +1,6 @@
-# TDE Benefits
+# Benefits of pg_tde
+
+The benefits of using `pg_tde` are outlined below for different users and organizations.
 
 ## Benefits for organizations
 
@@ -11,10 +13,10 @@
 * **Operational simplicity:** Works transparently without requiring major application changes.
 * **Defense in depth:** Adds another layer of protection to existing controls like TLS (encryption in transit), access control, and role-based permissions.
 
-When combined with the external Key Management Systems (KMS), TDE enables centralized control, auditing, and rotation of encryption keys—critical for secure production environments.
+When combined with the external Key Management Systems (KMS), `pg_tde` enables centralized control, auditing, and rotation of encryption keys—critical for secure production environments.
 
 !!! admonition "See also"
 
-    Percona Blog: [Transparent Data Encryption (TDE)](https://www.percona.com/blog/transparent-data-encryption-tde/)
+    You can find more information on Transparent Data Encryption (TDE) in [this article](https://www.percona.com/blog/transparent-data-encryption-tde/).
 
-[How TDE works](how-does-tde-work.md){.md-button}
+[Learn how pg_tde works :material-arrow-right:](how-does-tde-work.md){.md-button}
@@ -1,4 +1,4 @@
-# Versions and Supported PostgreSQL Deployments
+# Versions and Supported PostgreSQL deployments
 
 The `pg_tde` extension is available for [Percona Server for PostgreSQL 17.x](https://docs.percona.com/postgresql/17/postgresql-server.html), an open source, drop-in replacement for PostgreSQL Community. This version provides the `tde_heap` access method and offers [full encryption capabilities](../features.md), including encryption of tables, indexes and WAL data.
 
@@ -18,4 +18,4 @@ By using our PostgreSQL distribution, you get:
 
 Still unsure which deployment fits your needs? [Contact our experts](https://www.percona.com/about/contact) to find the best solution for your environment.
 
-[Get Started: Install pg_tde :material-arrow-right:](../install.md){.md-button}
+[Get started with installation :material-arrow-right:](../install.md){.md-button}
@@ -1,4 +1,4 @@
-# Table Access Methods and TDE
+# Table Access Methods and pg_tde
 
 A table access method is the way how PostgreSQL stores the data in a table. The default table access method is `heap`. PostgreSQL organizes data in a heap structure, meaning there is no particular order to the rows in the table. Each row is stored independently and identified by its unique row identifier (TID).
 
@@ -28,7 +28,7 @@ CREATE TABLE table_name (
 ) USING tde_heap;
 ```
 
-### How tde_heap works
+### How tde_heap works with pg_tde
 
 The `tde_heap` access method works on top of the default `heap` access method and is a marker to point which tables require encryption. It uses the custom storage manager TDE SMGR, which becomes active only after you installed the `pg_tde` extension.
 
@@ -88,4 +88,4 @@ Here is how you can set the new default table access method:
     SELECT pg_reload_conf();
     ```
 
-[Limitations of TDE](tde-limitations.md){.md-button}
+[Understand pg_tde's limitations :material-arrow-right:](tde-limitations.md){.md-button}
@@ -1,4 +1,4 @@
-# Encrypted Data Scope
+# Encrypted data scope
 
 `pg_tde` encrypts the following components:
 
@@ -7,6 +7,4 @@
 * **Write-Ahead Log (WAL) data** for the entire database cluster. This includes WAL data in encrypted and non-encrypted tables.
 * **Indexes** on encrypted tables.
 
-!!!
-
-[Table Access Methods and TDE](table-access-method.md){.md-button}
+[Check out the table access methods :material-arrow-right:](table-access-method.md){.md-button}
@@ -1,11 +1,8 @@
 # Limitations of pg_tde
 
-* Keys in the local keyfile are stored **unencrypted**. For better security we recommend using the [Key management storage](../global-key-provider-configuration/index.md).
+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**.
-* `pg_tde` RC 2 is incompatible with `pg_tde` Beta2 due to significant changes in code. There is no direct upgrade flow from one version to another. You must [uninstall](../how-to/uninstall.md) `pg_tde` Beta2 first and then [install](../install.md) and configure the new Release Candidate version.
-
-!!! important
-    This is the {{release}} version of the extension and **it is not meant for production use yet**. We encourage you to use it in testing environments and [provide your feedback](https://forums.percona.com/c/postgresql/pg-tde-transparent-data-encryption-tde/82).
 
-[Versions and Supported PostgreSQL Deployments](supported-versions.md){.md-button}
+[View the versions and supported deployments :material-arrow-right:](supported-versions.md){.md-button}
@@ -39,4 +39,4 @@ Follow the configuration steps below to continue:
 
 If you’ve already completed these steps, feel free to skip ahead to a later section:
 
- [Configure Key Management (KMS)](global-key-provider-configuration/index.md){.md-button} [Validate Encryption with pg_tde](test.md){.md-button} [Configure WAL encryption](wal-encryption.md){.md-button}
+ [Configure Key Management (KMS)](global-key-provider-configuration/overview.md){.md-button} [Validate Encryption with pg_tde](test.md){.md-button} [Configure WAL encryption](wal-encryption.md){.md-button}
@@ -1,6 +1,6 @@
 # pg_tde Alpha 1 (2024-03-28)
 
-`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/index.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
+`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/about-tde.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
 
 [Get started](../install.md){.md-button}
 

@@ -1,6 +1,6 @@
 # pg_tde Beta (2024-06-30)
 
-`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/index.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
+`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/about-tde.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
 
 [Get started](../install.md){.md-button}
 

@@ -1,6 +1,6 @@
 # pg_tde Beta 2 (2024-12-16)
 
-`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/index.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
+`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/about-tde.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
 
 [Get started](../install.md){.md-button}
 

@@ -1,6 +1,6 @@
 # pg_tde Release Candidate 1 ({{date.RC}})
 
-`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/index.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
+`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/about-tde.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
 
 [Get started](../install.md){.md-button}
 

@@ -1,6 +1,6 @@
 # pg_tde Release Candidate 2 ({{date.RC2}})
 
-`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/index.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
+`pg_tde` extension brings in [Transparent Data Encryption (TDE)](../index/about-tde.md) to PostgreSQL and enables you to keep sensitive data safe and secure.
 
 [Get Started](../install.md){.md-button}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -39,4 +39,4 @@ Follow the configuration steps below to continue:

		If you’ve already completed these steps, feel free to skip ahead to a later section:

		[Configure Key Management (KMS)](global-key-provider-configuration/index.md){.md-button} [Validate Encryption with pg_tde](test.md){.md-button} [Configure WAL encryption](wal-encryption.md){.md-button}
		[Configure Key Management (KMS)](global-key-provider-configuration/overview.md){.md-button} [Validate Encryption with pg_tde](test.md){.md-button} [Configure WAL encryption](wal-encryption.md){.md-button}