Rebased on main

documentation/docs/apt.md

@@ -37,16 +37,10 @@ You need the `percona-release` repository management tool that enables the desir
 
 4. Enable the Percona Distribution for PostgreSQL repository
 
-    Percona provides [two repositories](repo-overview.md) for Percona Distribution for PostgreSQL. We recommend enabling the Major release repository to timely receive the latest updates. 
+    Percona provides [two repositories](repo-overview.md) for Percona Distribution for PostgreSQL. We recommend enabling the Major release repository to timely receive the latest updates. Since the `tde_heap` access method is still in the experimental stage, the `pg_tde` package is currently available from the experimental repository.
 
     ```{.bash data-prompt="$"}
-    $ sudo percona-release setup ppg-17
-    ```
-
-5. Enable the experimental Percona Distribution for PostgreSQL repository that contains the pg_tde package
-
-    ```bash
-    sudo percona-release enable ppg-{{pgversion17}} experimental
+    $ sudo percona-release enable ppg-{{pgversion17}} experimental
     ```
 
 6. Update the local cache
@@ -57,6 +51,7 @@ You need the `percona-release` repository management tool that enables the desir
 
 ## Install `pg_tde`
 
+After all [preconditions](#preconditions) are met, install the extension.
 
 1. Install Percona Distribution for PostgreSQL. 
 

documentation/docs/table-access-method.md

@@ -0,0 +1,90 @@
+# Table access method
+
+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 rows are identified by their unique row identifier (TID).
+
+## How does the heap access method work?
+
+**Insertion**: When a new row is inserted, PostgreSQL finds a free space in the tablespace and stores the row there.
+
+**Deletion**: When a row is deleted, PostgreSQL marks the space occupied by the row as free, but the data remains until it is overwritten by a new insertion.
+
+**Updates**: Updates are handled by deleting the old row and inserting a new row with the updated values
+
+## Custom access method
+
+You can create a custom table access method for each table and instruct PostgreSQL how to store the data for you. For example, you can tailor the table access method to better suit your specific workload or data access patterns.
+
+To define an access method, use the `CREATE ACCESS METHOD` with the `TYPE` clause set to `table`:
+
+```sql
+CREATE ACCESS METHOD access_method_name TYPE table;
+```
+
+To use your access method, specify the `USING` clause for the `CREATE TABLE` command:
+
+```sql
+CREATE TABLE table_name (
+    column1 data_type,
+    column2 data_type,
+    ...
+) USING access_method_name;
+```
+
+## `tde_heap` access method
+
+The `tde_heap` is a custom table access method that comes with the `pg_tde` extension to provide data encryption. It is automatically created **only** for the databases where you [enabled the `pg_tde` extension](setup.md) and configured the key provider.
+
+
+## Changing the default table access method
+
+You can change the default table access method so that every table in the entire database cluster is created using the custom access method. For example, you can enable data encryption by default by defining either `tde_heap_basic` or the  `tde_heap` as the default table access method. 
+
+However, consider the following before doing so:
+
+* This is a global setting and applies across the entire database cluster and not just a single database. We recommend setting it with caution only if you created the `pg_tde` extensions for all databases. Otherwise PostgreSQL throws an error.
+* You must create the `pg_tde` extension and configure the key provider for all databases before you modify the configuration. Otherwise PostgreSQL won't find the specified access method and will throw an error.
+
+Here's how you can set the new default table access method:
+
+1. Add the access method to the `default_table_access_method` parameter.        
+
+    === "via the SQL statement"
+
+        Use the `ALTER SYSTEM SET` command. This requires superuser privileges.
+
+        This example shows how to set the `tde_heap` access method. Replace it with the `tde_heap_basic` if needed. 
+
+
+        ```sql
+        ALTER SYSTEM SET default_table_access_method=tde_heap;
+        ```
+
+    === "via the configuration file"
+
+        Edit the `postgresql.conf` configuration file and add the value for the `default_table_access_method` parameter.
+        
+        This example shows how to set the `tde_heap` access method. Replace it with the `tde_heap_basic` if needed.
+
+        ```ini
+        default_table_access_method = 'tde_heap'
+        ```  
+
+    === "via the SET command"
+
+        You can use the SET command to change the default table access method temporarily, for the current session. 
+        
+        Unlike modifying the `postgresql.conf` file or using the ALTER SYSTEM SET command, the changes you make via the SET command don't persist after the session ends.
+
+        You also don't need to have the superuser privileges to run the SET command.
+
+        You can run the SET command anytime during the session. This example shows how to set the `tde_heap` access method. Replace it with the `tde_heap_basic` if needed.
+
+        ```sql
+        SET default_table_access_method = tde_heap;
+        ```
+
+2. Reload the configuration to apply the changes:
+
+    ```sql
+    SELECT pg_reload_conf();
+

documentation/docs/test.md

@@ -1,16 +1,14 @@
 # Test Transparent Data Encryption
 
-To check if the data is encrypted, do the following:
+Enabling `pg_tde` extension for a database creates the table access method `tde_heap` . This access method enables you to encrypt the data.
 
-=== "pg_tde Tech preview"
+!!! warning
 
-    !!! warning
+    This is the tech preview functionality. Its scope is not yet finalized and can change anytime. **Use it only for testing purposes.**
 
-        This is the tech preview functionality. Its scope is not yet finalized and can change anytime.** Use it only for testing purposes.**
+Here's how to do it:
 
-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`. To enable data encryption, create the table using this access method as follows:
+1. Create a table in the database for which you have [enabled `pg_tde`](setup.md) using the `tde_heap` access method as follows:
 
     ```sql
     CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap;
@@ -26,8 +24,10 @@ To check if the data is encrypted, do the following:
     released DATE NOT NULL
     ) USING tde_heap;
     ```
+
+    Learn more about table access methods and how you can enable data encryption by default in the [Table access methods](table-access-method.md) section.
 
-2. Run the following function:
+2. To check if the data is encrypted, run the following function:
 
     ```sql
     SELECT pg_tde_is_encrypted('table_name');
@@ -45,10 +45,10 @@ To check if the data is encrypted, do the following:
     SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- changeprovider
     ```
 
-4. You can encrypt existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
+4. You can encrypt an existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
 
     ```sql
-    ALTER TABLE table_name SET access method  tde_heap;
+    ALTER TABLE table_name SET access method tde_heap;
     ```
 
 !!! hint

documentation/mkdocs.yml

@@ -155,14 +155,17 @@ extra:
 
 nav:
   - Home: index.md
-  - tde.md
   - Get started:
     - "Install": "install.md"
     - "Via apt": apt.md
     - "Via yum": yum.md   
     - "Set up": "setup.md"
     - "Test TDE": "test.md"
   - functions.md
+  - Concepts:
+    - "What is TDE": tde.md
+  #  - wal-encryption.md
+    - table-access-method.md
   - How to:
     - Use reference to external parameters: external-parameters.md
     - Decrypt an encrypted table: decrypt.md