Skip to content

Installation

Jump to bottom
mdurighettomiriade edited this page Aug 6, 2026 · 2 revisions

Installation

pg_vault_tde supports PostgreSQL 17 and 18 (19 is planned). It ships as pre-built DEB/RPM packages, or can be built from source.

Prerequisites

pg_vault_tde is a shared_preload_libraries extension: it must be loaded at server start, and it links against OpenSSL 3.x and libcurl.

Requirement Notes
PostgreSQL 17.x or 18.x, with server development headers
OpenSSL 3.x (AES-256-GCM / AES-256-SIV via the EVP / provider API)
libcurl Required for the HashiCorp Vault / OpenBao provider
CPU Any x86-64 or AArch64 — AES hardware acceleration (AES-NI/VAES/ARM CE/SVE2) is automatic via OpenSSL on every build; see Performance and Tuning

Option A — Install From Package (Recommended)

Pre-built DEB and RPM packages are produced for both PostgreSQL 17 and 18. There is a single package per (format, PG major) — hardware-accelerated AES is automatic via OpenSSL on it, no CPU-specific variant is needed (see Performance and Tuning). See Compatibility and Versioning for the full package/version matrix.

Debian / Ubuntu

dpkg -i postgresql-18-pg-vault-tde_<version>_amd64.deb
dpkg -l | grep pg-vault-tde   # verify

RHEL / Rocky / AlmaLinux

dnf install postgresql18-pg_vault_tde-<version>.rpm
rpm -qi postgresql18-pg_vault_tde   # verify

Wallet base directory. If you plan to use the local wallet KMS provider, the package installer automatically creates /var/lib/pg_vault_tde/, owned by the postgres OS user with mode 0700. Source builds (Option B) must create this directory manually — see the note at the end of this page.

Option B — Build From Source

git clone https://github.com/miriade/pg_vault_tde.git
cd pg_vault_tde

Debian / Ubuntu, PostgreSQL 18:

apt-get install -y postgresql-server-dev-18 libssl-dev libcurl4-openssl-dev pkg-config
make && sudo make install

Debian / Ubuntu, PostgreSQL 17:

apt-get install -y postgresql-server-dev-17 libssl-dev libcurl4-openssl-dev pkg-config
make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config && sudo make install

RHEL / Rocky, PostgreSQL 18:

dnf install -y postgresql18-devel openssl-devel libcurl-devel
make PG_CONFIG=/usr/pgsql-18/bin/pg_config && make install

RHEL / Rocky, PostgreSQL 17:

dnf install -y postgresql17-devel openssl-devel libcurl-devel
make PG_CONFIG=/usr/pgsql-17/bin/pg_config && make install

Hardware-accelerated crypto (AES-NI, VAES, ARM CE, SVE2) is automatic via OpenSSL on this same build — see Performance and Tuning.

Wallet base directory (source builds only). Package installers create /var/lib/pg_vault_tde/ automatically; a source build does not. If you intend to use the local wallet provider, create it once as root before calling pg_vault_tde_wallet_init():

mkdir -p /var/lib/pg_vault_tde
chown postgres:postgres /var/lib/pg_vault_tde
chmod 0700 /var/lib/pg_vault_tde

This directory must not live inside PGDATA — see Security Considerations.

Option C — Install via PGXN

pg_vault_tde is distributed on the PostgreSQL Extension Network (PGXN). This is essentially a source build (Option B) driven for you by the PGXN client, so the same OS packages (postgresql-server-dev-<ver>, libssl-dev, libcurl4-openssl-dev, pkg-config / their RHEL equivalents) must already be installed.

# Install the client once, if you don't already have it
pip install pgxnclient    # or: apt-get install pgxnclient / dnf install pgxnclient

pgxn install pg_vault_tde
pgxn load    pg_vault_tde -d yourdatabase   # runs CREATE EXTENSION

pgxn install downloads the latest release from PGXN, then runs make USE_PGXS=1 && make USE_PGXS=1 install against whichever pg_config is first on PATH — pass --pg_config /path/to/pg_config explicitly if you need to target a specific PostgreSQL 17/18 install. pgxn load only runs CREATE EXTENSION; you still need to add pg_vault_tde to shared_preload_libraries and restart PostgreSQL yourself (below) before CREATE EXTENSION will succeed — pgxn load does not edit postgresql.conf.

Load and Enable the Extension

  1. Add to postgresql.conf:

    shared_preload_libraries = 'pg_vault_tde'

  2. Restart PostgreSQL — this GUC is PGC_POSTMASTER and cannot be reloaded with pg_reload_conf().

  3. Create the extension in each database that needs it:

    CREATE EXTENSION pg_vault_tde;

  4. Verify:

    SELECT * FROM pg_vault_tde_health_check();

At this point the extension is loaded but has no key backend configured yet — go to Key Management Overview to choose and configure one before creating any encrypted table.

See Also

Clone this wiki locally