8000 README updates (#389) · percona/postgres@9686b82 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9686b82

Browse files
AndriciucAndriciuc
authored
README updates (#389)
Updated the pg_tde README based on @Robinyo feedback, removed unnecessary config steps and replaced with links to docs for up to date information, reorganized content and information for clarity and descriptions, improved SEO.
1 parent 4173798 commit 9686b82

File tree

1 file changed

+33
-135
lines changed

1 file changed

+33
-135
lines changed

‎contrib/pg_tde/README.md

Lines changed: 33 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,66 @@
11
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/percona/pg_tde/badge)](https://scorecard.dev/viewer/?uri=github.com/percona/pg_tde)
22
[![codecov](https://codecov.io/github/percona/postgres/graph/badge.svg?token=Wow78BMYdP)](https://codecov.io/github/percona/postgres)
33
[![Forum](https://img.shields.io/badge/Forum-join-brightgreen)](https://forums.percona.com/)
4+
[![Docs](https://img.shields.io/badge/docs-pg_tde-blue)](https://docs.percona.com/pg-tde/)
45

56
# pg_tde: Transparent Database Encryption for PostgreSQL
67

7-
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)
8+
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)
9+
10+
## Table of Contents
811

9-
## Table of contents
1012
1. [Overview](#overview)
1113
2. [Documentation](#documentation)
12-
1. [Percona Server for PostgreSQL](#percona-server-for-postgresql)
13-
3. [Build from sources](#building-from-sources-for-community-postgresql)
14+
3. [Percona Server for PostgreSQL](#percona-server-for-postgresql)
1415
4. [Run in docker](#run-in-docker)
15-
5. [Setting up](#setting-up)
16-
6. [Helper functions](#helper-functions)
16+
5. [Set up pg_tde](#set-up-pg_tde)
17+
6. [Downloads](#downloads)
18+
7. [Additional functions](#additional-functions)
1719

1820
## Overview
19-
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/).
2021

21-
### This extension provides one `access method`:
22+
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).
23+
24+
### This extension provides the `tde_heap access method`
25+
26+
This access method:
2227

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

2933
## Documentation
3034

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

3337
## Percona Server for PostgreSQL
3438

3539
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).
3640

37-
## Building from sources for community PostgreSQL
38-
1. Install required dependencies (replace XX with 16 or 17)
39-
- On Debian and Ubuntu:
40-
```sh
41-
sudo apt install make gcc autoconf git libcurl4-openssl-dev postgresql-server-dev-XX
42-
```
43-
44-
- On RHEL 8 compatible OS:
45-
```sh
46-
sudo yum install epel-release
47-
yum --enablerepo=powertools install git make gcc autoconf libcurl-devel perl-IPC-Run redhat-rpm-config openssl-devel postgresqlXX-devel
48-
```
49-
50-
- On MacOS:
51-
```sh
52-
brew install make autoconf curl gettext postresql@XX
53-
```
54-
55-
2. Install or build postgresql 16 or 17
56-
3. If postgres is installed in a non standard directory, set the `PG_CONFIG` environment variable to point to the `pg_config` executable
57-
58-
4. Clone the repository, build and install it with the following commands:
59-
60-
```sh
61-
git clone https://github.com/percona/pg_tde
62-
```
63-
64-
5. Compile and install the extension
65-
66-
```sh
67-
cd pg_tde
68-
make USE_PGXS=1
69-
sudo make USE_PGXS=1 install
70-
```
71-
7241
## Run in Docker
7342

74-
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)
75-
76-
```
77-
docker run --name pg-tde -e POSTGRES_PASSWORD=mysecretpassword -d perconalab/pg_tde
78-
```
79-
Docker file is available [here](https://github.com/percona/pg_tde/blob/main/docker/Dockerfile)
80-
81-
82-
_See [Make Builds for Developers](https://github.com/percona/pg_tde/wiki/Make-builds-for-developers) for more info on the build infrastructure._
83-
84-
## Setting up
85-
86-
1. Add extension to the `shared_preload_libraries`:
87-
1. Via configuration file `postgresql.conf `
88-
```
89-
shared_preload_libraries=pg_tde
90-
```
91-
2. Via SQL using [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html) command
92-
```sql
93-
ALTER SYSTEM SET shared_preload_libraries = 'pg_tde';
94-
```
95-
2. Start or restart the `postgresql` cluster to apply the changes.
96-
* On Debian and Ubuntu:
97-
98-
```sh
99-
sudo systemctl restart postgresql-17
100-
```
101-
102-
* On RHEL 8 compatible OS (replace XX with your version):
103-
```sh
104-
sudo systemctl restart postgresql-XX.service
105-
```
106-
3. [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) with SQL (requires superuser or a database owner privileges):
107-
108-
```sql
109-
CREATE EXTENSION pg_tde;
110-
```
111-
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.
112-
113-
114-
```sql
115-
-- For Vault-V2 key provider
116-
-- pg_tde_add_database_key_provider_vault_v2(provider_name, vault_token, vault_url, vault_mount_path, vault_ca_path)
117-
SELECT pg_tde_add_database_key_provider_vault_v2(
118-
'vault-provider',
119-
'/path/to/token_file',
120-
'https://your.vault.server',
121-
'secret', NULL);
122-
123-
-- For File key provider
124-
-- pg_tde_add_database_key_provider_file(provider_name, file_path);
125-
SELECT pg_tde_add_database_key_provider_file('file','/tmp/pgkeyring');
126-
```
127-
128-
**Note: The `File` provided is intended for development and stores the keys unencrypted in the specified data file.**
129-
130-
5. Set the principal key for the database using the `pg_tde_set_key` function.
131-
132-
```sql
133-
-- pg_tde_set_key_using_database_key_provider(key_name, provider_name);
134-
SELECT pg_tde_set_key_using_database_key_provider('my-key','file');
135-
```
136-
137-
6. Specify `tde_heap` access method during table creation
138-
```sql
139-
CREATE TABLE albums (
140-
album_id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
141-
artist_id INTEGER,
142-
title TEXT NOT NULL,
143-
released DATE NOT NULL
144-
) USING tde_heap;
145-
```
146-
7. You can encrypt existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
147-
```sql
148-
ALTER TABLE table_name SET ACCESS METHOD tde_heap;
149-
```
150-
151-
152-
## Latest test release
153-
154-
To download the latest build of the main branch, use the `HEAD` release from [releases](https://github.com/percona/pg_tde/releases).
43+
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).
15544

156-
Builds are available in a tar.gz format, containing only the required files, and as a deb package.
157-
The deb package is built against the pgdg16 release, but this dependency is not yet enforced in the package.
45+
_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)._
15846

47+
## Set up pg_tde
15948

160-
## Helper functions
49+
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).
16150

162-
The extension provides the following helper functions:
51+
The guide also includes instructions for:
52+
53+
- Installing and enabling the extension
54+
- Setting up key providers
55+
- Creating encrypted tables
56+
57+
## Downloads
58+
59+
To download the latest build of the main branch, use the `HEAD` release from [releases](https://github.com/percona/postgres/releases).
60+
61+
Builds are available in a tar.gz format, containing only the required files, and as a deb package.
62+
The deb package is built against the pgdg17 release, but this dependency is not yet enforced in the package.
16363

164-
### pg_tde_is_encrypted(tablename)
64+
## Additional functions
16565

166-
Returns `t` if the relation is encrypted, if unencrypted `f` or `NULL` if the
167-
relation lacks storage, i.e. views, foreign tables, and partitioning tables and
168-
indexes.
66+
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).

0 commit comments

Comments
 (0)
0