Skip to content

Commit f86706a

Browse files
committed
Added diagrams to overview
1 parent bcb0094 commit f86706a

23 files changed

+449
-250
lines changed
62.9 KB
Loading
38.2 KB
Loading
Loading
Loading

docs/apt.md

+6-1
Original file line numberDiff line numberDiff line change
@@ -140,11 +140,16 @@ Run all the commands in the following sections as root or using the `sudo` comma
140140

141141
Install `pg_gather`
142142

143-
144143
```{.bash data-prompt="$"}
145144
$ sudo apt install percona-pg-gather
146145
```
147146

147+
Install `pgvector`
148+
149+
```{.bash data-prompt="$"}
150+
- $ sudo apt install percona-postgresql-{{pgversion}}-pgvector
151+
```
152+
148153
Some extensions require additional setup in order to use them with Percona Distribution for PostgreSQL. For more information, refer to [Enabling extensions](enable-extensions.md).
149154

150155
### Start the service

docs/css/design.css

+1
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,7 @@
269269
vertical-align: baseline;
270270
padding: 0 0.2em 0.1em;
271271
border-radius: 0.15em;
272+
white-space: pre-wrap; /* Ensure long lines wrap */
272273
}
273274
.md-typeset .highlight code span,
274275
.md-typeset code,

docs/docker.md

+66
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ For more information about using Docker, see the [Docker Docs :octicons-link-ext
2727
| `percona-pgaudit{{pgversion}}_set_user`| An additional layer of logging and control when unprivileged users must escalate themselves to superuser or object owner roles in order to perform needed maintenance tasks.|
2828
| `percona-pg_repack{{pgversion}}`| rebuilds PostgreSQL database objects.|
2929
| `percona-wal2json{{pgversion}}` | a PostgreSQL logical decoding JSON output plugin.|
30+
| `percona-pgvector` | A vector similarity search for PostgreSQL|
3031

3132
## Start the container {.power-number}
3233

@@ -97,6 +98,71 @@ Where:
9798
`tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image.
9899
* `address` is the network address where your database container is running. Use 127.0.0.1, if the database container is running on the local machine/host.
99100
101+
## Enable encryption
102+
103+
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.
104+
105+
Here's how to do this:
106+
{.power-number}
107+
108+
1. Start the container with the `ENABLE_PG_TDE=1` environment variable:
109+
110+
```{.bash data-prompt="$"}
111+
$ docker run --name container-name -e ENABLE_PG_TDE=1 -e POSTGRES_PASSWORD=sUpers3cRet -d percona/percona-distribution-postgresql:{{dockertag}}-multi
112+
```
113+
114+
where:
115+
116+
* `container-name` is the name you assign to your container
117+
* `ENABLE_PG_TDE=1` adds the `pg_tde` to the `shared_preload_libraries` and enables the custom storage manager
118+
* `POSTGRES_PASSWORD` is the superuser password
119+
120+
121+
2. Connect to the container and start the interactive `psql` session:
122+
123+
```{.bash data-prompt="$"}
124+
$ docker exec -it container-name psql
125+
```
126+
127+
??? example "Sample output"
128+
129+
```{.text .no-copy}
130+
psql ({{dockertag}} - Percona Server for PostgreSQL {{dockertag}}.1)
131+
Type "help" for help.
132+
133+
postgres=#
134+
```
135+
136+
3. Create the extension in the database where you want to encrypt data. This requires superuser privileges.
137+
138+
```sql
139+
CREATE EXTENSION pg_tde;
140+
```
141+
142+
4. Configure a key provider. In this sample configuration intended for testing and development purpose, we use a local keyring provider.
143+
144+
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.
145+
146+
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
147+
148+
```sql
149+
SELECT pg_tde_add_key_provider_file('file-keyring','/tmp/pg_tde_test_local_keyring.per');
150+
```
151+
152+
5. Add a principal key
153+
154+
```sql
155+
SELECT pg_tde_set_principal_key('test-db-master-key','file-keyring');
156+
```
157+
158+
The key is autogenerated. You are ready to use data encryption.
159+
160+
6. Create a table with encryption enabled. Pass the `USING tde_heap` clause to the `CREATE TABLE` command:
161+
162+
```sql
163+
CREATE TABLE <table_name> (<field> <datatype>) USING tde_heap;
164+
```
165+
100166
## Enable `pg_stat_monitor`
101167

102168
To enable the `pg_stat_monitor` extension after launching the container, do the following:

docs/enable-extensions.md

+8
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,14 @@ wal_level = logical
137137

138138
Start / restart the server to apply the changes.
139139

140+
## pgvector
141+
142+
To get started, enable the extension for the database where you want to use it:
143+
144+
```sql
145+
CREATE EXTENSION vector;
146+
```
147+
140148
## Next steps
141149

142150
[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}

docs/how-to.md

-75
This file was deleted.

docs/minor-upgrade.md

+18
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,24 @@ Minor upgrade of Percona Distribution for PostgreSQL includes the following step
2424

2525
Before the upgrade, [update the `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/percona-release.html#updating-percona-release-to-the-latest-version) utility to the latest version. This is required to install the new version packages of Percona Distribution for PostgreSQL.
2626

27+
## Before you start
28+
29+
1. [Update the `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/percona-release.html#updating-percona-release-to-the-latest-version) utility to the latest version. This is required to install the new version packages of Percona Distribution for PostgreSQL.
30+
31+
2. Starting with version 17.2.1, `pg_tde` is part of the Percona Server for PostgreSQL package. If you installed `pg_tde` from its dedicated package, do the following to avoid conflicts during the upgrade:
32+
33+
* Drop the extension using the `DROP EXTENSION` with `CASCADE` command.
34+
35+
<i warning>:material-alert: Warning:</i> The use of the `CASCADE` parameter deletes all tables that were created in the database with `pg_tde` enabled and also all dependencies upon the encrypted table (e.g. foreign keys in a non-encrypted table used in the encrypted one).
36+
37+
```sql
38+
DROP EXTENSION pg_tde CASCADE
39+
```
40+
41+
* Uninstall the `percona-postgresql-17-pg-tde` package for Debian/Ubuntu or the `percona-pg_tde_17` package for RHEL and derivatives.
42+
43+
## Procedure
44+
2745
Run **all** commands as root or via **sudo**:
2846
{.power-number}
2947

docs/release-notes-v17.2.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Percona Distribution for PostgreSQL 17.2.1 ({{date.17_2}})
2+
3+
--8<-- "release-notes-intro.md"
4+
5+
This release of Percona Distribution for PostgreSQL is based on Percona Server for PostgreSQL 17.2.1 - a binary compatible, open source drop in replacement of [PostgreSQL Community 17.2](https://www.postgresql.org/docs/17/release-17-2.html).
6+
7+
## Release Highlights
8+
9+
* This release includes fixes for [CVE-2024-10978](https://www.postgresql.org/support/security/CVE-2024-10978/) and for certain PostgreSQL extensions that break because they depend on the modified Application Binary Interface (ABI). These regressions were introduced in PostgreSQL 17.1, 16.5, 15.9, 14.14, 13.17, and 12.21. For this reason, the release of Percona Distribution for PostgreSQL 17.1.1 has been skipped.
10+
* Percona Distribution for PostgreSQL includes [`pgvector` :octicons-link-external-16](https://github.com/pgvector/pgvector) - an open source extension that enables you to use PostgreSQL as a vector database. It brings vector data type and vector operations (mainly similarity search) to PostgreSQL. You can install `pgvector` from repositories, tarballs, and it is also available as a Docker image.
11+
* The new version of `pg_tde` extension features index encryption and the support of storing encryption keys in KMIP-compatible servers. These feature come with the Beta version of the `tde_heap` access method. Learn more in the [pg_tde release notes :octicons-link-external-16:](https://percona.github.io/pg_tde/main/release-notes/release-notes.html)
12+
* The `pg_tde` extension itself is now a part of the Percona Server for PostgreSQL server package and a Docker image. If you installed the extension before, from its individual package, uninstall it first to avoid conflicts during the upgrade. See the [Minor Upgrade of Percona Distribution for PostgreSQL](minor-upgrade.md#preconditions) for details.
13+
For how to run `pg_tde` in Docker, check the [Enable encryption](docker.md#enable-encryption) section in the documentation.
14+
* Percona Distribution for PostgreSQL now statically links `llvmjit.so` library for Red Hat Enterprise Linux 8 and 9 and compatible derivatives. This resolves the conflict between the LLVM version required by Percona Distribution for PostgreSQL and the one supplied with the operating system. This also enables you to use the LLVM modules supplied with the operating system for other software you require.
15+
* Percona Monitoring and Management (PMM) 2.43.2 is now compatible with `pg_stat_monitor` 2.1.0 to monitor PostgreSQL 17.
16+
17+
------------------------------------------------------------------------------
18+
19+
20+
The following is the list of extensions available in Percona Distribution for PostgreSQL.
21+
22+
| Extension | Version | Description |
23+
| ------------------- | -------------- | ---------------------------- |
24+
| [etcd](https://etcd.io/)| 3.5.16 | A distributed, reliable key-value store for setting up high available Patroni clusters |
25+
|[HAProxy :octicons-link-external-16:](http://www.haproxy.org/) | 2.8.11 | a high-availability and load-balancing solution |
26+
| [Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) | 4.0.3 | a HA (High Availability) solution for PostgreSQL |
27+
| [PgAudit :octicons-link-external-16:](https://www.pgaudit.org/) | 17.0 | provides detailed session or object audit logging via the standard logging facility provided by PostgreSQL |
28+
| [pgAudit set_user :octicons-link-external-16:](https://github.com/pgaudit/set_user)| 4.1.0 | provides an additional layer of logging and control when unprivileged users must escalate themselves to superusers or object owner roles in order to perform needed maintenance tasks.|
29+
| [pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) | 2.54.0 | a backup and restore solution for PostgreSQL |
30+
|[pgBadger :octicons-link-external-16:](https://github.com/darold/pgbadger) | 12.4 | a fast PostgreSQL Log Analyzer.|
31+
|[PgBouncer :octicons-link-external-16:](https://www.pgbouncer.org/) |1.23.1 | a lightweight connection pooler for PostgreSQL|
32+
| [pg_gather :octicons-link-external-16:](https://github.com/jobinau/pg_gather)| v28 | an SQL script for running the diagnostics of the health of PostgreSQL cluster |
33+
| [pgpool2 :octicons-link-external-16:](https://git.postgresql.org/gitweb/?p=pgpool2.git;a=summary) | 4.5.4 | a middleware between PostgreSQL server and client for high availability, connection pooling and load balancing.|
34+
| [pg_repack :octicons-link-external-16:](https://github.com/reorg/pg_repack) | 1.5.1 | rebuilds PostgreSQL database objects |
35+
| [pg_stat_monitor :octicons-link-external-16:](https://github.com/percona/pg_stat_monitor)|{{pgsmversion}} | collects and aggregates statistics for PostgreSQL and provides histogram information.|
36+
|[pgvector :octicons-link-external-16:](https://github.com/pgvector/pgvector)| v0.8.0 | A vector similarity search for PostgreSQL|
37+
| [PostGIS :octicons-link-external-16:](https://github.com/postgis/postgis) | 3.3.7 | a spatial extension for PostgreSQL.|
38+
| [PostgreSQL Common :octicons-link-external-16:](https://salsa.debian.org/postgresql/postgresql-common)| 265 | PostgreSQL database-cluster manager. It provides a structure under which multiple versions of PostgreSQL may be installed and/or multiple clusters maintained at one time.|
39+
|[wal2json :octicons-link-external-16:](https://github.com/eulerto/wal2json) |2.6 | a PostgreSQL logical decoding JSON output plugin|
40+
41+
For Red Hat Enterprise Linux 8 and 9 and compatible derivatives, Percona Distribution for PostgreSQL also includes the following packages:
42+
43+
* `llvm` 17.0.6 packages. This fixes compatibility issues with LLVM from upstream.
44+
* supplemental `python3-etcd` 0.4.5 packages, which can be used for setting up Patroni clusters.
45+
46+
Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/17/libpq.html) library. It contains "a set of
47+
library functions that allow client programs to pass queries to the PostgreSQL
48+
backend server and to receive the results of these queries."

docs/release-notes.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
# Percona Distribution for PostgreSQL release notes
22

3-
* [Percona Distribution for PostgreSQL 17](release-notes-v17.0.md) ({{date.17_0}})
3+
* [Percona Distribution for PostgreSQL 17.2.1](release-notes-v17.2.md) ({{date.17_2}})
4+
* [Percona Distribution for PostgreSQL 17.0.1](release-notes-v17.0.md) ({{date.17_0}})

docs/solutions/ha-architecture.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Architecture layout
1+
# Architecture
22

33
As we discussed in the [overview of high availability](high-availability.md), the minimalist approach to a highly-available deployment is to have a three-node PostgreSQL cluster with the cluster management and failover mechanisms, load balancer and a backup / restore solution.
44

5-
The following diagram shows this architecture.
5+
The following diagram shows this architecture with the tools we recommend to use.
66

77
![Architecture of the three-node, single primary PostgreSQL cluster](../_images/diagrams/ha-architecture-patroni.png)
88

0 commit comments

Comments
 (0)