Thanks to visit codestin.com
Credit goes to github.com

Skip to content

README updates #389

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 6, 2025
Merged

README updates #389

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8830692
Update README.md
Andriciuc Jun 4, 2025
f9c0ec5
Update README.md
Andriciuc Jun 5, 2025
ede4156
Update README.md
Andriciuc Jun 5, 2025
bb1af7a
Merge branch 'TDE_REL_17_STABLE' into docs-readme-update
Andriciuc Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 33 additions & 135 deletions contrib/pg_tde/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,168 +1,66 @@
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/percona/pg_tde/badge)](https://scorecard.dev/viewer/?uri=github.com/percona/pg_tde)
[![codecov](https://codecov.io/github/percona/postgres/graph/badge.svg?token=Wow78BMYdP)](https://codecov.io/github/percona/postgres)
[![Forum](https://img.shields.io/badge/Forum-join-brightgreen)](https://forums.percona.com/)
[![Docs](https://img.shields.io/badge/docs-pg_tde-blue)](https://docs.percona.com/pg-tde/)

# pg_tde: Transparent Database Encryption for PostgreSQL

The PostgreSQL extension provides data at rest encryption. It is currently in an experimental phase and is under active development. [We need your feedback!](https://github.com/percona/pg_tde/discussions/151)
The PostgreSQL extension provides data at rest encryption. It is currently in an experimental phase and is under active development. [We need your feedback!](https://github.com/percona/postgres/discussions)

## Table of Contents

## Table of contents
1. [Overview](#overview)
2. [Documentation](#documentation)
1. [Percona Server for PostgreSQL](#percona-server-for-postgresql)
3. [Build from sources](#building-from-sources-for-community-postgresql)
3. [Percona Server for PostgreSQL](#percona-server-for-postgresql)
4. [Run in docker](#run-in-docker)
5. [Setting up](#setting-up)
6. [Helper functions](#helper-functions)
5. [Set up pg_tde](#set-up-pg_tde)
6. [Downloads](#downloads)
7. [Additional functions](#additional-functions)

## Overview
Transparent Data Encryption offers encryption at the file level and solves the problem of protecting data at rest. The encryption is transparent for users allowing them to access and manipulate the data and not to worry about the encryption process. As a key provider, the extension supports the keyringfile and [Hashicorp Vault](https://www.vaultproject.io/).

### This extension provides one `access method`:
Transparent Data Encryption offers encryption at the file level and solves the problem of protecting data at rest. The encryption is transparent for users allowing them to access and manipulate the data and not to worry about the encryption process. The extension supports [keyringfile and external Key Management Systems (KMS) through a Global Key Provider interface](../pg_tde/documentation/docs/global-key-provider-configuration/index.md).

### This extension provides the `tde_heap access method`

This access method:

#### `tde_heap` access method
- Works only with [Percona Server for PostgreSQL 17](https://docs.percona.com/postgresql/17/postgresql-server.html)
- Uses extended Storage Manager and WAL APIs
- Encrypts tuples, WAL and indexes
- **Doesn't** encrypt temporary files and statistics **yet**
- It **does not** encrypt temporary files and statistics **yet**

## Documentation

Full and comprehensive documentation about `pg_tde` is available at https://docs.percona.com/pg-tde/index.html.
For more information about `pg_tde`, [see the official documentation](https://docs.percona.com/pg-tde/index.html).

## Percona Server for PostgreSQL

Percona provides binary packages of `pg_tde` extension only for Percona Server for PostgreSQL. Learn how to install them or build `pg_tde` from sources for PSPG in the [documentation](https://docs.percona.com/pg-tde/install.html).

## Building from sources for community PostgreSQL
1. Install required dependencies (replace XX with 16 or 17)
- On Debian and Ubuntu:
```sh
sudo apt install make gcc autoconf git libcurl4-openssl-dev postgresql-server-dev-XX
```

- On RHEL 8 compatible OS:
```sh
sudo yum install epel-release
yum --enablerepo=powertools install git make gcc autoconf libcurl-devel perl-IPC-Run redhat-rpm-config openssl-devel postgresqlXX-devel
```

- On MacOS:
```sh
brew install make autoconf curl gettext postresql@XX
```

2. Install or build postgresql 16 or 17
3. If postgres is installed in a non standard directory, set the `PG_CONFIG` environment variable to point to the `pg_config` executable

4. Clone the repository, build and install it with the following commands:

```sh
git clone https://github.com/percona/pg_tde
```

5. Compile and install the extension

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

## Run in Docker

There is a [docker image](https://hub.docker.com/r/perconalab/pg_tde) with `pg_tde` based community [PostgreSQL 16](https://hub.docker.com/_/postgres)

```
docker run --name pg-tde -e POSTGRES_PASSWORD=mysecretpassword -d perconalab/pg_tde
```
Docker file is available [here](https://github.com/percona/pg_tde/blob/main/docker/Dockerfile)


_See [Make Builds for Developers](https://github.com/percona/pg_tde/wiki/Make-builds-for-developers) for more info on the build infrastructure._

## Setting up

1. Add extension to the `shared_preload_libraries`:
1. Via configuration file `postgresql.conf `
```
shared_preload_libraries=pg_tde
```
2. Via SQL using [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html) command
```sql
ALTER SYSTEM SET shared_preload_libraries = 'pg_tde';
```
2. Start or restart the `postgresql` cluster to apply the changes.
* On Debian and Ubuntu:

```sh
sudo systemctl restart postgresql-17
```

* On RHEL 8 compatible OS (replace XX with your version):
```sh
sudo systemctl restart postgresql-XX.service
```
3. [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) with SQL (requires superuser or a database owner privileges):

```sql
CREATE EXTENSION pg_tde;
```
4. Create a key provider. Currently `pg_tde` supports `File` and `Vault-V2` key providers. You can add the required key provider using one of the functions.


```sql
-- For Vault-V2 key provider
-- pg_tde_add_database_key_provider_vault_v2(provider_name, vault_token, vault_url, vault_mount_path, vault_ca_path)
SELECT pg_tde_add_database_key_provider_vault_v2(
'vault-provider',
'/path/to/token_file',
'https://your.vault.server',
'secret', NULL);

-- For File key provider
-- pg_tde_add_database_key_provider_file(provider_name, file_path);
SELECT pg_tde_add_database_key_provider_file('file','/tmp/pgkeyring');
```

**Note: The `File` provided is intended for development and stores the keys unencrypted in the specified data file.**

5. Set the principal key for the database using the `pg_tde_set_key` function.

```sql
-- pg_tde_set_key_using_database_key_provider(key_name, provider_name);
SELECT pg_tde_set_key_using_database_key_provider('my-key','file');
```

6. Specify `tde_heap` access method during table creation
```sql
CREATE TABLE albums (
album_id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
artist_id INTEGER,
title TEXT NOT NULL,
released DATE NOT NULL
) USING tde_heap;
```
7. You can encrypt existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
```sql
ALTER TABLE table_name SET ACCESS METHOD tde_heap;
```


## Latest test release

To download the latest build of the main branch, use the `HEAD` release from [releases](https://github.com/percona/pg_tde/releases).
To run `pg_tde` in Docker, follow the instructions in the [official pg_tde Docker documentation](https://docs.percona.com/postgresql/17/docker.html#enable-encryption).

Builds are available in a tar.gz format, containing only the required files, and as a deb package.
The deb package is built against the pgdg16 release, but this dependency is not yet enforced in the package.
_For details on the build process and developer setup, see [Make Builds for Developers](https://github.com/percona/pg_tde/wiki/Make-builds-for-developers)._

## Set up pg_tde

## Helper functions
For more information on setting up and configuring `pg_tde`, see the [official pg_tde setup topic](https://docs.percona.com/pg-tde/setup.html).

The extension provides the following helper functions:
The guide also includes instructions for:

- Installing and enabling the extension
- Setting up key providers
- Creating encrypted tables

## Downloads

To download the latest build of the main branch, use the `HEAD` release from [releases](https://github.com/percona/postgres/releases).

Builds are available in a tar.gz format, containing only the required files, and as a deb package.
The deb package is built against the pgdg17 release, but this dependency is not yet enforced in the package.

### pg_tde_is_encrypted(tablename)
## Additional functions

Returns `t` if the relation is encrypted, if unencrypted `f` or `NULL` if the
relation lacks storage, i.e. views, foreign tables, and partitioning tables and
indexes.
Learn more about the helper functions available in `pg_tde`, including how to check table encryption status, in the [Functions topic](https://docs.percona.com/pg-tde/functions.html?h=pg_tde_is_encrypted#encryption-status-check).