PG-1012 Documented set up of the_heap access method

documentation/_resource/overrides/main.html

@@ -24,8 +24,8 @@
                  {% endif %}
                  <meta property="og:type" content="website" />
                  <meta property="og:title" content="{{ title }}" />
-                 <meta property="og:image" content="https://docs.percona.com/pg-stat-monitor/_images/pg_stat_monitor.png">
-                 <meta property="og:url" content="https://docs.percona.com/pg-stat-monitor/">
+                 <meta property="og:image" content="https://percona-lab.github.io/pg_tde/main/documentation/_images/pg_tde.png">
+                 <meta property="og:url" content="https://percona-lab.github.io/pg_tde/main/">
     <script>
         !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
         posthog.init('phc_7unoI9J6Fm0SMrfDp35xNOpCRTkOAibbffQwdGWbHnL',{api_host:'https://eu.posthog.com'})

documentation/docs/apt.md

@@ -1,6 +1,10 @@
 # Install `pg_tde` on Debian or Ubuntu
 
-In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2).
+The packages for `pg_tde` {{release}} are available in the testing repository for Percona Distribution for PostgreSQL 16. 
+
+The packages for the tech preview `pg_tde` are available in the experimental repository for Percona Distribution for PostgreSQL 17. 
+
+Check the [list of supported platforms](install.md#__tabbed_1_2).
 
 This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html).
 
@@ -23,9 +27,9 @@ You need the `percona-release` repository management tool that enables the desir
 
 2. Fetch the `percona-release` package
 
-   ```bash
-   sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
-   ```
+    ```bash
+    sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
+    ```
 
 3. Install `percona-release`
 
@@ -35,31 +39,58 @@ You need the `percona-release` repository management tool that enables the desir
 
 4. Enable the Percona Distribution for PostgreSQL repository
 
-    ```bash
-    sudo percona-release enable-only ppg-16.2 testing
-    ```
+    === "pg_tde Beta"
+
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion16}} testing
+        ```
+
+    === "pg_tde Tech preview"
+
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion17}} experimental
+        ```
 
 5. Update the local cache
 
     ```bash
     sudo apt-get update
     ```
 
-## Install Percona Distribution for PostgreSQL
+## Install `pg_tde`
+
+=== "pg_tde Beta"
+
+    1. Install Percona Distribution for PostgreSQL. 
+
+        Run the following command to install Percona Distribution for PostgreSQL and the required packages:
 
-To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+        ```bash
+        sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib     percona-postgresql-server-dev-all
+        ```
 
-```bash
-sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all
-```
+    2. Install `pg_tde` packages
+
+        ```bash
+        sudo apt-get install percona-postgresql-16-pg-tde
+        ```
+
+=== "pg_tde Tech preview"
+
+    1. Install Percona Distribution for PostgreSQL. 
+
+        Run the following command to install Percona Distribution for PostgreSQL and the required packages:
 
-## Install `pg_tde` packages
+        ```bash
+        sudo apt-get install -y percona-postgresql-17 percona-postgresql-contrib     percona-postgresql-server-dev-all
+        ```
 
-To install `pg_tde` packages, run the following command:
+    2. Install `pg_tde` packages
+
+        ```bash
+        sudo apt-get install percona-postgresql-17-pg-tde
+        ```
 
-```bash
-sudo apt-get install percona-postgresql-16-pg-tde
-```
 
 ## Next step 
 

documentation/docs/decrypt.md

@@ -0,0 +1,44 @@
+# Decrypt an encrypted table
+
+## Method 1. Change the access method
+
+If you encrypted a table with the `tde_heap` or `tde_heap_basic` access method and need to decrypt it, run the following command against the desired table (`mytable` in the example below):
+
+```sql
+ALTER TABLE mytable SET access method heap;
+```
+
+Check that the table is not encrypted:
+
+```sql
+SELECT pg_tde_is_encrypted('mytable');
+```
+
+The output returns `f` meaning that the table is no longer encrypted. 
+
+!!! note ""
+
+    In the same way you can re-encrypt the data with the `tde_heap_basic` access method. 
+
+    ```sql
+    ALTER TABLE mytable SET access method tde_heap_basic;
+    ```
+
+    Note that the indexes and WAL files will no longer be encrypted.
+
+## Method 2. Create a new unencrypted table on the base of the encrypted one
+
+Alternatively, you can create a new unencrypted table with the same structure and data as the initial table. For example, the original encrypted table is `EncryptedCustomers`. Use the following command to create a new table `Customers`: 
+
+```sql
+CREATE TABLE Customers AS
+SELECT * FROM EncryptedCustomers;
+```
+
+The new table `Customers` inherits the structure and the data from `EncryptedCustomers`.
+
+(Optional) If you no longer need the `EncryptedCustomers` table, you can delete it.
+
+```sql
+DROP TABLE EncryptedCustomers;
+```

documentation/docs/index.md

@@ -26,14 +26,18 @@
 
 ## Supported PostgreSQL versions
 
-`pg_tde` is currently based on PostgreSQL 16.0 and supported for Percona Distribution for PostgreSQL 16.x and upstream PostgreSQL 16.x. 
+`pg_tde` is currently based on Percona Server for PostgreSQL 17.0 and upstream PostgreSQL 16.x. 
+
+It is also supported for Percona Distribution for PostgreSQL 16.x and upstream PostgreSQL 16.x. 
 
 ## Future releases
 
 The following is planned for future releases of `pg_tde`:
 
 * Encryption of indexes and `NULL` bitmaps of tuples
 * Logical replication support
+* KMIP integration for key management
+* Global principal key management
 
 
 

documentation/docs/install.md

@@ -21,12 +21,10 @@ Install `pg_tde` using one of available installation methods:
 
     Starting with Aplha1 version, you can install the extension as package from Percona repositories using the `percona-release` tool. The packages are available for the following operating systems:
 
-    - Red Hat Enterprise Linux and CentOS 7
     - Red Hat Enterprise Linux 8 and compatible derivatives
     - Red Hat Enterprise Linux 9 and compatible derivatives
     - Ubuntu 20.04 (Focal Fossa)
     - Ubuntu 22.04 (Jammy Jellyfish)
-    - Debian 10 (Buster)
     - Debian 11 (Bullseye) 
     - Debian 12 (Bookworm)
 
@@ -35,6 +33,8 @@ Install `pg_tde` using one of available installation methods:
 
 === "Build from source"
 
+    The following steps apply to PostgreSQL 16. To build `pg_tde` for PostgreSQL 17, replace the version in the commands. 
+
     1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian:
 
         ```sh

documentation/docs/setup.md

@@ -1,5 +1,7 @@
 # Set up `pg_tde`
 
+## Enable extension
+
 Load the `pg_tde` at the start time. The extension requires additional shared memory; therefore,  add the `pg_tde` value for the `shared_preload_libraries` parameter and restart the `postgresql` instance.
 
 1. Use the [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html) command from `psql` terminal to modify the `shared_preload_libraries` parameter.
@@ -38,7 +40,9 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         psql -d template1 -c 'CREATE EXTENSION pg_tde;'
         ```
 
-4. Set up a key provider for the database where you have enabled the extension
+## Key provider configuration
+
+1. Set up a key provider for the database where you have enabled the extension
 
     === "With HaschiCorp Vault"
 
@@ -63,7 +67,7 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         ```
 
 
-5. Add a principal key
+2. Add a principal key
 
     ```sql
     SELECT pg_tde_set_principal_key('name-of-the-principal-key', 'provider-name');
@@ -72,6 +76,67 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
    <i info>:material-information: Info:</i> The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup.
 
 
+## WAL encryption configuration (tech preview)
+
+Perform this step if you [installed Percona Server for PostgreSQL :octicons-link-external-16:](https://docs.percona.com/postgresql/17/installing.html). Otherwise, proceed to the [Next steps](#next-steps).
+
+After you [enabled `pg_tde`](#enable-extension) and started the Percona Server for PostgreSQL, a principal key and a keyring for WAL are created. Now you need to instruct `pg_tde ` to encrypt WAL files by configuring WAL encryption. Here's how to do it:
+
+1. Enable WAL level encryption using the `ALTER SYSTEM SET` command:
+
+    ```sql
+    ALTER SYSTEM set pg_tde.wal_encrypt = on;
+    ```
+
+2. Restart the server to apply the changes.
+
+    * On Debian and Ubuntu:    
+
+       ```sh
+       sudo systemctl restart postgresql.service
+       ```
+
+    * On RHEL and derivatives
+
+       ```sh
+       sudo systemctl restart postgresql-17
+       ```
+
+3. We highly recommend you to create your own keyring and rotate the principal key. This is because the default principal key is created from the local keyfile and is stored unencrypted. 
+
+   Set up the key provider for WAL encryption
+
+   === "With HaschiCorp Vault"
+
+        ```sql
+        SELECT pg_tde_add_key_provider_vault_v2('PG_TDE_GLOBAL','provider-name',:'secret_token','url','mount','ca_path');
+        ``` 
+
+        where: 
+
+        * `PG_TDE_GLOBAL` is the constant that defines the WAL encryption key  
+        * `provider-name` is the name you define for the key provider
+        * `url` is the URL of the Vault server
+        * `mount` is the mount point where the keyring should store the keys
+        * `secret_token` is an access token with read and write access to the above mount point
+        * [optional] `ca_path` is the path of the CA file used for SSL verification
+
+
+    === "With keyring file"
+
+        This setup is intended for development and stores the keys unencrypted in the specified data file.    
+
+        ```sql
+        SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file');
+        ```
+
+4. Rotate the principal key. Don't forget to specify the `PG_TDE_GLOBAL` constant to rotate only the principal key for WAL.
+
+    ```sql
+    SELECT pg_tde_rotate_principal_key('PG_TDE_GLOBAL', 'new-principal-key', 'provider-name');
+    ```
+
+Now all WAL files are encrypted.
 
 ## Next steps
 

documentation/docs/switch.md

@@ -0,0 +1,5 @@
+# Switch from Percona Server for PostgreSQL to PostgreSQL Community
+
+Percona Server for PostgreSQL and PostgreSQL Community are binary compatible and enable you to switch from one to another. Here's how:
+
+1. If you used the `tde_heap` (tech preview feature) access method for encryption, either re-encrypt the data using the `tde_heap_basic` access method, or [decrypt](decrypt.md) it completely 

documentation/docs/test.md

@@ -2,34 +2,76 @@
 
 To check if the data is encrypted, do the following:
 
-1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap_basic`. To enable data encryption, create the table using this access method as follows:
+=== "pg_tde Beta"
 
-    ```sql
-    CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap_basic;
-    ```
+    1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde`    extension creates the table access method `tde_heap_basic`. To enable data encryption, create the table using this access method as follows:
 
-    !!! hint
+        ```sql
+        CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap_basic;
+        ```
+
+        !!! hint
+
+            You can enable data encryption by default by setting the `default_table_access_method` to     `tde_heap_basic`:
+
+            ```sql
+            ALTER SYSTEM  SET default_table_access_method=tde_heap;
+            ```
+
+            Reload the configuration to apply the changes:
+
+            ```
+            SELECT pg_reload_conf();
+            ```
+
+    2. Run the following function:
+
+        ```sql
+        SELECT pg_tde_is_encrypted('table_name');
+        ```
 
-        You can enable data encryption by default by setting the `default_table_access_method` to `tde_heap_basic`:
+        The function returns `t` if the table is encrypted and `f` - if not.
+
+    3. Rotate the principal key when needed:
 
         ```sql
-        SET default_table_access_method = tde_heap_basic;
+        SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin
+        -- or
+        SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name
+        -- or
+        SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider
         ```
-
-2. Run the following function:
 
-    ```sql
-    SELECT pg_tde_is_encrypted('table_name');
-    ```
+=== "pg_tde Tech preview"
+
+    !!! warning
 
-    The function returns `t` if the table is encrypted and `f` - if not.
+        This is the tech preview functionality. Its scope is not yet finalized and can change anytime.** Use it only for testing purposes.**
+
+    1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde`    extension creates the table access method `tde_heap`. To enable data encryption, create the table using this access method as follows:
+
+        ```sql
+        CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap;
+        ```
+
+    2. Run the following function:
+
+        ```sql
+        SELECT pg_tde_is_encrypted('table_name');
+        ```
+
+        The function returns `t` if the table is encrypted and `f` - if not.
+
+    3. Rotate the principal key when needed:
+
+        ```sql
+        SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin
+        -- or
+        SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name
+        -- or
+        SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider
+        ```
 
-3. Rotate the principal key when needed:
+!!! hint
 
-    ```sql
-    SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin
-    -- or
-    SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name
-    -- or
-    SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider
-    ```
+    If you no longer wish to use `pg_tde` or wish to switch to using the `tde_heap_basic` access method, see how you can [decrypt your data](decrypt.md).