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).
 
@@ -35,8 +39,16 @@ You need the `percona-release` repository management tool that enables the desir
 
 4. Enable the Percona Distribution for PostgreSQL repository
 
+    === "pg_tde Beta"
+
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion16}} testing
+        ```
+    
+    === "pg_tde Tech preview"
+
         ```bash
-    sudo percona-release enable-only ppg-16.2 testing
+        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. 
     
-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
+        ```bash
-sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all
+        sudo apt-get install -y percona-postgresql-16 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-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:
+
+        ```bash
+        sudo apt-get install -y percona-postgresql-17 percona-postgresql-contrib     percona-postgresql-server-dev-all
+        ```
+
+    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/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,7 +2,9 @@
 
 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"
+
+    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:
 
         ```sql
         CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap_basic;
@@ -16,7 +18,37 @@ To check if the data is encrypted, do the following:
             SET default_table_access_method = tde_heap_basic;
             ```
     
-2. Run the following function:
+    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
+        ```
+
+=== "pg_tde Tech preview"
+
+    !!! warning
+
+        This is the tech preview functionality. It is under active development 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');
@@ -24,7 +56,7 @@ To check if the data is encrypted, do the following:
 
         The function returns `t` if the table is encrypted and `f` - if not.
 
-3. Rotate the principal key when needed:
+    3. Rotate the principal key when needed:
 
         ```sql
         SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin

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,54 +12,68 @@ This tutorial shows how to install `pg_tde` with [Percona Distribution for Postg
 
 ### Enable / disable modules
 
-=== "CentOS 7"
+For RHEL8/Oracle Linux 8/Rocky Linux 8, disable the ``postgresql``  and ``llvm-toolset``modules:    
+
+```bash
+sudo dnf module disable postgresql llvm-toolset
+```
+
+### Install `percona-release`
+
+You need the `percona-release` repository management tool that enables the desired Percona repository for you.
 
-    Install the `epel-release` package:
+1. Install `percona-release`:
 
     ```bash
-    sudo yum -y install epel-release
+    sudo yum -y install https://repo.percona.com/yum/percona-release-latest.noarch.rpm 
-    sudo yum repolist
     ```
 
-=== "RHEL8/Oracle Linux 8/Rocky Linux 8"
+2. Enable the repository
+
+    Enable the Percona Distribution for PostgreSQL repository
 
-    Disable the ``postgresql``  and ``llvm-toolset``modules:    
+    === "pg_tde Beta"
 
         ```bash
-    sudo dnf module disable postgresql llvm-toolset
+        sudo percona-release enable-only ppg-{{pgversion16}} testing
         ```
     
-### Install `percona-release`
+    === "pg_tde Tech preview"
 
-You need the `percona-release` repository management tool that enables the desired Percona repository for you.
+        ```bash
+        sudo percona-release enable-only ppg-{{pgversion17}} experimental
+        ```
 
-1. Install `percona-release`:
+## Install `pg_tde`
+
+=== "pg_tde Beta"
+   
+    1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
 
         ```bash
-    sudo yum -y install https://repo.percona.com/yum/percona-release-latest.noarch.rpm 
+        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. Enable the repository
+    2. Install `pg_tde` packages
         
         ```bash
-    sudo percona-release enable-only ppg-16.2 testing
+        sudo yum install percona-pg_tde_16
         ```
     
-## Install Percona Distribution for PostgreSQL
+=== "pg_tde Tech preview"
    
-To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+    1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
 
-```bash
+        ```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
+        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
-```
+        ```
     
-## Install `pg_tde`
+    2. Install `pg_tde` packages
         
-To install `pg_tde` packages, run the following command:
+        ```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'