PG-1012 Documented set up of the_heap access method

Added How to decrypt a table

documentation/decrypt.md

@@ -0,0 +1,34 @@
+# Decrypt encrypted table
+
+## Method 1. Change the access method
+
+If you encrypted a table with the `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.
+
+## 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/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,9 +39,17 @@ 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
 
@@ -45,21 +57,40 @@ You need the `percona-release` repository management tool that enables the desir
     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:
+
+        ```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. 
     
-To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+        Run the following command to install Percona Distribution for PostgreSQL and the required packages:
 
-```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-17 percona-postgresql-contrib     percona-postgresql-server-dev-all
+        ```
 
-## Install `pg_tde` packages
+    2. Install `pg_tde` packages
         
-To install `pg_tde` packages, run the following command:
+        ```bash
+        sudo apt-get install percona-postgresql-17-pg-tde
+        ```
 
-```bash
-sudo apt-get install percona-postgresql-16-pg-tde
-```
 
 ## Next step 
 

documentation/docs/index.md

@@ -26,7 +26,9 @@
 
 ## 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
 
@@ -34,6 +36,8 @@ 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/test.md

@@ -2,34 +2,66 @@
 
 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`:
+            You can enable data encryption by default by setting the `default_table_access_method` to     `tde_heap_basic`:
+
+            ```sql
+            SET default_table_access_method = tde_heap_basic;
+            ```
+    
+    2. Run the following function:
 
         ```sql
-        SET default_table_access_method = tde_heap_basic;
+        SELECT pg_tde_is_encrypted('table_name');
         ```
 
-2. Run the following function:
+        The function returns `t` if the table is encrypted and `f` - if not.
 
-    ```sql
-    SELECT pg_tde_is_encrypted('table_name');
-    ```
+    3. Rotate the principal key when needed:
 
-    The function returns `t` if the table is encrypted and `f` - if not.
+        ```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
+        ```
+
+=== "pg_tde Tech preview"
+
+    !!! warning
 
-3. Rotate the principal key when needed:
+        This is the tech preview functionality. It is under active development and can change anytime. Use it only for testing purposes
 
-    ```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
-    ```
+    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
+        ```

documentation/docs/yum.md

@@ -1,6 +1,10 @@
 # Install `pg_tde` on Red Hat Enterprise Linux and derivatives
 
-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).
 
@@ -8,22 +12,11 @@ This tutorial shows how to install `pg_tde` with [Percona Distribution for Postg
 
 ### Enable / disable modules
 
-=== "CentOS 7"
-
-    Install the `epel-release` package:
-
-    ```bash
-    sudo yum -y install epel-release
-    sudo yum repolist
-    ```
-
-=== "RHEL8/Oracle Linux 8/Rocky Linux 8"
+For RHEL8/Oracle Linux 8/Rocky Linux 8, disable the ``postgresql``  and ``llvm-toolset``modules:    
 
-    Disable the ``postgresql``  and ``llvm-toolset``modules:    
-
-    ```bash
-    sudo dnf module disable postgresql llvm-toolset
-    ```
+```bash
+sudo dnf module disable postgresql llvm-toolset
+```
 
 ### Install `percona-release`
 
@@ -37,25 +30,50 @@ You need the `percona-release` repository management tool that enables the desir
 
 2. Enable the repository
 
-    ```bash
-    sudo percona-release enable-only ppg-16.2 testing
-    ```
+    Enable the Percona Distribution for PostgreSQL repository
 
-## Install Percona Distribution for PostgreSQL
+    === "pg_tde Beta"
 
-To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion16}} testing
+        ```
     
-```bash
-sudo yum -y install percona-postgresql-client-common percona-postgresql-common percona-postgresql-server-dev-all percona-postgresql16 percona-postgresql16-contrib percona-postgresql16-devel percona-postgresql16-libs
-```
+    === "pg_tde Tech preview"
+
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion17}} experimental
+        ```
 
 ## Install `pg_tde`
 
-To install `pg_tde` packages, run the following command:
+=== "pg_tde Beta"
+   
+    1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+
+        ```bash
+        sudo yum -y install percona-postgresql-client-common percona-postgresql-common         percona-postgresql-server-dev-all percona-postgresql16 percona-postgresql16-contrib         percona-postgresql16-devel percona-postgresql16-libs
+        ```
+    
+    2. Install `pg_tde` packages
+        
+        ```bash
+        sudo yum install percona-pg_tde_16
+        ```
+    
+=== "pg_tde Tech preview"
+   
+    1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+
+        ```bash
+        sudo yum -y install percona-postgresql-client-common percona-postgresql-common         percona-postgresql-server-dev-all percona-postgresql17 percona-postgresql17-contrib         percona-postgresql17-devel percona-postgresql17-libs
+        ```
+    
+    2. Install `pg_tde` packages
+        
+        ```bash
+        sudo yum install percona-pg_tde_17
+        ```
 
-```bash
-sudo yum install percona-pg_tde_16
-```
 
 ## Next steps
 

documentation/mkdocs.yml

@@ -165,10 +165,10 @@ nav:
   - functions.md
   - How to:
     - Use reference to external parameters: external-parameters.md
+    - Decrypt encrypted table: decrypt.md
   - Release notes:
     - "pg_tde release notes": release-notes/release-notes.md
   - uninstall.md
   - contribute.md
 
-# - Version Selector: "../"
 

documentation/variables.yml

@@ -1,3 +1,5 @@
 #Variables used throughout the docs
 
 release: 'Beta'
+pgversion16: '16.4'
+pgversion17: '17.0'