Suggestion for documentation DO NOT MERGE

AndersAstrand · AndersAstrand · commit 9b23b519f638 · 2025-05-14T16:06:53.000+02:00
I think it's much easier to read if we use named parameters in our
example sql code, especially with functions that have many parameters.
diff --git a/contrib/pg_tde/documentation/docs/wal-encryption.md b/contrib/pg_tde/documentation/docs/wal-encryption.md
@@ -19,50 +19,102 @@ Before turning WAL encryption on, you must follow the steps below to create your
         For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.
 
         ```sql
-        SELECT pg_tde_add_global_key_provider_kmip('provider-name','kmip-addr', 5696, '/path_to/server_certificate.pem', '/path_to/client_cert.pem', '/path_to/client_key.pem');
+        SELECT pg_tde_add_global_key_provider_kmip(
+            provider_name => <provider-name>,
+            kmip_host => <kmip-addr>,
+            kmip_port => 5696,
+            kmip_ca_path => <server-certificate>,
+            kmip_cert_path => <client-cert>,
+            kmip_key_path => <client-key>
+        );
         ```
 
         where:
 
-        * `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider.
-        * `kmip-addr` is the IP address of a domain name of the KMIP server
-        * `port` is the port to communicate with the KMIP server. Typically used port is 5696.
-        * `server-certificate` is the path to the certificate file for the KMIP server.
-        * `client-cert` is the path to the client certificate.
-        * `client-key` is the path to the client key.
+        * `<provider-name>` is the name of the provider. You can specify any name, it's for you to identify the provider.
+        * `<kmip-addr>` is the IP address of a domain name of the KMIP server
+        * `<port>` is the port to communicate with the KMIP server. Typically used port is 5696.
+        * `<server-certificate>` is the path to the certificate file for the KMIP server.
+        * `<client-cert>` is the path to the client certificate.
+        * `<client-key>` is the path to the client key.
 
         <i warning>:material-information: Warning:</i> This example is for testing purposes only:
 
         ```
-        SELECT pg_tde_add_key_using_global_key_provider_kmip('kmip','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_cert_jane_doe.pem', '/tmp/client_key_jane_doe.pem');
+        SELECT pg_tde_add_key_using_global_key_provider_kmip(
+            provider_name => 'kmip',
+            kmip_host => '127.0.0.1',
+            kmip_port => 5696,
+            kmip_ca_path => '/opt/server_certificate.pem',
+            kmip_cert_path => '/opt/client_cert_jane_doe.pem',
+            kmip_key_path => '/opt/client_key_jane_doe.pem'
+        );
         ```
 
     === "With HashiCorp Vault"
 
         ```sql
-        SELECT pg_tde_add_global_key_provider_vault_v2('provider-name', 'secret_token', 'url', 'mount', 'ca_path');
+        SELECT pg_tde_add_global_key_provider_vault_v2(
+            provider_name => <provider-name>,
+            vault_token => <secret_token>,
+            vault_url => <url>,
+            vault_mount_path => <mount>,
+            vault_ca_path => <ca-path>
+        );
         ```
 
         where:
 
-        * `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
+        * `<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
+
+        <i warning>:material-information: Warning:</i> This example is for testing purposes only:
+
+        ```
+        SELECT pg_tde_add_key_using_global_key_provider_vault_v2(
+            provider_name => 'vault_v2',
+            vault_token => 'secret_token',
+            vault_url => 'http://127.0.0.1',
+            vault_mount_path => 'secrets',
+            vault_ca_path => '/opt/server_certificate.pem'
+        );
+        ```
 
     === "With keyring file"
 
         This setup is **not recommended**, as it is intended for development. The keys are stored **unencrypted** in the specified data file.
 
         ```sql
-        SELECT pg_tde_add_global_key_provider_file('provider-name','/path/to/the/keyring/data.file');
+        SELECT pg_tde_add_global_key_provider_file(
+            provier_name => <provider-name>,
+            file_path => <path>
+        );
+        ```
+
+        where:
+
+        * `<provider-name>` is the name you define for the key provider
+        * `<path>` is the key data file
+
+        <i warning>:material-information: Warning:</i> This example is for testing purposes only:
+
+        ```sql
+        SELECT pg_tde_add_global_key_provider_file(
+            provier_name => 'provider-name',
+            file_path => '/path/to/the/keyring/data.file'
+        );
         ```
 
 3. Create principal key
 
     ```sql
-        SELECT pg_tde_set_server_key_using_global_key_provider('key', 'provider-name');
+    SELECT pg_tde_set_server_key_using_global_key_provider(
+        key_name => 'key',
+        provider_name => 'provider-name'
+    );
     ```
 
 4. Enable WAL level encryption using the `ALTER SYSTEM` command. You need the privileges of the superuser to run this command:
