postgres/documentation/docs/setup.md

Setup

Load the pg_tde at the start time. The extension requires additional shared memory; therefore, add the pg_tde value for the shared_preload_libraries parameter and restart the postgresql instance.

1. Use the ALTER SYSTEM command from psql terminal to modify the shared_preload_libraries parameter.

   ALTER SYSTEM SET shared_preload_libraries = 'pg_tde';
   

2. Start or restart the postgresql instance to apply the changes.

   • On Debian and Ubuntu:

     sudo systemctl restart postgresql.service
     

   • On RHEL and derivatives

     sudo systemctl restart postgresql-16
     

3. Create the extension using the CREATE EXTENSION command. You must have the privileges of a superuser or a database owner to use this command. Connect to psql as a superuser for a database and run the following command:

   CREATE EXTENSION pg_tde;
   

   By default, the pg_tde extension is created for the currently used database. To encrypt the data in other databases, you must explicitly run the CREATE EXTENSION command against them.

   !!! tip

    You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows: 
   
    ```
    psql -d template1 -c 'CREATE EXTENSION pg_tde;'
    ```
   

4. Set the location of the keyring configuration file in postgresql.conf: pg_tde.keyringConfigFile = '/where/to/put/the/keyring.json'

5. Create the keyring configuration file

6. Start or restart the postgresql instance to apply the changes.

   • On Debian and Ubuntu:

     sudo systemctl restart postgresql.service
     

   • On RHEL and derivatives

     sudo systemctl restart postgresql-16
     

Keyring configuration

Create the keyring configuration file with the following contents:

=== "HashiCorp Vault"

 ```json
 {
         'provider': 'vault-v2',
         'token': 'ROOT_TOKEN',
         'url': 'http://127.0.0.1:8200',
         'mountPath': 'secret'
         'caPath': '<path/to/caFile>'
 }
 ```

 where:

 * `provider` is set to `vault-v2` since only the version 2 of the KV secrets engine is supported
 * `url` is the URL of the Vault server
 * `mountPath` is the mount point where the keyring should store the keys
 * `token` is an access token with read and write access to the above mount point
 * [optional] `caPath` is the path of the CA file used for SSL verification

=== "Local keyfile"

 ```json
 {
         'provider': 'file',
         'datafile': '/tmp/pgkeyring',
 }
 ```     

 This keyring configuration has the file provider, with a single datafile parameter.     

 This datafile is created and managed by PostgreSQL, the only requirement is that `postgres` should be able to write to the specified path.     

 This setup is intended for development, and stores the keys unencrypted in the specified data file.