Skip to content

Commit ab6391e

Browse files
AndriciucAndriciuc
authored
PG-1928 Add tool descriptions bundled with pg_tde in PG (#876)
* PG-1928 Add tool descriptions bundled with pg_tde in PG - added initial chapter with ToC file * add new chapter to toc * add links for tools in topic - minor text fixes and rewrites * small updates to text, simplified explanations for quick reads
1 parent cbd44a1 commit ab6391e

File tree

2 files changed

+160
-0
lines changed

2 files changed

+160
-0
lines changed

‎docs/solutions/tde-tools-compatibility.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# TDE compatibility with tools and extensions
2+
3+
Transparent Data Encryption (TDE) protects PostgreSQL data files and Write-Ahead Logs (WAL) by encrypting them at rest.
4+
5+
This page describes how TDE interacts with each component included in the Percona Distribution for PostgreSQL.
6+
7+
## Compatibility summary
8+
9+
| Component | Affected by TDE | Notes |
10+
|------------|----------------|-------|
11+
| [**etcd**](#etcd) | ❌ No | Stores configuration data, not PostgreSQL data. |
12+
| [**HAProxy**](#haproxy) | ❌ No | Operates at network level; unaffected by TDE. |
13+
| [**Patroni**](#patroni) | ⚙️ Partial | Cluster replication requires consistent keys. |
14+
| [**pgAudit**](#pgaudit) | ❌ No | Logs SQL activity; no interaction with encrypted files. |
15+
| [**pgAudit set_user**](#pgaudit-set_user) | ❌ No | Session role tracking unaffected by encryption. |
16+
| [**pgBackRest**](#pgbackrest) | ✅ Yes | Backs up encrypted data and WAL; requires key for restore. |
17+
| [**pgBadger**](#pgbadger) | ❌ No | Processes plaintext PostgreSQL logs; not impacted. |
18+
| [**pgBouncer**](#pgbouncer) | ❌ No | Connection pooling; no access to storage layer. |
19+
| [**pg_gather**](#pg_gather) | ❌ No | Collects performance stats; queries decrypted data in memory. |
20+
| [**pgpool2**](#pgpool2) | ❌ No | Middleware routing connections; not affected by TDE. |
21+
| [**pg_repack**](#pg_repack) | ✅ Yes | Rewrites data files; requires access to decrypted in-memory data. |
22+
| [**pg_stat_monitor**](#pg_stat_monitor) | ❌ No | Operates at query-level statistics; no WAL interaction. |
23+
| [**pgvector**](#pgvector) | ❌ No | Works on in-memory and SQL-level data; encryption transparent. |
24+
| [**PostGIS**](#postgis) | ❌ No | Spatial extensions operate on decrypted in-memory data. |
25+
| [**wal2json**](#wal2json) | ⚠️ Limited | Logical decoding may fail on encrypted WAL. |
26+
| [**PostgreSQL Commons and Contrib Modules**](#postgresql-commons-and-contrib-modules) | ❌ No | Core modules function normally with TDE enabled. |
27+
28+
## etcd
29+
30+
`etcd` is a distributed key-value store used by Patroni to maintain cluster state.
31+
It does not store PostgreSQL data or WAL files.
32+
33+
- TDE does not impact etcd functionality.
34+
- No special configuration is required.
35+
36+
## HAProxy
37+
38+
`HAProxy` provides load balancing and connection routing.
39+
Since it operates over TCP connections, not on data files:
40+
41+
- TDE does not affect its behavior.
42+
- No configuration changes are needed.
43+
44+
## Patroni
45+
46+
`Patroni` manages PostgreSQL high availability and replication.
47+
It is not directly impacted by TDE, but the following considerations apply:
48+
49+
- Each cluster node must share the same TDE key provider and key ID.
50+
- A key mismatch will prevent replicas from starting or replaying WAL.
51+
52+
## pgAudit
53+
54+
`pgAudit` logs SQL statements for auditing purposes.
55+
56+
- TDE does not affect audit logging because SQL is captured before disk encryption.
57+
- Logs are written as plaintext files.
58+
59+
## pgAudit set_user
60+
61+
`pgAudit set_user` provides controlled user switching.
62+
It operates at the session level and is **not affected** by encryption of data files.
63+
64+
- No TDE-specific configuration is required.
65+
66+
## pgBackRest
67+
68+
`pgBackRest` performs physical backups and restores of PostgreSQL clusters.
69+
It fully supports encrypted databases.
70+
71+
- Backups include encrypted data and WAL segments.
72+
- Restores require the original TDE encryption key or Vault access.
73+
74+
!!! warning
75+
Restoring without the correct key makes the backup unusable.
76+
77+
!!! tip
78+
Use a [global key provider :octicons-link-external-16:](https://docs.percona.com/pg-tde/global-key-provider-configuration/overview.html).
79+
80+
## pgBadger
81+
82+
`pgBadger` analyzes PostgreSQL logs for activity and performance.
83+
84+
- Logs are not encrypted by TDE.
85+
- No configuration or compatibility issues.
86+
87+
## pgBouncer
88+
89+
`pgBouncer` handles connection pooling at the network layer.
90+
It has no interaction with encrypted data or WAL files.
91+
92+
- TDE does not affect pgBouncer.
93+
- No configuration changes are needed.
94+
95+
## pg_gather
96+
97+
`pg_gather` collects system and query statistics from running databases.
98+
99+
- TDE is transparent; no configuration required.
100+
101+
## pgpool2
102+
103+
`pgpool2` manages load balancing and connection routing for PostgreSQL.
104+
105+
- Works on SQL sessions, not files.
106+
- TDE encryption at rest has no impact.
107+
108+
## pg_repack
109+
110+
`pg_repack` rebuilds database objects to reclaim space or optimize performance.
111+
112+
- Works with decrypted data in memory.
113+
- Can safely be used with TDE-enabled clusters.
114+
115+
## pg_stat_monitor
116+
117+
`pg_stat_monitor` collects detailed query statistics.
118+
119+
- Operates entirely at the SQL and memory level.
120+
- TDE does not affect functionality.
121+
122+
## pgvector
123+
124+
`pgvector` stores and searches vector embeddings.
125+
126+
- Operates at the SQL layer, reading decrypted in-memory data.
127+
- TDE does not change its functionality.
128+
129+
## PostGIS
130+
131+
`PostGIS` adds spatial data types and functions.
132+
133+
- Operates on decrypted data loaded into memory.
134+
- TDE does not change its functionality.
135+
136+
## wal2json
137+
138+
`wal2json` converts WAL records into JSON for logical replication.
139+
140+
With TDE enabled:
141+
142+
- WAL files are encrypted on disk.
143+
- Logical decoding may fail because it cannot access decrypted WAL.
144+
145+
!!! warning
146+
`wal2json` is **not compatible** with encrypted WAL. Consider using logical replication with TDE disabled, or alternative decoding plugins.
147+
148+
## PostgreSQL Commons and Contrib Modules
149+
150+
Common and contrib modules (such as `pg_stat_statements`, `pg_trgm`, and `hstore`)
151+
operate at the SQL and memory level.
152+
153+
- TDE does not change their functionality.
154+
- No additional configuration is required.
155+
156+
## See also
157+
158+
- [Percona `pg_tde` documentation](https://docs.percona.com/postgresql/pg_tde)

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ nav:
7070
- Backup and disaster recovery:
7171
- 'Overview': 'solutions/backup-recovery.md'
7272
- solutions/dr-pgbackrest-setup.md
73+
- Data encryption:
74+
- 'TDE compatibility with tools and extensions': solutions/tde-tools-compatibility.md
7375
- Spatial data handling:
7476
- Overview: solutions/postgis.md
7577
- Deployment: solutions/postgis-deploy.md

0 commit comments

Comments
 (0)