diff --git a/docs/major-upgrade.md b/docs/major-upgrade.md index 6ea62429f..961508f79 100644 --- a/docs/major-upgrade.md +++ b/docs/major-upgrade.md @@ -2,16 +2,15 @@ This document describes the in-place upgrade of Percona Distribution for PostgreSQL using the `pg_upgrade` tool. -!!! important +To ensure a smooth upgrade path, follow these steps: - When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following: - - Percona Distribution for PostgreSQL 16.3, 15.7, 14.12, 13.15 and 12.18 include `llvm` packages 16.0.6, while its previous versions 16.2, 15.6, 14.11, 13.14, and 12.17 include `llvm` 12.0.1. Since `llvm` libraries differ and are not compatible, the direct major version upgrade from 15.6 to 16.3 may cause issues. +* Upgrade to the latest minor version within your current major version (e.g., from 16.6 to 16.9). +* Then, perform the major upgrade to your desired version (e.g., from 16.9 to 17.5). - To ensure a smooth upgrade path, follow these steps: +!!! note + When running a major upgrade on **RHEL 8 and compatible derivatives**, consider the following: - * Upgrade to the latest minor version within your current major version (e.g., from 15.6 to 15.7). - * Then, perform the major upgrade to your desired version (e.g., from 15.7 to 16.3). + Percona Distribution for PostgreSQL 16.3, 15.7, 14.12, 13.15 and 12.18 include `llvm` packages 16.0.6, while its previous versions 16.2, 15.6, 14.11, 13.14, and 12.17 include `llvm` 12.0.1. Since `llvm` libraries differ and are not compatible, the direct major version upgrade from 15.6 to 16.3 may cause issues. The in-place upgrade means installing a new version without removing the old version and keeping the data files on the server. @@ -27,26 +26,19 @@ Similar to installing, we recommend you to upgrade Percona Distribution for Post The general in-place upgrade flow for Percona Distribution for PostgreSQL is the following: - 1. Install new version of Percona Distribution for PostgreSQL packages. - 2. Stop the PostgreSQL service. - 3. Check the upgrade without modifying the data. - 4. Upgrade Percona Distribution for PostgreSQL. - 5. Start PostgreSQL service. - 6. Execute the **analyze_new_cluster.sh** script to generate statistics so the system is usable. - 7. Delete old packages and configuration files. The exact steps may differ depending on the package manager of your operating system. @@ -56,22 +48,23 @@ The exact steps may differ depending on the package manager of your operating sy Run **all** commands as root or via **sudo**: {.power-number} -1. Install Percona Distribution for PostgreSQL {{pgversion}} packages. +1. Install Percona Distribution for PostgreSQL 17 packages. + !!! note + When installing version 17, if prompted via a pop-up to upgrade to the latest available version, select **No**. - * [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html). If you have installed it before, [update it to the latest version](https://docs.percona.com/percona-software-repositories/updating.html) - - * Enable Percona repository: + * [Install percona-release :octicons-link-external-17:](https://docs.percona.com/percona-software-repositories/installing.html). If you have installed it before, [update it to the latest version](https://docs.percona.com/percona-software-repositories/updating.html) + + * Enable Percona repository ```{.bash data-prompt="$"} - $ sudo percona-release setup ppg-{{pgversion}} + $ sudo percona-release setup ppg-17 ``` - - * Install Percona Distribution for PostgreSQL {{pgversion}} package: + * Install Percona Distribution for PostgreSQL 17 package ```{.bash data-prompt="$"} - $ sudo apt install percona-postgresql-{{pgversion}} + $ sudo apt install percona-postgresql-17 ``` 2. Stop the `postgresql` service. @@ -82,94 +75,113 @@ Run **all** commands as root or via **sudo**: This stops both Percona Distribution for PostgreSQL 16 and 17. - 3. Run the database upgrade. + * Log in as the `postgres` user - * Log in as the `postgres` user. - - ```{.bash data-prompt="$"} - $ sudo su postgres - ``` - - - * Change the current directory to the `tmp` directory where logs and some scripts will be recorded: - - ```{.bash data-prompt="$"} - $ cd tmp/ - ``` - - - * Check the ability to upgrade Percona Distribution for PostgreSQL from 16 to 17: - - ```{.bash data-prompt="$"} - $ /usr/lib/postgresql/{{pgversion}}/bin/pg_upgrade \ - --old-datadir=/var/lib/postgresql/16/main \ - --new-datadir=/var/lib/postgresql/{{pgversion}}/main \ - --old-bindir=/usr/lib/postgresql/16/bin \ - --new-bindir=/usr/lib/postgresql/{{pgversion}}/bin \ - --old-options '-c config_file=/etc/postgresql/16/main/postgresql.conf' \ - --new-options '-c config_file=/etc/postgresql/{{pgversion}}/main/postgresql.conf' \ - --check - ``` - - The `--check` flag here instructs `pg_upgrade` to only check the upgrade without changing any data. + ```{.bash data-prompt="$"} + $ sudo su postgres + ``` - **Sample output** + * Check if you can upgrade Percona Distribution for PostgreSQL from 16 to 17 - ``` - Performing Consistency Checks - ----------------------------- - Checking cluster versions ok - Checking database user is the install user ok - Checking database connection settings ok - Checking for prepared transactions ok - Checking for reg* data types in user tables ok - Checking for contrib/isn with bigint-passing mismatch ok - Checking for tables WITH OIDS ok - Checking for invalid "sql_identifier" user columns ok - Checking for presence of required libraries ok - Checking database user is the install user ok - Checking for prepared transactions ok - - *Clusters are compatible* - ``` + ```{.bash data-prompt="$"} + $ pg_upgradecluster 16 main --check + # Sample output: pg_upgradecluster pre-upgrade checks ok + ``` + The `--check` flag here instructs `pg_upgrade` to only check the upgrade without changing any data. * Upgrade the Percona Distribution for PostgreSQL - ```{.bash data-prompt="$"} - $ /usr/lib/postgresql/{{pgversion}}/bin/pg_upgrade \ - --old-datadir=/var/lib/postgresql/16/main \ - --new-datadir=/var/lib/postgresql/{{pgversion}}/main \ - --old-bindir=/usr/lib/postgresql/16/bin \ - --new-bindir=/usr/lib/postgresql/{{pgversion}}/bin \ - --old-options '-c config_file=/etc/postgresql/16/main/postgresql.conf' \ - --new-options '-c config_file=/etc/postgresql/{{pgversion}}/main/postgresql.conf' \ - --link - ``` - - The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data. - - If you don’t wish to use the `--link` option, make sure that you have enough disk space to store 2 copies of files for both old version and new version clusters. - - - * Go back to the regular user: - - ```{.bash data-prompt="$"} - $ exit - ``` - - - * The Percona Distribution for PostgreSQL 16 uses the `5432` port while the Percona Distribution for PostgreSQL 17 is set up to use the `5433` port by default. To start the Percona Distribution for PostgreSQL 17, swap ports in the configuration files of both versions. - - ```{.bash data-prompt="$"} - $ sudo vim /etc/postgresql/{{pgversion}}/main/postgresql.conf - $ port = 5433 # Change to 5432 here - $ sudo vim /etc/postgresql/16/main/postgresql.conf - $ port = 5432 # Change to 5433 here - ``` + ```{.bash data-prompt="$"} + $ pg_upgradecluster 16 main + ``` +
+ Sample output (click to expand) + ```bash + Upgrading cluster 16/main to 17/main ... + Stopping old cluster... + Restarting old cluster with restricted connections... + ... + Success. Please check that the upgraded cluster works. If it does, + you can remove the old cluster with: + pg_dropcluster 16 main + + Ver Cluster Port Status Owner Data directory Log file + 17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log + + Sample output: + Upgrading cluster 16/main to 17/main ... + Stopping old cluster... + Restarting old cluster with restricted connections... + Notice: extra pg_ctl/postgres options given, bypassing systemctl for start operation + Creating new PostgreSQL cluster 17/main ... + /usr/lib/postgresql/17/bin/initdb -D /var/lib/postgresql/17/main --auth-local peer --auth-host scram-sha-256 --no-instructions --encoding UTF8 --lc-collate C.UTF-8 --lc-ctype C.UTF-8 --locale-provider libc + The files belonging to this database system will be owned by user "postgres". + This user must also own the server process. + + The database cluster will be initialized with locale "C.UTF-8". + The default text search configuration will be set to "english". + + Data page checksums are disabled. + + fixing permissions on existing directory /var/lib/postgresql/17/main ... ok + creating subdirectories ... ok + selecting dynamic shared memory implementation ... posix + selecting default max_connections ... 100 + selecting default shared_buffers ... 128MB + selecting default time zone ... Etc/UTC + creating configuration files ... ok + running bootstrap script ... ok + performing post-bootstrap initialization ... ok + syncing data to disk ... ok + + Copying old configuration files... + Copying old start.conf... + Copying old pg_ctl.conf... + Starting new cluster... + Notice: extra pg_ctl/postgres options given, bypassing systemctl for start operation + Running init phase upgrade hook scripts ... + + Roles, databases, schemas, ACLs... + set_config + ------------ + + (1 row) + + set_config + ------------ + + (1 row) + + Fixing hardcoded library paths for stored procedures... + Upgrading database template1... + Fixing hardcoded library paths for stored procedures... + Upgrading database postgres... + Stopping target cluster... + Stopping old cluster... + Disabling automatic startup of old cluster... + Starting upgraded cluster on port 5432... + Running finish phase upgrade hook scripts ... + vacuumdb: processing database "postgres": Generating minimal optimizer statistics (1 target) + vacuumdb: processing database "template1": Generating minimal optimizer statistics (1 target) + vacuumdb: processing database "postgres": Generating medium optimizer statistics (10 targets) + vacuumdb: processing database "template1": Generating medium optimizer statistics (10 targets) + vacuumdb: processing database "postgres": Generating default (full) optimizer statistics + vacuumdb: processing database "template1": Generating default (full) optimizer statistics + + Success. Please check that the upgraded cluster works. If it does, + you can remove the old cluster with + pg_dropcluster 16 main + + Ver Cluster Port Status Owner Data directory Log file + 16 main 5433 down postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log + Ver Cluster Port Status Owner Data directory Log file + 17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log + ``` +
4. Start the `postgreqsl` service. @@ -177,38 +189,29 @@ Run **all** commands as root or via **sudo**: $ sudo systemctl start postgresql.service ``` - 5. Check the `postgresql` version. * Log in as a postgres user - + ```{.bash data-prompt="$"} $ sudo su postgres ``` * Check the database version - + ```{.bash data-prompt="$"} $ psql -c "SELECT version();" ``` +6. Delete the old cluster's data files. -6. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster: + !!! note + Before deleting the old cluster, verify that the newly upgraded cluster is fully operational. Keeping the old cluster does not negatively affect the functionality or performance of your upgraded cluster. ```{.bash data-prompt="$"} - $ /usr/lib/postgresql/{{pgversion}}/bin/vacuumdb --all --analyze-in-stages + $ pg_dropcluster 16 main ``` -7. Delete the old cluster's data files: - - ```{.bash data-prompt="$"} - $ ./delete_old_cluster.sh - $ sudo rm -rf /etc/postgresql/16/main - $ #Logout - $ exit - ``` - - ## On Red Hat Enterprise Linux and CentOS using `yum` Run **all** commands as root or via **sudo**: @@ -216,16 +219,14 @@ Run **all** commands as root or via **sudo**: 1. Install Percona Distribution for PostgreSQL 17 packages - * [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) - + * Enable Percona repository: ```{.bash data-prompt="$"} $ sudo percona-release setup ppg-{{pgversion}} ``` - * Install Percona Distribution for PostgreSQL {{pgversion}}: ```{.bash data-prompt="$"} @@ -242,7 +243,7 @@ Run **all** commands as root or via **sudo**: * Set up locale settings - ``` + ```ini export LC_ALL="en_US.UTF-8" export LC_CTYPE="en_US.UTF-8" ``` @@ -253,24 +254,20 @@ Run **all** commands as root or via **sudo**: $ /usr/pgsql-{{pgversion}}/bin/initdb -D /var/lib/pgsql/{{pgversion}}/data ``` - 3. Stop the `postgresql` 16 service ```{.bash data-prompt="$"} $ systemctl stop postgresql-16 ``` - 4. Run the database upgrade. - * Log in as the `postgres` user ```{.bash data-prompt="$"} $ sudo su postgres ``` - * Check the ability to upgrade Percona Distribution for PostgreSQL from 16 to 17: ```{.bash data-prompt="$"} @@ -304,7 +301,6 @@ Run **all** commands as root or via **sudo**: *Clusters are compatible* ``` - * Upgrade the Percona Distribution for PostgreSQL ```{.bash data-prompt="$"} @@ -319,7 +315,6 @@ Run **all** commands as root or via **sudo**: The `--link` flag creates hard links to the files on the old version cluster so you don’t need to copy data. If you don’t wish to use the `--link` option, make sure that you have enough disk space to store 2 copies of files for both old version and new version clusters. - 5. Start the `postgresql` {{pgversion}} service. ```{.bash data-prompt="$"} @@ -332,10 +327,8 @@ Run **all** commands as root or via **sudo**: $ systemctl status postgresql-{{pgversion}} ``` - 7. After the upgrade, the Optimizer statistics are not transferred to the new cluster. Run the `vaccumdb` command to analyze the new cluster: - * Log in as the postgres user ```{.bash data-prompt="$"} @@ -348,14 +341,12 @@ Run **all** commands as root or via **sudo**: $ /usr/pgsql-{{pgversion}}/bin/vacuumdb --all --analyze-in-stages ``` - 8. Delete Percona Distribution for PostgreSQL 16 configuration files ```{.bash data-prompt="$"} $ ./delete_old_cluster.sh ``` - 9. Delete Percona Distribution old data files ```{.bash data-prompt="$"} diff --git a/docs/release-notes-v17.5.md b/docs/release-notes-v17.5.md new file mode 100644 index 000000000..285ff90d6 --- /dev/null +++ b/docs/release-notes-v17.5.md @@ -0,0 +1,59 @@ +# Percona Distribution for PostgreSQL 17.5.1 ({{date.17_5}}) + +--8<-- "release-notes-intro.md" + +This release of Percona Distribution for PostgreSQL is based on Percona Server for PostgreSQL 17.5.1 - a binary compatible, open source drop in replacement of [PostgreSQL Community 17.5](https://www.postgresql.org/docs/17/release-17-5.html). + +## Release Highlights + +This release fixes [CVE-2025-1094](https://www.postgresql.org/support/security/CVE-2025-1094/), which closed a vulnerability in the `libpq` PostgreSQL client library but introduced a regression related to string handling for non-null terminated strings. The error would be visible based on how a PostgreSQL client implemented this behavior. This regression affects versions 17.3, 16.7, 15.11, 14.16, and 13.19. For this reason, version 17.3 was skipped. + +### A new version of `pg_tde` + +Percona Distribution for PostgreSQL includes the Release Candidate 2 (RC2) of `pg_tde` extension that brings in Transparent Data Encryption. This version of `pg_tde` provides a bunch of improvements, among which is WAL encryption now supporting Vault, automatic WAL internal key generation at server startup, new visibility and verification functions for default principal keys, and more. Learn about these features in the [`pg_tde` release notes :octicons-link-external-16:](https://docs.percona.com/pg-tde/release-notes/rc2.html). + +### Improved security and user experience for Docker images + +* Percona Distribution for PostgreSQL Docker image is now based on Universal Base Image (UBI) version 9, which includes the latest security fixes. This makes the image compliant with the Red Hat certification and ensures the seamless work of containers on Red Hat OpenShift Container Platform. + +* You no longer have to specify the `{{dockertag}}-multi` tag when you run Percona Distribution for PostgreSQL in Docker. Instead, use the `percona/percona-distribution-postgresql:{{dockertag}}`. Docker automatically identifies the architecture of your operating system and pulls the corresponding image. Refer to [Run in Docker](docker.md) for how to get started. + +### PostGIS is included into tarballs + +We have extended Percona Distribution for PostgreSQL tarballs with PostGIS - an open-source extension to handle spacial data. This way you can install and run PostgreSQL as a geospatial database on hosts without a direct access to the Internet. Learn more about [installing from tarballs](tarball.md) and [Spacial data manipulation](solutions/postgis.md). + +### Deprecation of meta packages + +[Meta-packages for Percona Distribution for PostgreSQL](repo-overview.md#repository-contents) are deprecated and will be removed in future releases. + +### Updated Major upgrade topic in documentation + +The [Upgrading Percona Distribution for PostgreSQL from 16 to 17](major-upgrade.md) guide has been updated with revised steps for the [On Debian and Ubuntu using `apt`](major-upgrade.md/#on-debian-and-ubuntu-using-apt) section, improving clarity and reliability of the upgrade process. + +## Supplied third-party extensions + +Review each extension’s release notes for What’s new, improvements, or bug fixes. The following is the list of extensions available in Percona Distribution for PostgreSQL. + +| Extension | Version | Description | +|--------------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------| +| [etcd :octicons-link-external-16:](https://etcd.io/) | 3.5.21 | A distributed, reliable key-value store for setting up high available Patroni clusters | +| [HAProxy :octicons-link-external-16:](http://www.haproxy.org/) | 2.8.15 | A high-availability and load-balancing solution | +| [Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) | 4.0.5 | A HA (High Availability) solution for PostgreSQL | +| [PgAudit :octicons-link-external-16:](https://www.pgaudit.org/) | 17.1 | Provides detailed session or object audit logging via the standard logging facility provided by PostgreSQL | +| [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 roles for maintenance. | +| [pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) | 2.55.0 | A backup and restore solution for PostgreSQL | +| [pgBadger :octicons-link-external-16:](https://github.com/darold/pgbadger) | 13.1 | A fast PostgreSQL Log Analyzer | +| [PgBouncer :octicons-link-external-16:](https://www.pgbouncer.org/) | 1.24.1 | A lightweight connection pooler for PostgreSQL | +| [pg_gather :octicons-link-external-16:](https://github.com/jobinau/pg_gather) | v30 | An SQL script for running the diagnostics of the health of a PostgreSQL cluster | +| [pgpool2 :octicons-link-external-16:](https://git.postgresql.org/gitweb/?p=pgpool2.git;a=summary) | 4.6.0 | A middleware between PostgreSQL server and client for high availability, connection pooling, and load balancing | +| [pg_repack :octicons-link-external-16:](https://github.com/reorg/pg_repack) | 1.5.2 | Rebuilds PostgreSQL database objects | +| [pgvector :octicons-link-external-16:](https://github.com/pgvector/pgvector) | v0.8.0 | A vector similarity search for PostgreSQL | +| [PostGIS :octicons-link-external-16:](https://github.com/postgis/postgis) | 3.3.8 | A spatial extension for PostgreSQL | +| [PostgreSQL Common :octicons-link-external-16:](https://salsa.debian.org/postgresql/postgresql-common) | 277 | PostgreSQL database-cluster manager. Supports multiple PostgreSQL versions and clusters simultaneously | +| [wal2json :octicons-link-external-16:](https://github.com/eulerto/wal2json) | 2.6 | A PostgreSQL logical decoding JSON output plugin | + +For Red Hat Enterprise Linux 8 and compatible derivatives, Percona Distribution for PostgreSQL also includes the supplemental `python3-etcd` 0.4.5 packages, which are used for setting up Patroni clusters. + +Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/17/libpq.html) library. It contains "a set of +library functions that allow client programs to pass queries to the PostgreSQL +backend server and to receive the results of these queries." diff --git a/docs/release-notes.md b/docs/release-notes.md index 787850be7..bfaab6694 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,5 +1,6 @@ -# Percona Distribution for PostgreSQL release notes +# Percona Distribution for PostgreSQL release notes +* [Percona Distribution for PostgreSQL 17.5.1](release-notes-v17.5.md) ({{date.17_5}}) * [Percona Distribution for PostgreSQL 17.4.1](release-notes-v17.4.md) ({{date.17_4}}) * [Percona Distribution for PostgreSQL 17.2.1](release-notes-v17.2.md) ({{date.17_2}}) * [Percona Distribution for PostgreSQL 17.0.1](release-notes-v17.0.md) ({{date.17_0}}) diff --git a/docs/tarball.md b/docs/tarball.md index 22f662807..361bfa2b9 100644 --- a/docs/tarball.md +++ b/docs/tarball.md @@ -44,7 +44,13 @@ The tarballs include the following components: === "Debian and Ubuntu" 1. Uninstall the upstream PostgreSQL package. - 2. Create the user to own the PostgreSQL process. For example, `mypguser`. Run the following command: + 2. Ensure that the `libreadline` is present on the system, as it is **required** for tarballs to work correctly: + + ```{.bash data-prompt="$"} + $ sudo apt install -y libreadline-dev + ``` + + 3. Create the user to own the PostgreSQL process. For example, `mypguser`. Run the following command: ```{.bash data-prompt="$"} $ sudo useradd -m mypguser @@ -58,6 +64,12 @@ The tarballs include the following components: === "RHEL and derivatives" + Ensure that the `libreadline` is present on the system, as it is **required** for tarballs to work correctly: + + ```{.bash data-prompt="$"} + $ sudo yum install -y readline-devel + ``` + Create the user to own the PostgreSQL process. For example, `mypguser`, Run the following command: ```{.bash data-prompt="$"} diff --git a/docs/templates/pdf_cover_page.tpl b/docs/templates/pdf_cover_page.tpl index 3298668b1..c71f69b64 100644 --- a/docs/templates/pdf_cover_page.tpl +++ b/docs/templates/pdf_cover_page.tpl @@ -7,6 +7,6 @@ {% if config.site_description %}

{{ config.site_description }}

{% endif %} -

17.4 (March 27, 2025)

+

17.5.1 (May , 2025)

diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 1608ae74b..5e545da23 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -221,6 +221,7 @@ nav: - troubleshooting.md - uninstalling.md - release-notes.md + - release-notes-v17.5.md - release-notes-v17.4.md - release-notes-v17.2.md - release-notes-v17.0.md diff --git a/mkdocs.yml b/mkdocs.yml index 38b77ba99..00ad630a0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,6 +75,7 @@ nav: - Uninstall: uninstalling.md - Release Notes: - "Release notes index": "release-notes.md" + - release-notes-v17.5.md - release-notes-v17.4.md - release-notes-v17.2.md - release-notes-v17.0.md diff --git a/variables.yml b/variables.yml index 7b8729bba..695892e9e 100644 --- a/variables.yml +++ b/variables.yml @@ -1,15 +1,15 @@ # PG Variables set for HTML output # See also mkdocs.yml plugins.with-pdf.cover_subtitle and output_path -release: 'release-notes-v17.4' -dockertag: '17.4' +release: 'release-notes-v17.5' +dockertag: '17.5' pgversion: '17' -pgsmversion: '2.1.1' -pspgversion: '17.4.1' +pspgversion: '17.5.1' date: + 17_5: 2025-05-28 17_4: 2025-03-27 17_2: 2024-12-26 17_0: 2024-10-03