From 681bd4d7dcfbdd7f079126d7f16a593b2521a7a9 Mon Sep 17 00:00:00 2001 From: andreia Date: Mon, 27 Oct 2025 11:16:25 +0100 Subject: [PATCH 1/7] Update Diataxis landing pages --- docs/explanation/index.md | 14 ++++++--- docs/how-to/index.md | 23 ++++++++++++-- docs/how-to/logical-replication/index.md | 1 + docs/reference/index.md | 40 +----------------------- 4 files changed, 32 insertions(+), 46 deletions(-) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 948d6b26c7..c13c9dc64d 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1,8 +1,10 @@ # Explanation -Additional context about key concepts behind the PostgreSQL charm, including design and legacy information. +Additional context about the PostgreSQL charm, including design, legacy information, and security. -## Core concepts and design +## Core + +Core concepts about the history and design of the charm: ```{toctree} :titlesonly: @@ -12,7 +14,9 @@ Interfaces and endpoints Charm versions ``` -## Operational concepts +## Operation + +Clarification of standard operational concepts: ```{toctree} :titlesonly: @@ -24,7 +28,9 @@ Logs Connection pooling ``` -## Security and hardening +## Security + +Security hardening overview: ```{toctree} :titlesonly: diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 9ccd5a72ea..b7b2a8dd93 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -1,10 +1,11 @@ # How-to guides -The following guides cover key processes and common tasks for managing and using Charmed PostgreSQL on machines. +The following guides cover key processes and common tasks for setting up and managing Charmed PostgreSQL on machines. ## Deployment and setup -Installation of different cloud services with Juju: +Set up different cloud services for a Charmed PostgreSQL deployment: + * [Sunbeam] * [MAAS] * [AWS EC2] @@ -13,6 +14,7 @@ Installation of different cloud services with Juju: * [Multi-availability zones (AZ)][Multi-AZ] Other deployment scenarios and configurations: + * [Terraform] * [TLS VIP access] * [Air-gapped] @@ -21,6 +23,8 @@ Other deployment scenarios and configurations: ## Usage and maintenance +Most common operations during the initial setup of a PostgreSQL cluster: + * [Integrate with another application] * [External access] * [Scale replicas] @@ -29,6 +33,9 @@ Other deployment scenarios and configurations: * [Switchover/failover] ## Backup and restore + +Configuration of storage providers and backup management: + * [Configure S3 AWS] * [Configure S3 RadosGW] * [Create a backup] @@ -38,16 +45,23 @@ Other deployment scenarios and configurations: ## Monitoring (COS) +Observability and monitoring with the Canonical Observability Stack: + * [Enable monitoring] with Grafana * [Enable alert rules] with Prometheus * [Enable tracing] with Tempo * [Enable profiling] with Parca ## Refresh (upgrade) + +In-place upgrades to higher revisions of Charmed PostgreSQL 16: + * [How to refresh] ## Cross-regional (cluster-cluster) async replication +Walkthrough of a cluster-cluster deployment and its essential operations: + * [Cross-regional async replication] * [Set up clusters] * [Integrate with a client app] @@ -55,13 +69,16 @@ Other deployment scenarios and configurations: * [Enable plugins/extensions] ## Logical replication + +How to replicate a subset of data to another PostgreSQL cluster: + * [Logical replication] * [Set up two clusters] * [Re-enable logical replication] ## Development -This section is for charm developers looking to support PostgreSQL integrations with their charm. +For charm developers looking to support PostgreSQL integrations with their charm: * [Integrate with your charm] * [Migrate data via pg_dump] diff --git a/docs/how-to/logical-replication/index.md b/docs/how-to/logical-replication/index.md index 345b7a2bac..590a196ec1 100644 --- a/docs/how-to/logical-replication/index.md +++ b/docs/how-to/logical-replication/index.md @@ -5,6 +5,7 @@ Logical replication is a feature that allows replicating a subset of one Postgre Under the hood, it uses the publication and subscriptions mechanisms from the [PostgreSQL logical replication](https://www.postgresql.org/docs/16/logical-replication.html) feature. ## Prerequisites + * Juju `v.3.6.8+` * Make sure your machine(s) fulfil the [](/reference/system-requirements) diff --git a/docs/reference/index.md b/docs/reference/index.md index a2a8f11a76..13665173d7 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,47 +1,9 @@ # Reference -Technical specifications, APIs, release notes, and other reference material for fast lookup. - -* [Releases] - Overview of major revisions of this charm -* [System requirements] -* [Software testing] -* [Performance and resources] -* [Troubleshooting] - * [CLI helpers] - Patroni CLI tools for troubleshooting -* [Plugins/extensions] -* [Alert rules] - Pre-configured Prometheus alert rules -* [Statuses] - Juju application statuses -* [Contacts] - - -The following generated API references can be found on [Charmhub](https://charmhub.io/postgresql): - -| Page | Description | -|------|-------------| -| [Integrations](https://charmhub.io/postgresql/integrations) | Integration/relation interfaces supported by this charm | -| [Libraries](https://charmhub.io/postgresql/libraries) | VM charm library is empty as charm uses [K8s library](https://charmhub.io/postgresql-k8s/libraries/) (more info [here](/explanation/architecture)) | -| [Configuration](https://charmhub.io/postgresql/configuration) | Application configuration parameters | -| [Actions](https://charmhub.io/postgresql/actions) | Juju actions supported by this charm | - - - -[Releases]: /reference/releases -[System requirements]: /reference/system-requirements -[Software testing]: /reference/software-testing -[Performance and resources]: /reference/performance-and-resources -[Troubleshooting]: /reference/troubleshooting/index -[CLI helpers]: /reference/troubleshooting/cli-helpers -[Plugins/extensions]: /reference/plugins-extensions -[Alert rules]: /reference/alert-rules -[Statuses]: /reference/statuses -[Contacts]: /reference/contacts - +Information about releases, charm options, technical specifications, and other reference material for quick lookup. ```{toctree} :titlesonly: -:maxdepth: 2 -:glob: -:hidden: Releases System requirements From 23379f8a5765b2baedf601c5378dbd682ebda22a Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 12:24:35 +0100 Subject: [PATCH 2/7] replace development section with data migration section --- docs/explanation/roles.md | 1 + .../integrate-with-your-charm.md | 0 .../{development => migrate-data}/index.md | 0 .../migrate-data-via-backup-restore.md | 4 +- .../migrate-data-via-pg-dump.md | 41 +++++++++++-------- 5 files changed, 28 insertions(+), 18 deletions(-) rename docs/how-to/{development => }/integrate-with-your-charm.md (100%) rename docs/how-to/{development => migrate-data}/index.md (100%) rename docs/how-to/{development => migrate-data}/migrate-data-via-backup-restore.md (81%) rename docs/how-to/{development => migrate-data}/migrate-data-via-pg-dump.md (84%) diff --git a/docs/explanation/roles.md b/docs/explanation/roles.md index 1eff6097f1..0eae363642 100644 --- a/docs/explanation/roles.md +++ b/docs/explanation/roles.md @@ -1,3 +1,4 @@ +(roles)= # Roles There are several definitions of roles in Charmed PostgreSQL: diff --git a/docs/how-to/development/integrate-with-your-charm.md b/docs/how-to/integrate-with-your-charm.md similarity index 100% rename from docs/how-to/development/integrate-with-your-charm.md rename to docs/how-to/integrate-with-your-charm.md diff --git a/docs/how-to/development/index.md b/docs/how-to/migrate-data/index.md similarity index 100% rename from docs/how-to/development/index.md rename to docs/how-to/migrate-data/index.md diff --git a/docs/how-to/development/migrate-data-via-backup-restore.md b/docs/how-to/migrate-data/migrate-data-via-backup-restore.md similarity index 81% rename from docs/how-to/development/migrate-data-via-backup-restore.md rename to docs/how-to/migrate-data/migrate-data-via-backup-restore.md index f4e5277133..af7454fff5 100644 --- a/docs/how-to/development/migrate-data-via-backup-restore.md +++ b/docs/how-to/migrate-data/migrate-data-via-backup-restore.md @@ -1,8 +1,8 @@ -# Migrate database data using ‘backup/restore’ +# Migrate database data using backup/restore 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/)! +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 has to be created manually using [pgBackRest](https://pgbackrest.org/)! ```{caution} The Canonical Data Team describes here the general approach and does NOT support nor guarantee the restoration results. diff --git a/docs/how-to/development/migrate-data-via-pg-dump.md b/docs/how-to/migrate-data/migrate-data-via-pg-dump.md similarity index 84% rename from docs/how-to/development/migrate-data-via-pg-dump.md rename to docs/how-to/migrate-data/migrate-data-via-pg-dump.md index 2311662b3e..060e4d788b 100644 --- a/docs/how-to/development/migrate-data-via-pg-dump.md +++ b/docs/how-to/migrate-data/migrate-data-via-pg-dump.md @@ -1,21 +1,8 @@ -# Migrate database data using `pg_dump` / `pg_restore` +(migrate-data-via-pg-dump)= +# Migrate database data using `pg_dump` -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). +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). -## Do you need to migrate? - -A database migration is only required if the output of the following command is `latest/stable`: - -```text -juju show-application postgresql | yq '.[] | .channel' -``` -Migration is **not** necessary if the output above is `14/stable`! - -This guide can be used to copy data between different installations of the same (modern) charm `postgresql`, but the [backup/restore](/how-to/development/migrate-data-via-backup-restore) is more recommended for migrations between modern charms. - -## Summary - -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 @@ -42,13 +29,16 @@ Always test migration in a safe environment before performing it in production! To obtain credentials for existing databases, execute the following commands for **each** database that will be migrated. Take note of these credentials for future steps. First, define and tune your application and db (database) names. For example: + ```text CLIENT_APP=< my-application/0 > OLD_DB_APP=< legacy-postgresql/leader | postgresql/0 > NEW_DB_APP=< new-postgresql/leader | postgresql/0 > DB_NAME=< your_db_name_to_migrate > ``` + Then, obtain the username from the existing legacy database via its relation info: + ```text OLD_DB_USER=$(juju show-unit ${CLIENT_APP} | yq '.[] | .relation-info | select(.[].endpoint == "db") | .[0].application-data.user') ``` @@ -60,13 +50,16 @@ Deploy new PostgreSQL database charm: ```text juju deploy postgresql ${NEW_DB_APP} --channel 16/stable ``` + Obtain `operator` user password of new PostgreSQL database from PostgreSQL charm: + ```text NEW_DB_USER=operator NEW_DB_PASS=$(juju run ${NEW_DB_APP} get-password | yq '.password') ``` ## Migrate database + Use the credentials and information obtained in previous steps to perform the database migration with the following procedure. ```{note} @@ -74,47 +67,63 @@ Make sure no new connections were made and that the database has not been altere ``` ### Create dump from legacy charm + Remove the relation between application charm and legacy charm: + ```text juju remove-relation ${CLIENT_APP} ${OLD_DB_APP} ``` Connect to the database VM of a legacy charm: + ```text juju ssh ${OLD_DB_APP} bash ``` + Create a dump via Unix socket using credentials from the relation: + ```text mkdir -p /srv/dump/ OLD_DB_DUMP="legacy-postgresql-${DB_NAME}.sql" pg_dump -Fc -h /var/run/postgresql/ -U ${OLD_DB_USER} -d ${DB_NAME} > "/srv/dump/${OLD_DB_DUMP}" ``` + Exit the database VM: + ```text exit ``` ### Upload dump to new charm + Fetch dump locally and upload it to the new Charmed PostgreSQL charm: + ```text juju scp ${OLD_DB_APP}:/srv/dump/${OLD_DB_DUMP} ./${OLD_DB_DUMP} juju scp ./${OLD_DB_DUMP} ${NEW_DB_APP}:. ``` + ssh into new Charmed PostgreSQL charm and create a new database (using `${NEW_DB_PASS}`): + ```text juju ssh ${NEW_DB_APP} bash createdb -h localhost -U ${NEW_DB_USER} --password ${DB_NAME} ``` + Restore the dump (using `${NEW_DB_PASS}`): + ```text pg_restore -h localhost -U ${NEW_DB_USER} --password -d ${DB_NAME} --no-owner --clean --if-exists ${OLD_DB_DUMP} ``` ## Integrate with modern charm + Integrate (formerly "relate" in `juju v.2.9`) your application and new PostgreSQL database charm (using the modern `database` endpoint) + ```text juju integrate ${CLIENT_APP} ${NEW_DB_APP}:database ``` If the `database` endpoint (from the `postgresql_client` interface) is not yet supported, use instead the `db` endpoint from the legacy `pgsql` interface: + ```text juju integrate ${CLIENT_APP} ${NEW_DB_APP}:db ``` From 85619974c0cda5bbf6991a9f3e473f21c0949c49 Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 12:24:49 +0100 Subject: [PATCH 3/7] (wip) 14 to 16 data migration guide --- .../migrate-data-from-14-to-16.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/how-to/migrate-data/migrate-data-from-14-to-16.md diff --git a/docs/how-to/migrate-data/migrate-data-from-14-to-16.md b/docs/how-to/migrate-data/migrate-data-from-14-to-16.md new file mode 100644 index 0000000000..3f559be515 --- /dev/null +++ b/docs/how-to/migrate-data/migrate-data-from-14-to-16.md @@ -0,0 +1,117 @@ +# Migrate data from PostgreSQL 14 to 16 + +There are two possible ways to migrate data from PostgreSQL 14 to 16 depending on how {ref}`roles` are managed: + +**In the case of charm roles management**, all the database objects ownership will be handled by charm automatically. This is what this guide will cover. + +**In case of admin roles management**, all database objects ownership are handled manually by the user. See: {ref}`migrate-data-via-pg-dump`. + + +Note: make sure `extra-user-roles` set to `charmed-admin` once Juju relation requested to such DB. + +This guide covers how to migrate data from Charmed PostgreSQL 14 to 16 using the new charm roles management setup for client applications managed by Juju. The migrated data from PostgreSQL 14 will be mapped to the corresponding ownership in PostgreSQL 16. + +## Prepare PostgreSQL 14 data + +First, in order to make sure the latest data is written to your dump, remove the relation between the client app and Charmed PostgreSQL 14. + +Define the following variables for the old database: + +```shell +TMP_PATH="~/old-db-dump/" +OLD_DB_NAME="postgresql_test_app_database" +OLD_IP="10.218.34.229" +OLD_USER="operator" +OLD_PASSWORD="fJQYljbthEo2T1gj" +``` + +Create a dump of the old PostgreSQL 14 database with `pg_dump`: + +```shell +mkdir -p "${TMP_PATH}" +PGPASSWORD="${OLD_PASSWORD}" pg_dump -j 4 -Fd -h "${OLD_IP}" -U "${OLD_USER}" -d "${OLD_DB_NAME}" -f "${TMP_PATH}" --compress 9 +``` + +## Set up new PostgreSQL 16 charm + +Deploy one unit of Charmed PostgreSQL 16. This will simplify the migration and can be scaled later. + +```shell +juju deploy postgresql --channel 16/stable +``` + +Define the following variables for the new database: + +```shell +NEW_DB_NAME="postgresql_test_app_database123" +NEW_IP="10.218.34.56" +NEW_USER="operator" +NEW_PASSWORD="RnnijCiotVeW8O5I" +NEW_OWNER="charmed_${NEW_DB_NAME}_owner" +``` + +Migrate the following charm features from the old 14 charm to the new 16 charm: +* any necessary charm config options +* enabled charm extensions/plugins + +```{note} +Config options and extensions *must* be migrated before restoring the data dump +``` + +## Create a new database on PostgreSQL 16 + +```shell +PGPASSWORD="${NEW_PASSWORD}" psql -h "${NEW_IP}" -U "${NEW_USER}" -d postgres -c "CREATE DATABASE ${NEW_DB_NAME}" +``` + +Create new roles by running the function `set_up_predefined_catalog_roles()` in all databases except `postgres` and `template1`. It will create roles like `charmed__owner`, `..._dml` and others: + +```shell +PGPASSWORD="${NEW_PASSWORD}" psql -h "${NEW_IP}" -U "${NEW_USER}" -d "${NEW_DB_NAME}" -c "SELECT set_up_predefined_catalog_roles();" +PGPASSWORD="${NEW_PASSWORD}" psql -h "${NEW_IP}" -U "${NEW_USER}" -d "${NEW_DB_NAME}" -c "ALTER DATABASE ${NEW_DB_NAME} OWNER TO charmed_databases_owner;" +PGPASSWORD="${NEW_PASSWORD}" psql -h "${NEW_IP}" -U "${NEW_USER}" -d "${NEW_DB_NAME}" -c "ALTER SCHEMA public OWNER TO ${NEW_OWNER};" +``` + +## Migrate data from PostgreSQL 14 to 16 + +Restore the PostgreSQL 14 database dump into the new 16 database: + +```shell +PGPASSWORD="${NEW_PASSWORD}" pg_restore -j 4 -h "${NEW_IP}" -U "${NEW_USER}" -d "${NEW_DB_NAME}" -Fd "${TMP_PATH}" --no-owner +``` + +### Set up new database ownership + +Verify and modify the ownership for each database object in each schema to be equal to `charmed__owner` (`${NEW_OWNER}` above). + +For example, to find and fix ownership for all tables, sequences, and views: + +```shell +PGPASSWORD="${NEW_PASSWORD}" psql -h "${NEW_IP}" -U "${NEW_USER}" -d "${NEW_DB_NAME}" + +mydb=> DO $$ +DECLARE + r record; +BEGIN + FOR r IN + SELECT format('ALTER %s %I.%I OWNER TO %I;', + CASE c.relkind + WHEN 'r' THEN 'TABLE' + WHEN 'v' THEN 'VIEW' + WHEN 'm' THEN 'MATERIALIZED VIEW' + WHEN 'S' THEN 'SEQUENCE' + WHEN 'p' THEN 'TABLE' + ELSE NULL END, + n.nspname, c.relname, 'charmed__owner') + FROM pg_class c + JOIN pg_namespace n ON n.oid = c.relnamespace + WHERE n.nspname = 'public' + LOOP + EXECUTE r.format; + END LOOP; +END$$; +``` + +At this stage, the database has been completely imported. The cluster can be scaled, and the client app can be related to the new PostgreSQL 16 database. + +contact \ No newline at end of file From dd77e4d30255984efaf0bb772948478e83a8f430 Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 16:06:08 +0100 Subject: [PATCH 4/7] refactor landing page and polish migration guide --- .../charm-versions/legacy-charm.md | 2 +- docs/how-to/index.md | 24 +++++++++++++++---- .../integrate-with-another-application.md | 2 +- docs/how-to/migrate-data/index.md | 15 +++++++++--- .../migrate-data-from-14-to-16.md | 17 ++++--------- .../migrate-data-via-backup-restore.md | 3 ++- .../migrate-data/migrate-data-via-pg-dump.md | 4 ++-- 7 files changed, 42 insertions(+), 25 deletions(-) diff --git a/docs/explanation/charm-versions/legacy-charm.md b/docs/explanation/charm-versions/legacy-charm.md index 17c758e882..e1753305aa 100644 --- a/docs/explanation/charm-versions/legacy-charm.md +++ b/docs/explanation/charm-versions/legacy-charm.md @@ -4,7 +4,7 @@ The legacy PostgreSQL charm is a [Reactive charm](https://documentation.ubuntu.c 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 implementing compatible endpoints, see: [](/how-to/integrate-with-your-charm) To read more about the legacy charm see the {doc}`PostgreSQL 14 documentation `. diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 515c37861a..4e462b2b67 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -54,7 +54,7 @@ Monitoring (COS) ## Refresh (upgrade) -In-place upgrades to higher revisions of Charmed PostgreSQL 16: +Instructions for performing an in-place application refresh: ```{toctree} :titlesonly: @@ -62,6 +62,17 @@ In-place upgrades to higher revisions of Charmed PostgreSQL 16: Refresh (upgrade) ``` +## Data migration + +For charm developers looking to support PostgreSQL integrations with their charm: + +```{toctree} +:maxdepth: 2 +:titlesonly: + +Migrate data +``` + ## Cross-regional (cluster-cluster) async replication Walkthrough of a cluster-cluster deployment and its essential operations: @@ -84,13 +95,16 @@ How to replicate a subset of data to another PostgreSQL cluster: Logical replication ``` -## Development +## Charm development -For charm developers looking to support PostgreSQL integrations with their charm: +For charm developers looking to support PostgreSQL integrations with their charm ```{toctree} -:maxdepth: 2 :titlesonly: -Development +Integrate PostgreSQL with your charm ``` + +Other relevant guides: +* {ref}`migrate-data-via-pg-dump` +* {ref}`migrate-data-via-backup-restore` \ No newline at end of file diff --git a/docs/how-to/integrate-with-another-application.md b/docs/how-to/integrate-with-another-application.md index 73976c7eb8..21a34180e2 100644 --- a/docs/how-to/integrate-with-another-application.md +++ b/docs/how-to/integrate-with-another-application.md @@ -4,7 +4,7 @@ This guide shows how to integrate Charmed PostgreSQL with both charmed and non-charmed applications. -For developer information about how to integrate your own charmed application with PostgreSQL, see [Development > How to integrate with your charm](/how-to/development/integrate-with-your-charm). +For developer information about how to integrate your own charmed application with PostgreSQL, see [Development > How to integrate with your charm](/how-to/integrate-with-your-charm). ## Integrate with a charmed application diff --git a/docs/how-to/migrate-data/index.md b/docs/how-to/migrate-data/index.md index 710279e2d9..fbf3c55d84 100644 --- a/docs/how-to/migrate-data/index.md +++ b/docs/how-to/migrate-data/index.md @@ -1,9 +1,18 @@ -# Development +# Migrate data + +For guidance about moving data from a Charmed PostgreSQL 14 database to Charmed PostgreSQL 16, start here: + +```{toctree} +:titlesonly: + +Migrate data from PostgreSQL 14 to 16 +``` + +More generic data migration guides: ```{toctree} :titlesonly: -Integrate with your charm -Migrate data via pg_dump +Migrate data via `pg_dump` Migrate data via backup/restore ``` \ No newline at end of file diff --git a/docs/how-to/migrate-data/migrate-data-from-14-to-16.md b/docs/how-to/migrate-data/migrate-data-from-14-to-16.md index 3f559be515..9eb18ae8ee 100644 --- a/docs/how-to/migrate-data/migrate-data-from-14-to-16.md +++ b/docs/how-to/migrate-data/migrate-data-from-14-to-16.md @@ -2,20 +2,15 @@ There are two possible ways to migrate data from PostgreSQL 14 to 16 depending on how {ref}`roles` are managed: -**In the case of charm roles management**, all the database objects ownership will be handled by charm automatically. This is what this guide will cover. +**In case of admin roles management**, all database objects ownership are handled manually by the user. In this case, see the more general guide {ref}`migrate-data-via-pg-dump`. Note that you must set `extra-user-roles` to `charmed-admin` once a Juju relation is requested the new database. -**In case of admin roles management**, all database objects ownership are handled manually by the user. See: {ref}`migrate-data-via-pg-dump`. - - -Note: make sure `extra-user-roles` set to `charmed-admin` once Juju relation requested to such DB. - -This guide covers how to migrate data from Charmed PostgreSQL 14 to 16 using the new charm roles management setup for client applications managed by Juju. The migrated data from PostgreSQL 14 will be mapped to the corresponding ownership in PostgreSQL 16. +**In the case of charm roles management**, all the database objects ownership will be handled by charm automatically. This guide covers how to migrate data from Charmed PostgreSQL 14 to 16 using the new charm roles management setup for client applications managed by Juju. The migrated data from PostgreSQL 14 will be mapped to the corresponding ownership in PostgreSQL 16. ## Prepare PostgreSQL 14 data -First, in order to make sure the latest data is written to your dump, remove the relation between the client app and Charmed PostgreSQL 14. +First, in order to make sure the latest data is included, remove the relation between the client app and Charmed PostgreSQL 14. -Define the following variables for the old database: +Then, define the following variables for the old database: ```shell TMP_PATH="~/old-db-dump/" @@ -112,6 +107,4 @@ BEGIN END$$; ``` -At this stage, the database has been completely imported. The cluster can be scaled, and the client app can be related to the new PostgreSQL 16 database. - -contact \ No newline at end of file +At this stage, the database has been completely imported. The cluster can be scaled, and the client app can be related to the new PostgreSQL 16 database. \ No newline at end of file diff --git a/docs/how-to/migrate-data/migrate-data-via-backup-restore.md b/docs/how-to/migrate-data/migrate-data-via-backup-restore.md index af7454fff5..d2dc9bab65 100644 --- a/docs/how-to/migrate-data/migrate-data-via-backup-restore.md +++ b/docs/how-to/migrate-data/migrate-data-via-backup-restore.md @@ -1,4 +1,5 @@ -# Migrate database data using backup/restore +(migrate-data-via-backup-restore)= +# Migrate data via backup/restore 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). diff --git a/docs/how-to/migrate-data/migrate-data-via-pg-dump.md b/docs/how-to/migrate-data/migrate-data-via-pg-dump.md index 060e4d788b..3d38c11ad0 100644 --- a/docs/how-to/migrate-data/migrate-data-via-pg-dump.md +++ b/docs/how-to/migrate-data/migrate-data-via-pg-dump.md @@ -1,7 +1,7 @@ (migrate-data-via-pg-dump)= -# Migrate database data using `pg_dump` +# Migrate data via `pg_dump` -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). +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/integrate-with-your-charm). A minor difference in commands might be necessary for different revisions and/or Juju versions, but the general logic remains: From efd65d34d4475909638edfb4c1863b6d539fb5c8 Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 16:11:04 +0100 Subject: [PATCH 5/7] Rename section --- docs/how-to/{migrate-data => data-migration}/index.md | 0 .../migrate-data-from-14-to-16.md | 0 .../migrate-data-via-backup-restore.md | 0 .../migrate-data-via-pg-dump.md | 0 docs/how-to/index.md | 2 +- 5 files changed, 1 insertion(+), 1 deletion(-) rename docs/how-to/{migrate-data => data-migration}/index.md (100%) rename docs/how-to/{migrate-data => data-migration}/migrate-data-from-14-to-16.md (100%) rename docs/how-to/{migrate-data => data-migration}/migrate-data-via-backup-restore.md (100%) rename docs/how-to/{migrate-data => data-migration}/migrate-data-via-pg-dump.md (100%) diff --git a/docs/how-to/migrate-data/index.md b/docs/how-to/data-migration/index.md similarity index 100% rename from docs/how-to/migrate-data/index.md rename to docs/how-to/data-migration/index.md diff --git a/docs/how-to/migrate-data/migrate-data-from-14-to-16.md b/docs/how-to/data-migration/migrate-data-from-14-to-16.md similarity index 100% rename from docs/how-to/migrate-data/migrate-data-from-14-to-16.md rename to docs/how-to/data-migration/migrate-data-from-14-to-16.md diff --git a/docs/how-to/migrate-data/migrate-data-via-backup-restore.md b/docs/how-to/data-migration/migrate-data-via-backup-restore.md similarity index 100% rename from docs/how-to/migrate-data/migrate-data-via-backup-restore.md rename to docs/how-to/data-migration/migrate-data-via-backup-restore.md diff --git a/docs/how-to/migrate-data/migrate-data-via-pg-dump.md b/docs/how-to/data-migration/migrate-data-via-pg-dump.md similarity index 100% rename from docs/how-to/migrate-data/migrate-data-via-pg-dump.md rename to docs/how-to/data-migration/migrate-data-via-pg-dump.md diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 4e462b2b67..54877613bf 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -70,7 +70,7 @@ For charm developers looking to support PostgreSQL integrations with their charm :maxdepth: 2 :titlesonly: -Migrate data +Data migration ``` ## Cross-regional (cluster-cluster) async replication From c6672035107412504472b63388236b172c2b07ab Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 16:17:19 +0100 Subject: [PATCH 6/7] fix broken references --- docs/how-to/data-migration/migrate-data-via-backup-restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/data-migration/migrate-data-via-backup-restore.md b/docs/how-to/data-migration/migrate-data-via-backup-restore.md index d2dc9bab65..5d35eaaa0e 100644 --- a/docs/how-to/data-migration/migrate-data-via-backup-restore.md +++ b/docs/how-to/data-migration/migrate-data-via-backup-restore.md @@ -1,7 +1,7 @@ (migrate-data-via-backup-restore)= # Migrate data via backup/restore -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 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/data-migration/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 has to be created manually using [pgBackRest](https://pgbackrest.org/)! @@ -20,7 +20,7 @@ Below is the *general approach* to the migration (see warning above!): 1. Retrieve root/admin level credentials from legacy charm. - See examples in [](/how-to/development/migrate-data-via-pg-dump). + See examples in [](/how-to/data-migration/migrate-data-via-pg-dump). 2. Install [pgBackRest](https://pgbackrest.org/) inside the old charm OR nearby. From 4afb08097da909d38cb3664aa8a9da385afcd2d7 Mon Sep 17 00:00:00 2001 From: andreia Date: Wed, 29 Oct 2025 17:02:31 +0100 Subject: [PATCH 7/7] remove mailing list --- docs/reference/contacts.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/contacts.md b/docs/reference/contacts.md index dbbe12750e..bd11cbfd2d 100644 --- a/docs/reference/contacts.md +++ b/docs/reference/contacts.md @@ -13,5 +13,4 @@ Useful links: * [Git sources for Charmed PostgreSQL](https://github.com/canonical/postgresql-operator) * [Canonical Data on Launchpad](https://launchpad.net/~data-platform) * [Canonical Data on Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) -* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/)