From 694aa4e5e5fcae1ad6c5360c64a12c44d1fecfd4 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 17 Jul 2026 17:34:24 +0300 Subject: [PATCH 1/2] PG-2434 - Add Docker upgrade topic This PR mentions the docker upgrade image and instructs the user how to upgrade using this image. Furthermore, major upgrade chapter and docker install chapter will have links to this topic. --- docs/docker/docker-upgrade.md | 35 +++++++++++++++++++++++++++++++++++ docs/docker/docker.md | 3 +++ docs/major-upgrade.md | 3 +++ mkdocs.yml | 1 + 4 files changed, 42 insertions(+) create mode 100644 docs/docker/docker-upgrade.md diff --git a/docs/docker/docker-upgrade.md b/docs/docker/docker-upgrade.md new file mode 100644 index 000000000..895a7cf68 --- /dev/null +++ b/docs/docker/docker-upgrade.md @@ -0,0 +1,35 @@ +# Upgrade Percona Distribution for PostgreSQL + +To upgrade Percona Distribution for PostgreSQL in Docker to a new major version, use the dedicated `percona/percona-distribution-postgresql-upgrade` image. It bundles the server binaries for several consecutive major versions, so `pg_upgrade` can run against your old and new data directories. + +!!! important + Back up your data before you start. The backup tool is out of scope for this document. Use the backup tool of your choice. + +!!! warning + If your cluster uses `pg_tde`, do not follow these steps. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. See [Upgrading Percona Distribution for PostgreSQL](../major-upgrade.md) for details. + +1. Stop the running container: + + ```{.bash data-prompt="$"}t + docker stop container-name + ``` + +2. Pull the upgrade image tag that covers your source and target versions. The tags encode all bundled versions, for example `18.4-17.10-16.14-15.18-14.23-1` bundles Percona PostgreSQL 14 through 18: + + ```{.bash data-prompt="$"} + docker pull percona/percona-distribution-postgresql-upgrade: upgrade-tag + ``` + +3. Run the upgrade container, mount your existing data volume as the old data directory and an empty volume as the new one: + + ```{.bash data-prompt="$"} + TO BE ADDED + ``` + +4. Start a new container on the target version, using `name of new data vol (TBD)` as its data directory: + + ```{.bash data-prompt="$"} + docker run --name container-name \ + -v new-data-volume:/var/lib/postgresql/data \ + -d percona/percona-distribution-postgresql:{{dockertag}} + ``` diff --git a/docs/docker/docker.md b/docs/docker/docker.md index 1cf666ab1..fdb24639b 100644 --- a/docs/docker/docker.md +++ b/docs/docker/docker.md @@ -85,6 +85,9 @@ Or pull the latest image for a major version: docker pull percona/percona-distribution-postgresql:{{pgversion}} ``` +!!! note + To upgrade a containerized Percona Distribution for PostgreSQL instance to a new major version, use the dedicated upgrade image. See [Upgrade Percona Distribution for PostgreSQL using the upgrade image](docker-upgrade.md). + ## 4. Docker image contents The Docker image of Percona Distribution for PostgreSQL includes the following components: diff --git a/docs/major-upgrade.md b/docs/major-upgrade.md index dc9544540..2cf9f3740 100644 --- a/docs/major-upgrade.md +++ b/docs/major-upgrade.md @@ -15,6 +15,9 @@ To ensure a smooth upgrade path, follow these steps: !!! warning When doing a major version upgrade, if your cluster uses `pg_tde`, you **must** use [`pg_tde_upgrade` :octicons-link-external-16:](https://docs.percona.com/pg-tde/command-line-tools/pg-tde-upgrade.html) instead of `pg_upgrade`. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. The server may start successfully but queries against encrypted tables will fail. +!!! note + If you run Percona Distribution for PostgreSQL in Docker, use the dedicated upgrade image instead of the package-manager steps below. See [Upgrade Percona Distribution for PostgreSQL using the upgrade image](docker/docker-upgrade.md). + The in-place upgrade means installing a new version without removing the old version and keeping the data files on the server. !!! admonition "See also" diff --git a/mkdocs.yml b/mkdocs.yml index a4f8b43a4..8759f85f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,7 @@ nav: - From tarballs: tarball.md - Run in Docker: - Overview: docker/docker.md + - Upgrade in Docker: docker/docker-upgrade.md - 'Enable pg_tde for securing data at rest': docker/docker-enable-pg-tde.md - 'Enable stat-monitor for performance statistics': docker/docker-enable-pg-stat-monitor.md - enable-extensions.md From e8c7d6fae9db609432f159f558d3ae6d7246f05b Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 23 Jul 2026 14:21:30 +0300 Subject: [PATCH 2/2] Update based on feedback and proper steps --- docs/docker/docker-enable-pg-stat-monitor.md | 4 + docs/docker/docker-enable-pg-tde.md | 7 +- docs/docker/docker-upgrade.md | 120 ++++++++++++++++--- 3 files changed, 112 insertions(+), 19 deletions(-) diff --git a/docs/docker/docker-enable-pg-stat-monitor.md b/docs/docker/docker-enable-pg-stat-monitor.md index 8812b268e..1421e1ed0 100644 --- a/docs/docker/docker-enable-pg-stat-monitor.md +++ b/docs/docker/docker-enable-pg-stat-monitor.md @@ -96,3 +96,7 @@ For more information on this extension, see [pg_stat_monitor :octicons-link-exte !!! note The `pg_stat_monitor` view is available only for the databases where you enabled it. If you create a new database, make sure to create the view for it to see its statistics data. + +## Next steps + +[Enable Percona Distribution for PostgreSQL components :material-arrow-right:](../enable-extensions.md){.md-button} diff --git a/docs/docker/docker-enable-pg-tde.md b/docs/docker/docker-enable-pg-tde.md index 5b4f3e56e..bc2c3ffac 100644 --- a/docs/docker/docker-enable-pg-tde.md +++ b/docs/docker/docker-enable-pg-tde.md @@ -2,7 +2,8 @@ Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. -For more information, see the [pg_tde documentation :octicons-link-external-16:](https://docs.percona.com/pg-tde/index.html). +!!! note + For more information about how `pg_tde` works, see the [pg_tde documentation :octicons-link-external-16:](https://docs.percona.com/pg-tde/index.html). ## Enable pg_tde {.power-number} @@ -80,3 +81,7 @@ For more information, see the [pg_tde documentation :octicons-link-external-16:] signup_date DATE ) USING tde_heap; ``` + +## Next steps + +[Enable `pg_stat_monitor` for performance statistics :material-arrow-right:](docker-enable-pg-stat-monitor.md){.md-button} diff --git a/docs/docker/docker-upgrade.md b/docs/docker/docker-upgrade.md index 895a7cf68..961a62fa4 100644 --- a/docs/docker/docker-upgrade.md +++ b/docs/docker/docker-upgrade.md @@ -8,28 +8,112 @@ To upgrade Percona Distribution for PostgreSQL in Docker to a new major version, !!! warning If your cluster uses `pg_tde`, do not follow these steps. Using `pg_upgrade` on an encrypted cluster is not supported and will result in data corruption. See [Upgrading Percona Distribution for PostgreSQL](../major-upgrade.md) for details. -1. Stop the running container: +!!! note + If you're upgrading an existing instance rather than following along with the step 1-5 example, skip those steps and start from step 6 with your own running container and data. - ```{.bash data-prompt="$"}t - docker stop container-name - ``` +## 1. Create directories for the old and new clusters { .power-number } -2. Pull the upgrade image tag that covers your source and target versions. The tags encode all bundled versions, for example `18.4-17.10-16.14-15.18-14.23-1` bundles Percona PostgreSQL 14 through 18: +```{.bash data-prompt="$"} +mkdir -p ~/pgupgrade/pg17olddata/postgres +mkdir -p ~/pgupgrade/pg18newdata/postgres +``` - ```{.bash data-prompt="$"} - docker pull percona/percona-distribution-postgresql-upgrade: upgrade-tag - ``` +## 2. Start the PostgreSQL 17 container -3. Run the upgrade container, mount your existing data volume as the old data directory and an empty volume as the new one: +```{.bash data-prompt="$"} +docker run -d + --name pg17 + -e POSTGRES_PASSWORD=password + -v ~/pgupgrade/pg17olddata/postgres:/data/db + percona/percona-distribution-postgresql:17 +``` - ```{.bash data-prompt="$"} - TO BE ADDED - ``` +## 3. Wait until PostgreSQL finishes initialization -4. Start a new container on the target version, using `name of new data vol (TBD)` as its data directory: +```{.bash data-prompt="$"} +docker logs pg17 +``` - ```{.bash data-prompt="$"} - docker run --name container-name \ - -v new-data-volume:/var/lib/postgresql/data \ - -d percona/percona-distribution-postgresql:{{dockertag}} - ``` +## 4. Connect to PostgreSQL + +```{.bash data-prompt="$"} +docker exec -it pg17 psql -U postgres +``` + +## 5. Create a test database and add data + +```sql +CREATE DATABASE testdb; +\c testdb +CREATE TABLE t1(a int); +INSERT INTO t1 VALUES (100); +``` + +## 6. Stop the PostgreSQL 17 container + +```{.bash data-prompt="$"} +docker stop pg17 +``` + +## 7. Pull the upgrade image + +```{.bash data-prompt="$"} +docker pull percona/percona-distribution-postgresql-upgrade:18.4-17.10-16.14-15.18-14.23-1 +``` + +The tag encodes all bundled versions; here it covers PostgreSQL 14 through 18. + +## 8. Run the upgrade + +```{.bash data-prompt="$"} +docker run --rm + --name ppg_upgrade_17_18 + -e OLD_VERSION=17 + -e NEW_VERSION=18 + -e OLD_DATABASE_NAME=postgres + -e NEW_DATABASE_NAME=postgres + -v ~/pgupgrade/pg17olddata:/pgolddata + -v ~/pgupgrade/pg18newdata:/pgnewdata + percona/percona-distribution-postgresql-upgrade:18.4-17.10-16.14-15.18-14.23-1 +``` + +Where: + +* `OLD_VERSION` / `NEW_VERSION` are the major versions you're upgrading from and to +* `OLD_DATABASE_NAME` / `NEW_DATABASE_NAME` are the database directory names under your old and new data mounts +* the volumes mount the parent directories (`pg17olddata`, `pg18newdata`), **not** the `postgres` subdirectory directly + +## 9. Start PostgreSQL 18 using the upgraded data directory + +```{.bash data-prompt="$"} +docker run -d + --name pg18 + -e POSTGRES_PASSWORD=password + -v ~/pgupgrade/pg18newdata/postgres:/data/db + percona/percona-distribution-postgresql:18 +``` + +## 10. Verify PostgreSQL 18 starts successfully + +```{.bash data-prompt="$"} +docker logs -f pg18 +``` + +## 11. Connect to the upgraded cluster + +```{.bash data-prompt="$"} +docker exec -it pg18 psql -U postgres testdb +``` + +## 12. Verify the upgraded data + +```sql +SELECT version(); +SELECT * FROM t1; +``` + +Once you've confirmed the upgraded container is healthy, you can remove `pg17olddata`. + +## Next steps + +[Enable `pg_tde` for securing data at rest :material-arrow-right:](docker-enable-pg-tde.md){.md-button}