diff --git a/docs/conf.py b/docs/conf.py index 3f6d37dec2..e057244cf2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -335,5 +335,6 @@ # Add configuration for intersphinx mapping intersphinx_mapping = { - 'starter-pack': ('https://canonical-example-product-documentation.readthedocs-hosted.com/en/latest', None) + 'postgresql-14': ('https://canonical-charmed-postgresql.readthedocs-hosted.com/14/', None) } +myst_url_schemes = ["http", "https", ] \ No newline at end of file diff --git a/docs/explanation/charm-versions/index.md b/docs/explanation/charm-versions/index.md new file mode 100644 index 0000000000..0124587de6 --- /dev/null +++ b/docs/explanation/charm-versions/index.md @@ -0,0 +1,44 @@ +# PostgreSQL major versions + +Charmed PostgreSQL is available in multiple versions to support different deployment requirements and lifecycle stages. It is shipped in the following [tracks](https://documentation.ubuntu.com/juju/3.6/reference/charm/#track): + + +| Charm name | Charmhub channel | Type | Status | +| ----------------------- | ---------------- | ------ | ----------------------------------------------------------------- | +| PostgreSQL 16 | `16/stable` | modern | ![check] Latest version - new features are released here | +| PostgreSQL 14 | `14/stable` | modern | ![check] In maintenance mode - bug fixes and security updates only | +| Legacy PostgreSQL charm | `latest/stable` | legacy | ![cross] Deprecated | + +## Legacy vs. modern + +There are two [generations](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) of charms stored under the same charm name `postgresql`. In these docs, we refer to them as "legacy" and "modern". + +Legacy charm (deprecated) +: Also known as a [Reactive charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm). Found in the Charmhub channel `latest/stable`. +: Provided `db` and `db-admin` endpoints for the `pgsql` interface. + +Modern charm +: Also known as an [Ops charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm). Found in the Charmhub channels `14/stable` and `16/stable`. +: `14/stable` provides legacy endpoints and new `database` endpoint for the `postgresql_client` interface. +: `16/stable` **does not** provide legacy endpoints - only the new `database` `database` endpoint for the `postgresql_client` interface. + +```{seealso} +* [](/explanation/charm-versions/legacy-charm) +* [](/explanation/charm-versions/modern-charm) +* [](/explanation/interfaces-and-endpoints) +``` + + + +[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303 +[check]: https://img.icons8.com/color/20/checkmark--v1.png + +```{toctree} +:titlesonly: +:maxdepth: 2 +:glob: +:hidden: + +Legacy charm +Modern charm +``` \ No newline at end of file diff --git a/docs/explanation/charm-versions/legacy-charm.md b/docs/explanation/charm-versions/legacy-charm.md new file mode 100644 index 0000000000..17c758e882 --- /dev/null +++ b/docs/explanation/charm-versions/legacy-charm.md @@ -0,0 +1,18 @@ +# Legacy PostgreSQL charm + +The legacy PostgreSQL charm is a [Reactive charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) in the **now deprecated** Charmhub channel `latest/stable`. + +The PostgreSQL 16 charm does not support the same endpoints as the legacy charm. To migrate from legacy to PostgreSQL 16, you must implement the modern `database` endpoint for the `postgresql_client` interface on your charm. + +To read more about implementing compatible endpoints, see: [](/how-to/development/integrate-with-your-charm) + +To read more about the legacy charm see the {doc}`PostgreSQL 14 documentation `. + +## How to report issues and contact authors + +The legacy charm (from `latest/stable`) is stored on [Launchpad](https://git.launchpad.net/postgresql-charm/). Report legacy charm issues [here](https://bugs.launchpad.net/postgresql-charm). + +The modern charms are stored on GitHub: [PostgreSQL 14 branch](https://github.com/canonical/postgresql-operator/tree/main) and [PostgreSQL 16 branch](https://github.com/canonical/postgresql-operator/tree/16/edge) . Report modern charm issues [here](https://github.com/canonical/postgresql-operator/issues/new/choose). + +Do you have questions? [Contact us](/reference/contacts)! + diff --git a/docs/explanation/charm-versions/modern-charm.md b/docs/explanation/charm-versions/modern-charm.md new file mode 100644 index 0000000000..83acd1b9e9 --- /dev/null +++ b/docs/explanation/charm-versions/modern-charm.md @@ -0,0 +1,109 @@ +# Modern PostgreSQL charm + +Modern PostgreSQL charms are [Ops charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm) released in the Charmhub channels `14/` and `16/`. + +Both modern charms provide the `database` endpoint for the `postgresql_client` interface. + +PostgreSQL 14 (track `14/`) additionally provides `db` and `db-admin` endpoints for the legacy `pgsql` interface, and supports migration from the legacy charm. + +PostgreSQL 16 (track `16/`) does not provide legacy endpoints. + +```{note} +You are currently viewing the documentation for **Charmed PostgreSQL 16**. + +To switch between versions, use the small rectangular menu at the bottom right corner of the page. +``` + +## PostgreSQL 16 + +**Latest stable version** with active feature development. + +* **Base:** Ubuntu 24.04 LTS (Noble) +* **Supported architectures:** `amd64`, `arm64` +* **Channel:** `16/stable` (latest development available for testing in `16/edge`) +* **Juju version:** Requires Juju 3.6+ LTS +* **Support status:** ![check] Active development and full support + +### New features + +* [**Juju spaces**](/how-to/deploy/juju-spaces) - Enhanced networking capabilities for complex deployment scenarios +* [**Juju user secrets**](https://documentation.ubuntu.com/juju/latest/reference/secret/index.html#user-secret) - Secure management of the charm's [internal passwords](/how-to/manage-passwords) +* **Improved** [**security hardening**](/explanation/security/index) - Enhanced security posture and best practices +* **TLS v4 library migration** + * New endpoints `client-certificates` and `peer-certificates` + * Endpoint `peer-interfaces` uses TLS by default + * See all endpoints on [Charmhub](https://charmhub.io/postgresql/integrations?channel=16/stable) +* [**Timescale Community Edition**](/how-to/enable-plugins-extensions/enable-timescaledb) replaces Timescale Apache 2 +* **Improved** [**built-in roles**](/explanation/roles) - Enhanced role-based access control system +* **New** **refresh process** for in-place upgrades + +### Deprecated or removed + +Important changes to keep in mind when migrating from 14 to 16: + +* **Legacy interface `psql`** - Endpoints `db` and `db-admin` are no longer supported + * See [](/explanation/interfaces-and-endpoints) for current supported interfaces +* **Support for Juju < `v3.6` removed** + * Charmed PostgreSQL 16 requires Juju `3.6+ LTS` due to [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html) support +* **Juju actions `get-password` and `set-password` removed** + * Replaced by [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html) for enhanced security +* **[Timescale Apache 2 edition](https://docs.timescale.com/about/latest/timescaledb-editions/) replaced** + * Now uses [Timescale Community edition](https://docs.timescale.com/about/latest/timescaledb-editions/) +* **Charm action `set-tls-private-key` removed** + * Will be re-introduced as Juju User Secrets in future releases +* **Charm actions renamed for consistency:** + * `pre-upgrade-check` → `pre-refresh-check` + * `resume-upgrade` → `resume-refresh` + * Changes align with `juju refresh` terminology +* **Charm endpoint `certificates` split into separate endpoints:** + * `client-certificates` - For client certificate management + * `peer-certificates` - For peer-to-peer certificate management + +For detailed information about all PostgreSQL 16 releases, see the [Releases page](/reference/releases). + +## PostgreSQL 14 + +**Maintenance mode** with bug fixes and security updates only. + +* **Base:** Ubuntu 22.04 LTS (Jammy) +* **Supported architectures:** `amd64`, `arm64` +* **Channel:** `14/stable` +* **Juju version:** Partially compatible with older Juju versions down to 2.9 +* **Support status:** 🔧 Bug fixes and security updates only + +### Features + +* [**Deployment on multiple cloud services**](/how-to/deploy/index), including Sunbeam, MAAS, AWS, GCE, and Azure +* [**Juju storage**](/how-to/deploy/juju-storage) - Flexible storage configuration options +* [**Back up and restore**](/how-to/back-up-and-restore/index), including point-in-time recovery +* [**COS integration**](/how-to/monitoring-cos/index) - Enable observability tools like Grafana, Loki, Tempo, and Parca +* [**TLS integration**](/how-to/enable-tls) +* [**LDAP integration**](/how-to/enable-ldap) - Centralised authentication for PostgreSQL clusters +* [**`amd64` and `arm64`architecture** support](/reference/system-requirements) + +For detailed information about all PostgreSQL 14 releases, see the {doc}`PostgreSQL 14 Releases page ` + +## Choosing a version + +| Version | Support Status | Base | Juju Version | Key Features | +|---------|----------------|------|--------------|-------------| +| **PostgreSQL 16** | ![check] Active development | Ubuntu 24.04 LTS | 3.6+ LTS | Latest PostgreSQL and Juju features, enhanced security | +| **PostgreSQL 14** | 🔧 Maintenance mode | Ubuntu 22.04 LTS | 2.9+ | Core database features, stable platform | +| **Legacy** | ![cross] Deprecated | Older base | Legacy versions | Not recommended | + +* **For new deployments**: Use **PostgreSQL 16** for the latest features and long-term support +* **For existing PostgreSQL 14 deployments**: Continue using PostgreSQL 14 or plan migration to 16 +* **For legacy charm users**: Migrate to PostgreSQL 14 as soon as possible + + + +[PostgreSQL 16]: https://charmhub.io/postgresql?channel=16/beta +[PostgreSQL 14]: https://charmhub.io/postgresql?channel=14/stable +[Legacy PostgreSQL charm]: https://charmhub.io/postgresql?channel=latest/stable + +[Version 16 Release Notes]: /reference/version-16-release-notes +[release notes]: /reference/releases +[legacy charm explanation page]: /explanation/charm-versions/legacy-charm + +[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303 +[check]: https://img.icons8.com/color/20/checkmark--v1.png \ No newline at end of file diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 1ac5a2e918..948d6b26c7 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -9,7 +9,7 @@ Additional context about key concepts behind the PostgreSQL charm, including des Architecture Interfaces and endpoints -Legacy charm +Charm versions ``` ## Operational concepts diff --git a/docs/explanation/interfaces-and-endpoints.md b/docs/explanation/interfaces-and-endpoints.md index 79347bf6b7..bbf942d81e 100644 --- a/docs/explanation/interfaces-and-endpoints.md +++ b/docs/explanation/interfaces-and-endpoints.md @@ -39,7 +39,7 @@ Find all details about default and extra DB user roles in "[Charm Users explanat ```{note} Legacy relations are deprecated and will be discontinued on future releases. Their usage should be avoided. -Check the legacy interfaces implementation limitations in [](/explanation/legacy-charm)" +Check the legacy interfaces implementation limitations in [](/explanation/charm-versions/legacy-charm)" ``` ### Legacy `pgsql` interface (`db` and `db-admin` endpoints): diff --git a/docs/explanation/legacy-charm.md b/docs/explanation/legacy-charm.md deleted file mode 100644 index 4821d82937..0000000000 --- a/docs/explanation/legacy-charm.md +++ /dev/null @@ -1,105 +0,0 @@ -# Legacy charm - -There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql`: - -1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) charm in the channel `latest/stable` (called `legacy`) -2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm) charm in the channel `14/stable` (called `modern`) - -The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](/explanation/interfaces-and-endpoints). - -```{note} -Choose one endpoint to use, rather than relating both simultaneously. -``` - - - -## The default track "latest" vs "14" - -The [default track](https://docs.openstack.org/charm-guide/yoga/project/charm-delivery.html) has been switched from the `latest` to `14`. It is [to ensure](https://discourse.charmhub.io/t/request-switch-default-track-from-latest-to-14-for-postgresql-k8s-charms/10314) all new deployments use a modern codebase. We strongly advise against using the latest track due to its implicit nature. In doing so, a future charm upgrade may result in a PostgreSQL version incompatible with an integrated application. Track 14 guarantees PostgreSQL 14 deployment only. The track `latest` will be closed after all applications migrated from Reactive to Ops-based charm. - -## How to migrate from "legacy" to "modern" charm - -The "modern" charm provides temporary support for the legacy interfaces: - -* **quick try**: relate the current application with new charm using endpoint `db` (set the channel to `14/stable`). No extra changes necessary: - -```text - postgresql: - charm: postgresql - channel: 14/stable -``` - -* **proper migration**: migrate the application to the new interface "[postgresql_client](https://github.com/canonical/charm-relation-interfaces)". The application will connect PostgreSQL using "[data_interfaces](https://charmhub.io/data-platform-libs/libraries/data_interfaces)" library from "[data-platform-libs](https://github.com/canonical/data-platform-libs/)" via endpoint `database`. - - -```{warning} -**In-place upgrades are not supported for this case.** - -Reactive charms cannot be upgraded to an operator-framework-based version. To move database data, the new DB application must be launched nearby, and data should be copied from "legacy" application to the "modern" one. - -Please [contact us](/reference/contacts) if you need migration instructions. -``` - -## How to deploy old "legacy" PostgreSQL charm - -Deploy the charm using the channel `latest/stable`: - -```text - postgresql: - charm: postgresql - channel: latest/stable -``` - -```{caution} -Remove the charm store prefix `cs:` from the bundle. - -Otherwise, the modern charm will be chosen by Juju (due to the default track pointing to `14/stable` and not `latest/stable`). - -A common error message is: `cannot deploy application "postgresql": unknown option "..."`. -``` - -## Config options supported by modern charm - -The legacy charm config options were not moved to the modern charm due to no need. The modern charm applies the best possible configuration automatically. - -Feel free to [contact us](/reference/contacts) about the DB tuning/config options. - -## Extensions supported by modern charm - -The legacy charm provided plugins/extensions enabling through the relation (interface `pgsql`). It is NOT supported by the modern charm (neither `pgsql` nor `postgresql_client` interfaces). Please enable the necessary extensions using appropriate `plugin_*_enable` [config option](https://charmhub.io/postgresql/configure) of the modern charm. After enabling the modern charm, it will provide plugins support for both `pgsql` and `postgresql_client` interfaces. - -Please find the list of supported PostgreSQL [Extensions](/reference/plugins-extensions) by modern charm. - -Feel free to [contact us](/reference/contacts) with a list of required extensions. - -## Roles supported by modern charm - -In the legacy charm, the user could request roles by setting the `roles` field to a comma separated list of desired roles. It is NOT supported by the modern charm implementation of the legacy `pgsql` interface. The same functionality is provided via the modern `postgresql_client` using "[extra-user-roles](/explanation/users)". - -For more information about migrating the new interface, see [this guide](/how-to/development/integrate-with-your-charm). - -## Supported PostgreSQL versions by modern charm - -At the moment, the modern charms support PostgreSQL 14 (based on Jammy/22.04 series) only. - -Please [contact us](/reference/contacts) if you need different versions/series. - -## Supported architectures - -Currently, the charm supports architecture `amd64` (all revisions) and `arm64` (from revision 396+). - -See the technical details in [Supported architectures](/reference/system-requirements). - -## Workload artifacts - -The legacy charm used to deploy PostgreSQL from APT/Debian packages, -while the modern charm installs and operates PostgreSQL snap "[charmed-postgresql](https://snapcraft.io/charmed-postgresql)". Check more details in [the modern charm architecture](/explanation/architecture). - -## How to report issues and contact authors - -The "legacy charm" (from `latest/stable`) is stored on [Launchpad](https://git.launchpad.net/postgresql-charm/), here is the link to report all [legacy charm issues](https://bugs.launchpad.net/postgresql-charm). - -The "modern charm" (from `14/stable`) is stored on [GitHub](https://github.com/canonical/postgresql-operator), here is the link to report [modern charm issues](https://github.com/canonical/postgresql-operator/issues/new/choose). - -Do you have questions? [Contact us](/reference/contacts)! - diff --git a/docs/how-to/deploy/juju-storage.md b/docs/how-to/deploy/juju-storage.md index 0121190f9c..5d9dd0a7a5 100644 --- a/docs/how-to/deploy/juju-storage.md +++ b/docs/how-to/deploy/juju-storage.md @@ -4,7 +4,7 @@ Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju [Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/stable) supports multiple storage types: `archive`, `data`, `logs` and `temp`. -The [legacy PostgreSQL charm](/explanation/legacy-charm) in track [`latest`](https://charmhub.io/postgresql?channel=latest/stable) does **not** support the Juju storage abstraction. +The [legacy PostgreSQL charm](/explanation/charm-versions/legacy-charm) in track [`latest`](https://charmhub.io/postgresql?channel=latest/stable)" does **not** support the Juju storage abstraction. ## Check Juju storage details diff --git a/docs/how-to/development/integrate-with-your-charm.md b/docs/how-to/development/integrate-with-your-charm.md index f13b0b3d85..5a4b67fcf0 100644 --- a/docs/how-to/development/integrate-with-your-charm.md +++ b/docs/how-to/development/integrate-with-your-charm.md @@ -2,15 +2,15 @@ Charmed PostgreSQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with PostgreSQL. +(check-supported-interfaces)= ## Check supported interfaces First, we recommend that you check [the supported interfaces](/explanation/interfaces-and-endpoints) of the current charm. You have the option to use modern (preferred) or legacy interfaces. Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs).** -Legacy charm details are described [here](/explanation/legacy-charm). +Legacy charm details are described [here](/explanation/charm-versions/legacy-charm). ## Integrate your charm with PostgreSQL -> See also: [Juju documentation | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/) **For a detailed tutorial** about integrating your charm with the PostgreSQL charm, refer to [Juju | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql). @@ -19,12 +19,18 @@ Legacy charm details are described [here](/explanation/legacy-charm). * [juju-sdk-tutorial-k8s](https://github.com/canonical/juju-sdk-tutorial-k8s/tree/04_integrate_with_psql) - the branch `04_integrate_with_psql` describes integration with Charmed PostgreSQL K8s * [How to migrate Nextcloud to new PostgreSQL (vm-charms)](https://discourse.charmhub.io/t/nextcloud-postgresql-how-to-migrate-nextcloud-to-new-postgresql-vm-charms/10969) guide +```{seealso} +[Juju documentation | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/) +``` + ## Troubleshooting & testing + * To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm) * To troubleshoot PostgreSQL, check the [Troubleshooting](/reference/troubleshooting/index) reference * To test PostgreSQL and other charms, check the [Testing](/reference/software-testing) reference ## FAQ + **Does the requirer need to set anything in relation data?** >It depends on the interface. Check the `postgresql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md). diff --git a/docs/how-to/development/migrate-data-via-backup-restore.md b/docs/how-to/development/migrate-data-via-backup-restore.md index 9b73faa7cb..f4e5277133 100644 --- a/docs/how-to/development/migrate-data-via-backup-restore.md +++ b/docs/how-to/development/migrate-data-via-backup-restore.md @@ -1,6 +1,6 @@ # Migrate database data using ‘backup/restore’ -This is a guide for migrating data from modern charms. To migrate [legacy charms](/explanation/legacy-charm) data, refer to the guide [Migrate data via pg_dump](/how-to/development/migrate-data-via-pg-dump). +This is a guide for migrating data from modern charms. To migrate [legacy charms](/explanation/charm-versions/legacy-charm) data, refer to the guide [Migrate data via pg_dump](/how-to/development/migrate-data-via-pg-dump). This Charmed PostgreSQL operator is able to restore its own[backups](/how-to/back-up-and-restore/restore-a-backup) stored on [S3-compatible storage](/how-to/back-up-and-restore/configure-s3-aws). The same restore approach is applicable to restore [foreign backups](/how-to/back-up-and-restore/migrate-a-cluster) made by different Charmed PostgreSQL installation or even another PostgreSQL charm. The backup have to be created manually using [pgBackRest](https://pgbackrest.org/)! @@ -11,7 +11,7 @@ Always test a migration in a test environment before performing it in production ``` ## Prerequisites -* **Check [your application compatibility](/explanation/legacy-charm)** with Charmed PostgreSQL VM before migrating production data from legacy charm +* **Check [your application compatibility](/explanation/charm-versions/index)** with Charmed PostgreSQL VM before migrating production data from legacy charm * Make sure **PostgreSQL versions are identical** before the migration ## Migrate database data diff --git a/docs/how-to/development/migrate-data-via-pg-dump.md b/docs/how-to/development/migrate-data-via-pg-dump.md index b29dc91e9a..2311662b3e 100644 --- a/docs/how-to/development/migrate-data-via-pg-dump.md +++ b/docs/how-to/development/migrate-data-via-pg-dump.md @@ -2,17 +2,6 @@ This guide describes database **data** migration only. To migrate charms on new juju interfaces, refer to the guide [How to integrate a database with my charm](/how-to/development/integrate-with-your-charm). -```{note} -All commands are written for `juju >= v.3.0` - -If you are using an earlier version, be aware that: - - - `juju run` replaces `juju run-action --wait` in `juju v.2.9` - - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9` - -For more information, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). -``` - ## Do you need to migrate? A database migration is only required if the output of the following command is `latest/stable`: @@ -26,7 +15,7 @@ This guide can be used to copy data between different installations of the same ## Summary -The legacy VM charm archived in the `latest/stable` channel, read more [here](/explanation/legacy-charm). +The legacy VM charm archived in the `latest/stable` channel, read more [here](/explanation/charm-versions/legacy-charm). A minor difference in commands might be necessary for different revisions and/or Juju versions, but the general logic remains: * Deploy the modern charm nearby @@ -43,9 +32,9 @@ Always test migration in a safe environment before performing it in production! ## Prerequisites -- **[Your application is compatible](/explanation/legacy-charm) with Charmed PostgreSQL VM** +- **Your application supports modern PostgreSQL interfaces** + - See: [](check-supported-interfaces) - A client machine with access to the deployed legacy charm -- `juju v.2.9` or later (check [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) for more information about key differences) - Enough storage in the cluster to support backup/restore of the databases. ## Obtain existing database credentials diff --git a/docs/how-to/integrate-with-another-application.md b/docs/how-to/integrate-with-another-application.md index fb4569a1ec..73976c7eb8 100644 --- a/docs/how-to/integrate-with-another-application.md +++ b/docs/how-to/integrate-with-another-application.md @@ -32,7 +32,7 @@ juju remove-relation postgresql ```{caution} Note that this interface is **deprecated**. -See the [legacy charm explanation page](/explanation/legacy-charm). +See the [legacy charm explanation page](/explanation/charm-versions/legacy-charm). ``` To integrate via the legacy interface, run diff --git a/docs/index.md b/docs/index.md index f501f6f58a..33d4d032d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ This is a **IAAS/VM** operator. To deploy on Kubernetes, see [Charmed PostgreSQL | | | |--|--| | [**Get started**](/tutorial/index) - [Deploy on a cloud](/how-to/deploy/index) \| [Scale](/how-to/scale-replicas) \| [Manage passwords](/how-to/manage-passwords) \| [Enable encryption](/how-to/enable-tls) \| [Back up](/how-to/back-up-and-restore/index) \| [Monitoring](/how-to/monitoring-cos/index)
| [**How-to guides**](/how-to/index) for key tasks, use-cases, and problems. These guides assume basic familiarity with Juju and PostgreSQL.
| -| [**Reference**](/reference/index) - Technical information for quick lookup, such as [requirements](/reference/system-requirements), [plugins](/reference/plugins-extensions), and [statuses](/reference/statuses). | [**Explanation**](/explanation/interfaces-and-endpoints) - Discussion and clarification of key topics such as [architecture](/explanation/architecture), [users](/explanation/users), and [legacy charms](/explanation/legacy-charm)| +| [**Reference**](/reference/index) - Technical information for quick lookup, such as [requirements](/reference/system-requirements), [plugins](/reference/plugins-extensions), and [statuses](/reference/statuses). | [**Explanation**](/explanation/interfaces-and-endpoints) - Discussion and clarification of key topics such as [architecture](/explanation/architecture), [users](/explanation/users), and [legacy charms](/explanation/charm-versions/index)| diff --git a/docs/reference/index.md b/docs/reference/index.md index a79f940650..a2a8f11a76 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -44,7 +44,6 @@ The following generated API references can be found on [Charmhub](https://charmh :hidden: Releases -Versions System requirements Software testing Performance and resources @@ -53,3 +52,4 @@ Plugins/extensions Alert rules Statuses Contacts +``` \ No newline at end of file diff --git a/docs/reference/releases.md b/docs/reference/releases.md index d6d5bf1468..1ab96379d0 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -1,6 +1,6 @@ # Releases -This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release. +This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release of Charmed PostgreSQL 16. 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). @@ -8,15 +8,20 @@ To see all releases and commits, check the [Charmed PostgreSQL Releases page on ## 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 +**PostgreSQL 16** comes with all features supported by PostgreSQL 14: TLS encryption, COS monitoring, upgrades, cross-regional async replication, LDAP, Point-in-time recovery, and {doc}`more `. -| 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] | +In addition, Charmed PostgreSQL 16 supports new features like [Juju spaces](/how-to/deploy/juju-spaces), [Juju storage](/how-to/deploy/juju-storage), and [Juju user secrets](https://documentation.ubuntu.com/juju/latest/reference/secret/index.html#user-secret). +For more details about all new PostgreSQL 16 features, see the complete [release notes](https://github.com/canonical/postgresql-operator/releases/tag/v16%2F1.59.0). + +| Charmhub revision
(amd, arm) | Snap revision
(amd, arm) | PostgreSQL version | Minimum Juju version | +|:----------------------------:|:------------------------:|:------------------:|:--------------------:| +| [843, 844] | 218, 219 | 16.9 | 3.6 | + +```{seealso} +* [Information about all major versions](/explanation/charm-versions/index) +* {doc}`Charmed PostgreSQL 14 releases ` +``` ## Architecture and base @@ -27,14 +32,10 @@ If you do not specify a revision on deploy time, Juju will automatically choose ```{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). +See: [`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). - - - + [check]: https://img.icons8.com/color/20/checkmark--v1.png +[843, 844]: https://github.com/canonical/postgresql-operator/releases/tag/v16%2F1.59.0 diff --git a/docs/reference/statuses.md b/docs/reference/statuses.md index 0bf6c86db2..b61fa47842 100644 --- a/docs/reference/statuses.md +++ b/docs/reference/statuses.md @@ -19,7 +19,7 @@ The charm follows [standard Juju applications statuses](https://documentation.ub | **blocked** | failed to start Patroni | TODO: error/retry? | | | **blocked** | Failed to create postgres user | The charm couldn't create the default `postgres` database user due to connection problems | Connect to the database using the `operator` user and the password from the `get-password` action, then run `CREATE ROLE postgres WITH LOGIN SUPERUSER;` | | **blocked** | Failed to restore backup | The database couldn't start after the restore | The charm needs fix in the code to recover from this status and enable a new restore to be requested | -| **blocked** | Please choose one endpoint to use. No need to relate all of them simultaneously! | [The modern / legacy interfaces](/explanation/legacy-charm) should not be used simultaneously. | Remove modern or legacy relation. Choose one to use at a time. | +| **blocked** | Please choose one endpoint to use. No need to relate all of them simultaneously! | [The modern / legacy interfaces](/explanation/charm-versions/legacy-charm) should not be used simultaneously. | Remove modern or legacy relation. Choose one to use at a time. | | **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve ` after addressing the root of the error state | | **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible | | **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent | diff --git a/docs/reference/versions.md b/docs/reference/versions.md deleted file mode 100644 index 62d566d415..0000000000 --- a/docs/reference/versions.md +++ /dev/null @@ -1,128 +0,0 @@ -# PostgreSQL major versions - -Charmed PostgreSQL is shipped in following [tracks](https://documentation.ubuntu.com/juju/3.6/reference/charm/#track): - -* [PostgreSQL 16] (channel `16/stable`) -* [PostgreSQL 14] (channel `14/stable`) -* [Legacy PostgreSQL charm] (channel `latest/stable`) -> **deprecated** - -This includes two major PostgreSQL versions, `14` and `16`, matching [Ubuntu versioning](https://packages.ubuntu.com/postgresql) for PostgreSQL. - -## PostgreSQL 16 - -PostgreSQL 16 is shipped in track `16` and is available for testing in the channel `16/edge`. - ->Released alongside [PgBouncer] and [Data Integrator](https://charmhub.io/data-integrator) for Ubuntu 24.04 - -**Base:** Noble (Ubuntu 24.04) - -**Supported architectures:** `arm64` and `amd64`. - -### Supported features - -* [Juju Spaces support] -* [Multiple Juju storage support] -* [LDAP integration] (also supported by PostgreSQL `14`) -* [SoS report integration] (also supported by PostgreSQL `14`) -* [Recovery improvements] (also supported by PostgreSQL `14`) - * 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-secret) for charm [internal passwords] -* [Timescale Community Edition] -* [Extended COS integration] - * [Profiling via Parca] - * [Tracing via Tempo] -* Improved [security hardening] -* [Improved built-in roles] -* New "juju refresh" library (Refresh v3) -* Migrated to TLS v4 library - * New endpoints `client-certificates` and `peer-certificates` - * Endpoint `peer-interfaces` uses TLS by default - - - -Read more about Charmed PostgreSQL 16 features in the [release notes]. - -### Deprecated / removed - -* Legacy interface `psql` (endpoints `db` and `db-admin`). - * See more about supported interfaces in [Interfaces and endpoints]. -* Support for Juju < `v3.6` - * Charmed PostgreSQL 16 requires Juju `3.6+ LTS` due to [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html) support. -* Juju actions `get-password` and `set-password`. - * For security reasons, these actions are replaced by [Juju secrets](https://documentation.ubuntu.com/juju/3.6/reference/secret/index.html). -* [Timescale Apache 2 edition](https://docs.timescale.com/about/latest/timescaledb-editions/) has been replaced by [Timescale Community edition](https://docs.timescale.com/about/latest/timescaledb-editions/). -* The charm action `set-tls-private-key ` has been removed (will be re-introduced as Juju User Secrets) -* The charm actions `pre-upgrade-check` and `resume-upgrade ` have been removed (replaced with `pre-refresh-check` and `resume-refresh` accordingly to be consistent with `juju refresh`) -* The charm endpoint `certificates` has been split into `client-certificates` and `peer-certificates`. - -## PostgreSQL 14 - -PostgreSQL 14 is shipped in track `14` and available for production in the channel `14/stable`. - -**Base:** Jammy (Ubuntu 22.04) - -**Supported architectures:** `arm64` and `amd64`. - -### Supported features - -* [Deployment] on multiple cloud services -* [Backup and restore] - * Including point-in-time recovery (PITR) -* [COS integration] -* [TLS integration] -* [LDAP integration] -* [`arm64` architecture] - -Read more about Charmed PostgreSQL 14 features in the [release notes]. - -### Deprecated - -* The track `14` is in bug-fixing/support mode. New Charmed PostgreSQL `16` features will NOT be back-ported to track `14`. -* Charmed PostgreSQL 14 ships [Timescale Apache 2 edition](https://docs.timescale.com/about/latest/timescaledb-editions/) only. - -## Legacy PostgreSQL charm - -The legacy charm in the track `latest` has been deprecated and is **not supported.** It is still available here for the historical and comparative reasons only. - -Please use the supported tracks of the modern charm: `14/` and `16/`. - -Learn more in the [legacy charm explanation page]. - - - -[PostgreSQL 16]: https://charmhub.io/postgresql?channel=16/beta -[PostgreSQL 14]: https://charmhub.io/postgresql?channel=14/stable -[Legacy PostgreSQL charm]: https://charmhub.io/postgresql?channel=latest/stable - -[PgBouncer]: https://charmhub.io/pgbouncer - -[LDAP integration]: /how-to/enable-ldap -[SoS report integration]: /reference/troubleshooting/sos-report -[Recovery improvements]: /how-to/switchover-failover -[synchronous units]: https://charmhub.io/postgresql/configurations?channel=16/edge#synchronous-node-count -[internal charm passwords]: /explanation/users -[Timescale Community Edition]: /how-to/enable-plugins-extensions/enable-timescaledb -[Extended COS integration]: /how-to/monitoring-cos/enable-monitoring -[Profiling via Parca]: /how-to/monitoring-cos/enable-profiling -[Tracing via Tempo]: /how-to/monitoring-cos/enable-tracing -[security hardening]: /explanation/security/index -[Multiple Juju storage support]: /how-to/deploy/juju-storage -[Juju Spaces support]: /how-to/deploy/juju-spaces -[Improved built-in roles]: /explanation/roles -[release notes]: /reference/releases -[internal passwords]: /how-to/manage-passwords -[Interfaces and endpoints]: /explanation/interfaces-and-endpoints - -[Deployment]: /how-to/deploy/index -[Backup and restore]: /how-to/back-up-and-restore/create-a-backup -[COS integration]: /how-to/monitoring-cos/enable-monitoring -[TLS integration]: /how-to/enable-tls -[`arm64` architecture]: /reference/system-requirements - -[legacy charm explanation page]: /explanation/legacy-charm -