Skip to content

PG-1804 - Remove outdated and duplicate Enable encryption topic from docker.md PSP 17 #830

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.

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
Aug 14, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
85 changes: 18 additions & 67 deletions docs/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,9 +98,10 @@ Where:

## Enable encryption

Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. You must explicitly enable it when you start the container. For more information, see the [pg_tde documentation](https://docs.percona.com/pg-tde/index.html).
Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. You must explicitly enable it when you start the container. For more information, see the [pg_tde documentation :octicons-link-external-16:](https://docs.percona.com/pg-tde/index.html).

Follow these steps to enable `pg_tde`:
{.power-number}

1. Start the container with the `ENABLE_PG_TDE=1` environment variable:

Expand All @@ -123,7 +124,7 @@ Follow these steps to enable `pg_tde`:
??? example "Sample output"

```{.text .no-copy}
psql ({{dockertag}} - Percona Server for PostgreSQL {{dockertag}}.1)
psql ({{pgsubversion}} - Percona Server for PostgreSQL {{dockertag}})
Type "help" for help.

postgres=#
Expand All @@ -135,7 +136,7 @@ Follow these steps to enable `pg_tde`:
CREATE EXTENSION pg_tde;
```

4. Configure a key provider with a keyring file. This setup is intended for development and stores the keys unencrypted in the specified data file. The below sample configuration is intended for testing and development purposes.
4. Add the key provider by using a keyring file. This setup is intended for development and stores the keys unencrypted in the specified data file. The below sample configuration is intended for testing and development purposes only.

!!! note
For production use, we **strongly recommend** setting up an external key management store and configure an external key provider. Refer to the [Setup :octicons-link-external-16:](https://docs.percona.com/pg-tde/setup.html#key-provider-configuration) topic in the `pg_tde` documentation.
Expand All @@ -146,85 +147,35 @@ Follow these steps to enable `pg_tde`:
SELECT pg_tde_add_database_key_provider_file('file-vault', '/tmp/pg_tde_test_001_basic.per');
```

5. Create the key:

```sql
SELECT pg_tde_create_key_using_database_key_provider('test-db-key', 'file-vault');
```

5. Set the principal key:

```sql
SELECT pg_tde_set_key_using_database_key_provider('test-db-key', 'file-vault');
```

The key is auto-generated. You are ready to use data encryption.

6. Create a table with encryption enabled. Pass the `USING tde_heap` clause to the `CREATE TABLE` command:

```sql
CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap;
```

## Enable encryption

Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. You must explicitly enable it when you start the container.

Here's how to do this:
{.power-number}

1. Start the container with the `ENABLE_PG_TDE=1` environment variable:

```{.bash data-prompt="$"}
$ docker run --name container-name -e ENABLE_PG_TDE=1 -e POSTGRES_PASSWORD=sUpers3cRet -d percona/percona-distribution-postgresql:{{dockertag}}-multi
```

where:

* `container-name` is the name you assign to your container
* `ENABLE_PG_TDE=1` adds the `pg_tde` to the `shared_preload_libraries` and enables the custom storage manager
* `POSTGRES_PASSWORD` is the superuser password


2. Connect to the container and start the interactive `psql` session:

```{.bash data-prompt="$"}
$ docker exec -it container-name psql
```

??? example "Sample output"

```{.text .no-copy}
psql ({{dockertag}} - Percona Server for PostgreSQL {{dockertag}}.1)
Type "help" for help.
??? example "CREATE TABLE example"

postgres=#
```{.sql .no-copy}
CREATE TABLE test_users (
user_id INT,
username VARCHAR(50),
email VARCHAR(100),
signup_date DATE
) USING tde_heap;
```

3. Create the extension in the database where you want to encrypt data. This requires superuser privileges.

```sql
CREATE EXTENSION pg_tde;
```

4. Configure a key provider. In this sample configuration intended for testing and development purpose, we use a local keyring provider.

For production use, set up an external key management store and configure an external key provider. Refer to the [Setup :octicons-link-external-16:](https://percona.github.io/pg_tde/main/setup.html#key-provider-configuration) chapter in the `pg_tde` documentation.

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```sql
SELECT pg_tde_add_key_provider_file('file-keyring','/tmp/pg_tde_test_local_keyring.per');
```

5. Add a principal key

```sql
SELECT pg_tde_set_principal_key('test-db-master-key','file-keyring');
```

The key is autogenerated. You are ready to use data encryption.

6. Create a table with encryption enabled. Pass the `USING tde_heap` clause to the `CREATE TABLE` command:

```sql
CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap;
```

## Enable `pg_stat_monitor`

To enable the `pg_stat_monitor` extension after launching the container, do the following:
Expand Down
1 change: 1 addition & 0 deletions variables.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

release: 'release-notes-v17.5'
dockertag: '17.5-2'
pgsubversion: '17.5'
pgversion: '17'
pspgversion: '17.5.2'
pgsmversion: '2.1.1'
Expand Down