updated toc

also, improved CLI flow, split into 3 subchapters
percona · Andriciuc · May 8, 2025 · Apr 17, 2025 · Apr 17, 2025 · Apr 22, 2025
commit 9b8d6c2c95f28dd1e685d10e6d32721ac213ae37
@@ -0,0 +1,7 @@
+# Additional CLI Commands and Tools
+
+The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. These include:
+
+* [pg_tde_change_key_provider](../command-line-tools/pg-tde-change-key-provider.md): change encryption key provider for a database
+* [pg_waldump](../command-line-tools/pg-waldump.md): inspect and decrypt WAL files
+* [pg_checksums](../command-line-tools/pg-checksums.md): verify data checksums (non-encrypted files only)
@@ -0,0 +1,37 @@
+# pg_tde_change_key_provider
+
+A tool for modifying the configuration of a key provider, possibly also changing its type.
+
+This tool edits the configuration files directly, ignoring permissions or running `postgres` processes.
+
+Its only intended use is to fix servers that can't start up because of inaccessible key providers.
+
+For example, you restore from an old backup and the address of the key provider changed in the meantime. You can use this tool to correct the configuration, allowing the server to start up.
+
+!!! warning
+      Use this tool **only when the server is offline.** To modify the key provider configuration when the server is up and running, use the [`pg_tde_change_(global/database)_key_provider_<type>`](../functions.md#change-an-existing-provider) SQL functions.
+
+## Example usage
+
+To modify the key provider configuration, specify all parameters depending on the provider type in the same way as you do when using the [`pg_tde_change_(global/database)_key_provider_<type>`](../functions.md#change-an-existing-provider) SQL functions.
+
+The general syntax is as follows:
+
+```bash
+pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> <new_provider_type> <provider_parameters...>
+```
+
+## Parameter description
+
+* [optional] `<datadir>` is the data directory.`pg_tde` uses the `$PGDATA` environment variable if this is not specified
+* `<provider_name>` is the name you assigned to the key provider
+* `<new_provider_type>` can be a `file`, `vault` or `kmip`
+* `<dbOid>`
+
+Depending on the provider type, the additional parameters are:
+
+```bash
+pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> file <filename>
+pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> vault <token> <url> <mount_path> [<ca_path>]
+pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> kmip <host> <port> <cert_path> <key_path> [<ca_path>] 
+```
@@ -0,0 +1,5 @@
+# pg_checksums
+
+[`pg_checksums` :octicons-link-external-16:](https://www.postgresql.org/docs/current/app-pgchecksums.html) is a PostgreSQL command-line utility used to enable, disable, or verify data checksums on a PostgreSQL data directory. However, it cannot calculate checksums for encrypted files.
+
+Encrypted files are skipped, and this is reported in the output.
@@ -0,0 +1,14 @@
+# pg_waldump
+
+[`pg_waldump` :octicons-link-external-16:](https://www.postgresql.org/docs/current/pgwaldump.html) is a tool to display a human-readable rendering of the Write-Ahead Log (WAL) of a PostgreSQL database cluster.
+
+To read encrypted WAL records, `pg_waldump` supports the following additional arguments:
+
+* `keyring_path`: the directory where keyring configuration files for WAL are stored. These files include:
+
+   * `pg_tde.map`
+   * `pg_tde.dat`
+   * `pg_tde_keyrings`
+
+!!! note
+   `pg_waldump` will not decrypt WAL unless the `keyring_path` is set.
@@ -53,7 +53,7 @@ Thus, to protect your sensitive data, consider using TDE to encrypt it at the ta
 
 ## Is TDE enough to ensure data security?
 
-No. TDE is an additional layer to ensure data security. It protects data at rest. Consider introducing also these measures:
+**No.** Transparent Data Encryption (TDE) adds an extra layer of security for data at rest. You should also consider implementing the following additional security features:
 
 * Access control and authentication
 * Strong network security like TLS
@@ -122,7 +122,7 @@ No, it's not yet supported. In our implementation we reply on OpenSSL libraries
 
 Yes, you can encrypt an existing table. Run the `ALTER TABLE` command as follows:
 
-```
+```sql
 ALTER TABLE table_name SET ACCESS METHOD tde_heap;
 ```
 

@@ -1,23 +1,33 @@
-# Set the Global Principal Key
+# Global Principal Key Configuration
 
 Add a default principal key:
 
-    ```sql
-    SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
-    ```
+```sql
+    SELECT pg_tde_set_default_key_using_global_key_provider(
+        'name-of-the-key',
+        'provider-name',
+        'ensure_new_key'
+    );
+```
 
 ## Parameter description
 
-    * `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
-    * `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
-    * `ensure_new_key` defines if a principal key must be unique. The default value `true` means that you must speficy a unique key during key rotation. The `false` value allows reusing an existing principal key.
+* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
+* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
+* `ensure_new_key` defines if a principal key must be unique. The default value `true` means that you must speficy a unique key during key rotation. The `false` value allows reusing an existing principal key.
 
-    <i warning>:material-information: Warning:</i> This example is for testing purposes only. Replace the key name and provider name with your values:
+<i warning>:material-information: Warning:</i> This example is for testing purposes only. Replace the key name and provider name with your values:
 
-    ```sql
-    SELECT pg_tde_set_key_using_global_key_provider('test-db-master-key','file-vault','ensure_new_key');
-    ```
+```sql
+    SELECT pg_tde_set_key_using_global_key_provider(
+        'test-db-master-key',
+        'file-vault',
+        'ensure_new_key'
+    );
+```
 
-    The key is auto-generated.
+The key is auto-generated.
 
-    After this, all databases that do not have something else configured will use this newly generated principal key.
+After this, all databases that do not have something else configured will use this newly generated principal key.
+
+[Validate Encryption with pg_tde :material-arrow-right:](../test.md){.md-button}
@@ -5,19 +5,19 @@
 If you encrypted a table with the `tde_heap` access method and need to remove the encryption from it, run the following command against the desired table (`mytable` in the example below):
 
 ```sql
-ALTER TABLE mytable SET ACCESS METHOD heap;
+    ALTER TABLE mytable SET ACCESS METHOD heap;
 ```
 
 Note that the `SET ACCESS METHOD` command drops hint bits and this may affect performance. Running a plain `SELECT count(*)` or `VACUUM` command on the entire table will check every tuple for visibility and set its hint bits. Therefore, after executing the `ALTER TABLE` command, run a simple `count(*)` on your tables:
 
 ```sql
-SELECT count(*) FROM mytable;
+    SELECT count(*) FROM mytable;
 ```
 
 Check that the table is not encrypted:
 
 ```sql
-SELECT pg_tde_is_encrypted('mytable');
+    SELECT pg_tde_is_encrypted('mytable');
 ```
 
 The output returns `f` meaning that the table is no longer encrypted.
@@ -27,14 +27,14 @@ The output returns `f` meaning that the table is no longer encrypted.
 Alternatively, you can create a new not encrypted 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;
+    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;
+    DROP TABLE EncryptedCustomers;
 ```