PG-2434 - Add Docker upgrade topic

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}

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}

docs/docker/docker-upgrade.md

@@ -0,0 +1,119 @@
+# 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.
+
+!!! 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.
+
+## 1. Create directories for the old and new clusters { .power-number }
+
+```{.bash data-prompt="$"}
+mkdir -p ~/pgupgrade/pg17olddata/postgres
+mkdir -p ~/pgupgrade/pg18newdata/postgres
+```
+
+## 2. Start the PostgreSQL 17 container
+
+```{.bash data-prompt="$"}
+docker run -d
+  --name pg17
+  -e POSTGRES_PASSWORD=password
+  -v ~/pgupgrade/pg17olddata/postgres:/data/db
+  percona/percona-distribution-postgresql:17
+```
+
+## 3. Wait until PostgreSQL finishes initialization
+
+```{.bash data-prompt="$"}
+docker logs pg17
+```
+
+## 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}

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:

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"

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