canonical · a-velasco · Aug 8, 2025 · Aug 8, 2025 · Aug 11, 2025 · Aug 11, 2025
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -43,8 +43,10 @@ Other deployment scenarios and configurations:
 * [Enable tracing] with Tempo
 * [Enable profiling] with Parca
 
-## Upgrades
-* [How to upgrade]
+## Refresh (upgrade)
+* [How to refresh]
+    * [Perform a minor upgrade]
+    * [Perform a minor rollback]
 
 ## Cross-regional (cluster-cluster) async replication
 
@@ -99,7 +101,9 @@ This section is for charm developers looking to support PostgreSQL integrations
 [Enable tracing]: /how-to/monitoring-cos/enable-tracing
 [Enable profiling]: /how-to/monitoring-cos/enable-profiling
 
-[How to upgrade]: /how-to/upgrade/index
+[How to upgrade]: /how-to/refresh/index
+[Perform a minor upgrade]: /how-to/refresh/minor-upgrade
+[Perform a minor rollback]: /how-to/refresh/minor-rollback
 
 [Cross-regional async replication]: /how-to/cross-regional-async-replication/index
 [Set up clusters]: /how-to/cross-regional-async-replication/set-up-clusters
@@ -119,7 +123,6 @@ This section is for charm developers looking to support PostgreSQL integrations
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
-:glob:
 :hidden:
 
 Deploy <deploy/index>
@@ -133,8 +136,9 @@ Enable LDAP <enable-ldap>
 Enable plugins/extensions <enable-plugins-extensions/index>
 Back up and restore <back-up-and-restore/index>
 Monitoring (COS) <monitoring-cos/index>
-Upgrade <upgrade/index>
+Refresh (upgrade) <refresh/index>
 Cross-regional async replication <cross-regional-async-replication/index>
 Logical replication <logical-replication/index>
 Development <development/index>
+```
 
diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md
@@ -0,0 +1,34 @@
+# Refresh (upgrade)
+
+A charm **refresh** is any change to the version of a charm, and/or its {term}`workload`. 
+
+Charmed PostgreSQL supports minor in-place {term}`upgrades <upgrade>` via the [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command.
+
+## Supported refresh types
+
+This charm **can only be upgraded to a higher version**. It cannot be {term}`downgraded <downgrade>` to a lower version.
+
+The charm version can only be lowered in the case of an ongoing refresh that needs to {term}`roll back <rollback>` to its {term}`original version` due to a failure.
+
+```{seealso}
+* [How to perform a minor upgrade](/how-to/refresh/minor-upgrade)
+* [How to perform a minor rollback](/how-to/refresh/minor-rollback)
+```
+
+## Supported versions
+
+This charm **only supports minor version upgrades**, e.g. 16.9 --> 16.10.
+
+[Contact us](/reference/contacts) if you want to migrate from Charmed PostgreSQL 14 to 16
+
+```{seealso}
+* [Charmed PostgreSQL 16 versions](/reference/releases)
+```
+
+```{toctree}
+:titlesonly:
+:hidden:
+
+Perform a minor upgrade <minor-upgrade>
+Perform a minor rollback <minor-rollback>
+```
diff --git a/docs/how-to/refresh/minor-rollback.md b/docs/how-to/refresh/minor-rollback.md
@@ -0,0 +1,29 @@
+# Perform a minor rollback
+
+After running `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the process will be halted and enter a failure state.
+
+Even if the underlying PostgreSQL cluster continues to work, it’s important to roll back the charm to the {term}`original version` so that an update can be attempted after further inspection of the failure.
+
+```{attention}
+Only trigger a rollback if the refresh has explicitly failed and cannot continue. Do not initiate a rollback while the refresh process is still running.
+
+<!--TODO: examples-->
+```
+
+---
+
+## Initiate rollback
+
+Perform a rollback with the command obtained from the [pre-refresh check](pre-refresh check) that was performed before initiating the refresh process. You can also find it in the [Juju logs](https://documentation.ubuntu.com/juju/3.6/howto/manage-logs/#view-the-log-files).
+
+<!--TODO: example-->
+
+## Resume rollback
+
+If the [`pause_after_unit_refresh`](https://charmhub.io/postgresql/configurations?channel=16/edge#pause_after_unit_refresh) config option on your PostgreSQL application is set to `first` (default) or `all`, you'll need to monitor and manually resume the refresh when one or more units have finished refreshing individually.
+
+When the refresh pauses and all units are in an idle state, check that they are healthy. <!-- TODO: how? -->
+
+Then, to resume the rollback, run the `resume-refresh` action on the unit shown by the app status.
+
+<!-->
diff --git a/docs/how-to/refresh/minor-upgrade.md b/docs/how-to/refresh/minor-upgrade.md
@@ -0,0 +1,93 @@
+# Perform a minor upgrade
+
+A minor upgrade is a {term}`refresh` from one workload version to a higher one within the same major version (e.g. PostgreSQL 14.12 --> PostgreSQL 14.15)
+
+The refresh process boils down to:
+* Running a pre-refresh check to ensure your deployment can undergo a safe upgrade process
+* Running the refresh command to initiate the process
+* Monitoring and following UI instructions
+
+Once in the refresh is in progress, the UI will clearly indicate what is happening to each unit, and what actions are required from the user to continue the process or roll back in case of a problem.
+
+```{seealso}
+* [How to perform a minor rollback](/how-to/refresh/minor-rollback)
+* [All Charmed PostgreSQL minor versions](/reference/releases)
+* [](/how-to/back-up-and-restore/create-a-backup)
+* [Developer docs for charm-refresh](https://canonical-charm-refresh.readthedocs-hosted.com/latest/)
+    * [`pause_after_unit_refresh` documentation](https://canonical-charm-refresh.readthedocs-hosted.com/latest/user-experience/config/#pause-after-unit-refresh)
+```
+
+
+## Precautions
+
+Below are some strongly recommended precautions before refreshing to ensure minimal service disruption:
+
+**Make sure to have a [backup](/how-to/back-up-and-restore/create-a-backup) of your data.**
+
+**Do not perform operations that modify your cluster while refreshing.**
+
+Concurrency with other operations is not supported, and it can lead the cluster to inconsistent states.
+
+```{dropdown} Examples
+Avoid operations such as (but not limited to) the following:
+
+* Adding or removing units
+* Creating or destroying new relations
+* Changes in workload configuration
+* Upgrading other connected/related/integrated applications simultaneously
+```
+
+**Integrate with [Charmed PgBouncer](https://charmhub.io/pgbouncer).** 
+
+This will ensure minimal service disruption, if any.
+
+(pre-refresh-check)=
+## Pre-refresh check
+
+The `pre-refresh-check` action checks that a refresh is possible and will switch the primary, if necessary, for a safe upgrade process.
+
+This check happens automatically when you run `juju refresh`, but we recommend running it manually before scheduling a maintenance window for the refresh operation.
+
+Run a pre-refresh check against the leader unit:
+
+```shell
+juju run postgresql/leader pre-refresh-check
+```
+
+Do not refresh if there are errors in the output.
+
+```{tip}
+Copy down the rollback command from the action output in case a rollback is needed later.
+```
+
+## Initiate refresh
+
+The following command will refresh the charm to the latest version in the channel you originally deployed your application from, e.g. `16/stable`:
+
+```shell
+juju refresh postgresql
+```
+
+To refresh your charm to the latest version of a specific channel or track, use the `--channel` flag. For example:
+
+```shell
+juju refresh postgresql --channel 16/edge
+```
+
+Units will be refreshed one by one based on role: first the `replica` units, then `sync-standby`, and lastly the `leader` unit. 
+
+If there are any version incompatibilities in charm revisions, dependencies, or any other unexpected failure in the upgrade process, the process will halt and enter a failure state.
+
+```{attention}
+Only trigger a rollback if the refresh has explicitly failed and cannot continue. <!--TODO: examples + clarify if you can rollback when refresh is healthy but paused waiting for resume-refresh -->
+```
+
+## Resume refresh
+
+If the [`pause_after_unit_refresh`](https://charmhub.io/postgresql/configurations?channel=16/edge#pause_after_unit_refresh) config option on your PostgreSQL application is set to `first` (default) or `all`, you'll need to monitor and manually resume the refresh when one or more units have finished refreshing individually.
+
+When the refresh pauses and all units are in an idle state, check that they are healthy. <!-- TODO: how? -->
+
+Then, to resume the upgrade, run the `resume-refresh` action on the unit shown by the app status.
+
+<!--TODO: example -->
diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -0,0 +1,31 @@
+# Glossary
+
+Common terminology in the context of Charmed PostgreSQL.
+
+## Upgrades (refresh)
+
+This is a simplified summary of refresh terminology. 
+
+For a more detailed glossary, see the [charm refresh  developer documentation](https://canonical-charm-refresh.readthedocs-hosted.com/latest/glossary/). 
+
+```{glossary}
+refresh
+    `juju refresh` to a different workload and/or charm version.
+
+    Note: *rollback*, *upgrade*, and *downgrade* are specific types of refresh.
+
+upgrade
+    `juju refresh` to a higher workload and/or charm version.
+
+downgrade
+    `juju refresh` to a lower workload and/or charm version.
+
+rollback
+    `juju refresh` to the original workload and charm version while a refresh is in progress.
+
+workload
+    A software component that the charm operates. E.g. PostgreSQL.
+
+original version
+    Workload and/or charm version of all units before initiating a refresh process
+```
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -52,4 +52,5 @@ Troubleshooting <troubleshooting/index>
 Plugins/extensions <plugins-extensions>
 Alert rules <alert-rules>
 Statuses <statuses>
+Glossary <glossary>
 Contacts <contacts>
diff --git a/docs/reference/releases.md b/docs/reference/releases.md
@@ -1,23 +1,15 @@
 # Releases
 
-This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release.
+Charmed PostgreSQL 16 supports all [features listed in PostgreSQL 14](https://canonical-charmed-postgresql.readthedocs-hosted.com/14/reference/releases/#dependencies-and-supported-features).
+
+| Release | PostgreSQL version | Minimum Juju version | 
+|:---:|:---:|:---:|
+| [843, 844] | 16.9  | 3.6+  |
 
 To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk).
 
 To see all releases and commits, check the [Charmed PostgreSQL Releases page on GitHub](https://github.com/canonical/postgresql-operator/releases).
 
-## Dependencies and supported features
-
-For a given release, this table shows:
-* The PostgreSQL version packaged inside.
-* The minimum Juju 3 version required to reliably operate **all** features of the release
-* Support for specific features
-
-| Release | PostgreSQL version | Minimum Juju version | [TLS encryption](/how-to/enable-tls) | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/upgrade/index) | [Cross-regional async replication](/how-to/cross-regional-async-replication/index) | [Point-in-time recovery](/how-to/back-up-and-restore/restore-a-backup) |
-|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-|   |   |   | ![check] | ![check] | ![check] | ![check] | ![check] |
-
-
 ## Architecture and base
 
 Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#charm-revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions.
@@ -34,6 +26,8 @@ Check the tables below, or use [`juju info`](https://juju.is/docs/juju/juju-info
 
 For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/reference/plugins-extensions).
 
+<!-- LINKS -->
+[843, 844]: https://github.com/canonical/postgresql-operator/releases/tag/v16%2F1.59.0
 
 <!--BADGES-->
 [check]: https://img.icons8.com/color/20/checkmark--v1.png

diff --git a/docs/reference/versions.md b/docs/reference/versions.md
@@ -28,7 +28,7 @@ PostgreSQL 16 is shipped in track `16` and is available for testing in the chann
   * All replicas are now [synchronous units]
   * Switchover the primary unit via `promote-to-primary scope=unit`
   * Raft re-init helper: `promote-to-primary scope=unit force=yes`
-* [Juju user secrets](https://documentation.ubuntu.com/juju/latest/reference/secret/index.html#user) for charm [internal passwords]
+* [Juju user secrets](https://documentation.ubuntu.com/juju/latest/reference/secret/index.html#user-secret) for charm [internal passwords]
 * [Timescale Community Edition]
 * [Extended COS integration]
   * [Profiling via Parca]