diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 83327c5c83..87f85b2fab 100644 --- 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 @@ -133,8 +136,9 @@ Enable LDAP Enable plugins/extensions Back up and restore Monitoring (COS) -Upgrade +Refresh (upgrade) Cross-regional async replication Logical replication Development +``` diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md new file mode 100644 index 0000000000..303caf6d76 --- /dev/null +++ b/docs/how-to/refresh/index.md @@ -0,0 +1,43 @@ +# Refresh (upgrade) + +Charmed PostgreSQL supports minor {term}`in-place` {term}`refresh` via the [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command. + +```{admonition} Emergency stop button +:class: attention +Use `juju config appname pause-after-unit-refresh=all` to halt an in-progress refresh +``` + +## Supported refreshes + +**Minor in-place {term}`upgrade`** between stable releases. +E.g. PostgreSQL 16.9 is upgraded to 16.10 + +> See [How to perform a minor upgrade](/how-to/refresh/minor-upgrade) + +**Minor in-place {term}`rollback`** between stable releases. +E.g. An upgrade from PostgreSQL 16.9 -> 16.10 fails, so a rollback is triggered to take all units from 16.10 back to 16.9. + +> See [How to perform a minor rollback](/how-to/refresh/minor-rollback) + + + +Check all available Charmed PostgreSQL 16 versions in [](/reference/releases). + +## Non-supported refreshes +* Minor in-place {term}`downgrade` from PostgreSQL 16.10 to 16.9 +* Major in-place {term}`upgrade` from PostgreSQL 14 to 16 +* Major in-place {term}`downgrade` from PostgreSQL 16 to 14 +* Any refresh involving non-stable versions (e.g. 16/edge) + +The actions listed above must be performed as out of place upgrades. + + + + +```{toctree} +:titlesonly: +:hidden: + +Perform a minor upgrade +Perform a minor rollback +``` \ No newline at end of file diff --git a/docs/how-to/refresh/minor-rollback.md b/docs/how-to/refresh/minor-rollback.md new file mode 100644 index 0000000000..3f3a9e4f81 --- /dev/null +++ b/docs/how-to/refresh/minor-rollback.md @@ -0,0 +1,23 @@ +# 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. + +--- + +## 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). + + + +## 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. + +Then, to resume the rollback, run the `resume-refresh` action on the unit shown by the app status. + + \ No newline at end of file diff --git a/docs/how-to/refresh/minor-upgrade.md b/docs/how-to/refresh/minor-upgrade.md new file mode 100644 index 0000000000..b102e6850b --- /dev/null +++ b/docs/how-to/refresh/minor-upgrade.md @@ -0,0 +1,85 @@ +# Perform a minor upgrade + +A minor {term}`in-place` {term}`upgrade` is a {term}`refresh` from one {term}`workload` version to a higher one, within the same major version (e.g. PostgreSQL 14.12 --> PostgreSQL 14.15) + +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. + +If your upgrade has failed, see [How to perform a minor rollback](/how-to/refresh/minor-rollback) + +```{seealso} + +* [All Charmed PostgreSQL minor versions](/reference/releases) +* [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.** + +We recommend testing the integrity of your backup by performing a test [restore](/how-to/back-up-and-restore/restore-a-backup). + +**Avoid 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 - unless it is necessary for recovery +* Creating or destroying new relations +* Changes in workload configuration +* Upgrading other connected/related/integrated applications simultaneously + +[Contact us](/reference/contacts) if you have questions about performing operations during refresh. +``` + +**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`](https://canonical-charm-refresh.readthedocs-hosted.com/latest/user-experience/actions/#pre-refresh-check) action checks that the application is healthy and ready to refresh (e.g. no other operations are running). + +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: + +```shell +juju refresh postgresql +``` + +It is expected for the Juju agents to enter a temporary `failed` state. + +Units will then be refreshed one by one based on role: +1. `replica` units +2. `sync-standby` +3. `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. + +## 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. + +Then, to resume the upgrade, run the `resume-refresh` action on the unit shown by the app status. + + diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md deleted file mode 100644 index d7743e52f1..0000000000 --- a/docs/how-to/upgrade/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Upgrade - -This charm does not support in-place upgrades for major version changes, and there are currently no minor versions of Charmed PostgreSQL 16 to upgrade or rollback. - -For minor version upgrades on Charmed PostgreSQL 14, see the [version 14 upgrades documentation](https://canonical-charmed-postgresql.readthedocs-hosted.com/en/14/how-to/upgrade/). - -```{note} -We will soon publish a migration guide with instructions on how to change from PostgreSQL 14 to 16. -``` diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md new file mode 100644 index 0000000000..ba9a29c234 --- /dev/null +++ b/docs/reference/glossary.md @@ -0,0 +1,39 @@ +# 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 + +in-place + TODO +``` + + \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index a79f940650..b569bee3d6 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -52,4 +52,5 @@ Troubleshooting Plugins/extensions Alert rules Statuses +Glossary Contacts diff --git a/docs/reference/releases.md b/docs/reference/releases.md index d6d5bf1468..f523f1eeb9 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -1,22 +1,22 @@ -# Releases +--- +relatedlinks: "[Charm risk](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk)" +--- -This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release. +# Releases -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). +Charmed PostgreSQL 16 supports all [features listed in PostgreSQL 14](https://canonical-charmed-postgresql.readthedocs-hosted.com/14/reference/releases/#dependencies-and-supported-features). -To see all releases and commits, check the [Charmed PostgreSQL Releases page on GitHub](https://github.com/canonical/postgresql-operator/releases). +| Release | PostgreSQL version | Minimum Juju version | +|:---:|:---:|:---:| +| [843, 844] | 16.9 | 3.6+ | -## Dependencies and supported features +See all release notes on [GitHub](https://github.com/canonical/postgresql-operator/releases). -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 +## How to refresh (upgrade) -| 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] | +Charmed PostgreSQL supports **minor in-place upgrades**. See [](/how-to/refresh/index) for more information. +[Contact us](/reference/contacts) if you are interested in migrating from PostgreSQL 14 to 16. ## Architecture and base @@ -24,16 +24,11 @@ Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#c If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture. -```{caution} -If you deploy with the `--revision` flag, **you must make sure the revision matches your base and architecture**. - -Check the tables below, or use [`juju info`](https://juju.is/docs/juju/juju-info). -``` - -## Plugins/extensions + -For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/reference/plugins-extensions). + +[843, 844]: https://github.com/canonical/postgresql-operator/releases/tag/v16%2F1.59.0 [check]: https://img.icons8.com/color/20/checkmark--v1.png diff --git a/docs/reference/versions.md b/docs/reference/versions.md index f58b704765..418512874e 100644 --- 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]