Skip to content
Percona Software for PostgreSQL Documentation

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Installation

Considerations

You can use the following options to manage encryption keys:

  • Use the Key Management Store (KMS). This is the recommended approach. pg_tde supports the following KMS:

    • HashiCorp Vault as the key/value secrets engine version 2 with secret versioning
    • HashiCorp Vault as the KMIP server. The KMIP server is part of Vault Enterprise and requires a license
    • OpenBao as the open-source alternative to HashiCorp Vault KMIP
    • A KMIP-compatible server. For testing and development purposes you can use PyKMIP.

    The KMS configuration is out of scope of this document. We assume that you have the KMS up and running. For the pg_tde configuration, you need the following information:

    • The secret access token to the Vault server
    • The URL to access the Vault server
    • (Optional) The CA file used for SSL verification
    • The hostname or IP address of the KMIP server.
    • The valid certificates issued by the key management appliance.

  • Use the local keyfile. Use the keyfile only development and testing purposes since the keys are stored unencrypted.

Procedure

Install pg_tde using one of available installation methods:

The packages are available for the following operating systems:

  • 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)
  • Ubuntu 24.04 (Noble Numbat)
  • Debian 11 (Bullseye)
  • Debian 12 (Bookworm)

Install on Debian or Ubuntu Install on RHEL or derivatives

To build pg_tde from source code, do the following:

  1. On Ubuntu/Debian: Install the following dependencies required for the build:

    sudo apt install make gcc postgresql-server-dev-17 libcurl4-openssl-dev

  2. Install Percona Distribution for PostgreSQL 17 or upstream PostgreSQL 17

  3. If PostgreSQL is installed in a non standard directory, set the PG_CONFIG environment variable to point to the pg_config executable.

  4. Clone the repository: 

    git clone git://github.com/percona/pg_tde

  5. Compile and install the extension

    cd pg_tde
make USE_PGXS=1
sudo make USE_PGXS=1 install

Note

The steps below are for the PostgreSQL Community version of pg_tde. It provides the tde_heap_basic access method for data encryption.

To run the pg_tde version for Percona Server for PostgreSQL, use the Percona Distribution for PostgreSQL Docker image .

You can find Docker images on Docker Hub. Images are built on top of postgres:16 official image.

To run pg_tde in Docker, use the following command: 

docker run --name pg-tde -e POSTGRES_PASSWORD=mysecretpassword -d perconalab/pg_tde

It builds and adds the pg_tde extension to PostgreSQL 16. The postgresql.conf contains the required modifications. The pg_tde extension is added to template1 so that all new databases automatically have the pg_tde extension loaded.

Keys are not created automatically. You must configure a key provider and a principal key for each database where you wish to use encrypted tables.

Connect to the container and establish the psql session there. Then, see the instructions in the Setup section, starting with the 4th point, as the first 3 steps are already completed in the Docker image.

See Docker Docs on usage.

You can also build a Docker image manually with: 

docker build . -f ./docker/Dockerfile -t your-image-name

Next steps

Setup