migration_PG 12

docs/reference/known_limitations.md

@@ -48,6 +48,7 @@ We are developing a new feature that will allow you to modify these settings dir
 ## Upgrading operators
 
 - When you upgrade PostgreSQL operators to version 2.4.1, the database transitions to the **Initializing** state as part of the upgrade process. However, this **Initializing** state does not cause any downtime.
+- Since the PostgreSQL operator does not support major version upgrades, you cannot directly upgrade PostgreSQL 12.19 to 13.16. This limitation also prevents upgrading the PG operator itself. Morever, there is no built-in mechanism for transferring data from PostgreSQL 12.19 to 13.16, making migration a challenge.
 - When you upgrade PXC operators to version 1.15.0, single node MySQL databases will be restarted, resulting in downtime. However, it is worth noting that single node databases should not be used in production environments.
 
 ## Backups storage

docs/reference/postgresql12_migration.md

@@ -0,0 +1,113 @@
+# Migrate from PostgreSQL 12
+
+!!! info "Important"
+    Percona Everest 1.6.0 has officially discontinued support for PostgreSQL 12. To ensure compatibility, security, and access to new features, it is highly recommended to migrate to PostgreSQL 13 or later.
+
+## Preparation before migration
+
+Before migrating from PostgreSQL 12, it's important to prepare thoroughly to ensure a smooth transition. Here are the key steps:
+{.power-number}
+
+1. **Backup your data** - Create a complete backup of your data before upgrading.
+
+2. **Select a target version** - Choose the PostgreSQL version you want to migrate to (e.g., 15 or 16). Select a stable, supported release compatible with Percona Everest's infrastructure requirements.
+
+3. **Check Compatibility** - Verify that your configurations are compatible with the new PostgreSQL version.
+
+4. **Provision a new PostgreSQL database in Percona Everest** – Use Percona Everest to deploy a new database with the desired PostgreSQL version.
+
+
+## Choose a migration option
+
+When upgrading from PostgreSQL 12, it is essential to choose a migration method that suits your environment. For a smooth transition, consider the following factors during migration:
+
+- Data size
+
+- Downtime tolerance
+
+PostgreSQL offers several migration options. Each method has its own benefits and trade-offs in terms of speed, complexity, and risk.
+
+Review PostgreSQL documentation to select the best option for your environment.
+
+💡 Need assistance? Connect with [Percona Everest community](https://forums.percona.com/t/welcome-to-perconas-community-forum/7){:target="_blank"}! 
+
+Alternatively, you can always [Talk to a Percona Expert](../get-help.md#percona-experts).
+
+
+??? info "Comprehensive analysis of PostgreSQL migration techniques: Expand for a detailed comparison of logical dump vs replication →"
+
+    ### Logical dump and restore vs. Logical replication
+
+    Two commonly used approaches to migrating a PostgreSQL database are Logical Dump and Restore and Logical Replication. Both methods help move data from one instance to another, but they have different purposes and distinct advantages.
+
+    | **Feature**              | **Logical Dump and Restore**               | **Logical Replication**               |
+    |--------------------------|-------------------------------------------|--------------------------------------|
+    | **Setup complexity**      | Simple and portable                      | More complex, involves replication slots |
+    | **Best suited for**           | One-time migrations, backups, and moving datasets across versions | Continuous data synchronization |
+    | **Downtime Impact**      | Requires application downtime during migration | Minimal downtime |
+    | **Primary Keys requirement** | No primary keys required; exports full table data regardless of constraints | Requires primary keys (or unique indexes) on tables|
+    | **Schema compatibility**  | Allows schema modifications before restoration; supports cross-version migration | Requires schema compatibility between source and target databases |
+    | **Performance**          | Can be slow for large datasets due to full export/import | More efficient for continuous updates, but may add replication overhead |
+
+
+=== "Logical replication"
+
+    ### Logical Replication
+
+    This option is recommended for **minimal downtime**.
+
+    Use [logical replication](https://www.postgresql.org/docs/current/logical-replication.html) to continuously replicate data from your PostgreSQL 12 cluster into a PostgresQLG 13+ cluster with little to no downtime.
+
+    📚 Learn more
+
+    - [PostgreSQL documentation on logical replication](https://www.postgresql.org/docs/current/logical-replication.html).
+
+=== "Logical dump and restore"
+
+    ### Logical Dump and Restore
+
+    This option is recommended for **smaller databases** and **one-time migrations**.
+    {.power-number}
+
+    1. Provision a new PostgreSQl database in Percona Everest.
+
+
+    2. Perform a logical dump of the old database:
+
+        - Use [pg_dump or pg_dumpall](https://www.postgresql.org/docs/current/app-pgdump.html) to **export** your data from PostgreSQL 12.
+
+            ??? example "Example: Source database (PostgreSQL 12)"
+                Run the following command on the source database (PostgreSQL 12):
+
+                ```sh
+                pg_dump -Fc -h <old-db-host> -U <user> <db_name> -f dump_file.dump
+                ```
+
+    3. Restore data to the new Percona Everest database:
+
+        - Use [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html) or [psql](https://www.postgresql.org/docs/current/app-psql.html) to import data into the newly created Percona Everest cluster.
+
+            ??? example "Example: Target database"
+                Run the following command on the target PostgreSQL database:
+
+                ```sh
+                pg_restore -U your_user -h new_db_host -d new_db_name -F c dump_file.dump
+                ```
+
+    4. Verify post-migration performance:
+
+        - Run queries to confirm [data integrity](https://www.postgresql.org/docs/current/applevel-consistency.html) and ensure compatibility.
+
+    📚 Reference
+
+    - [PostgreSQL pg_dump documentation](https://www.postgresql.org/docs/current/app-pgdump.html)
+    - [PostgreSQL pg_restore documentation](https://www.postgresql.org/docs/current/app-pgrestore.html)
+
+
+
+
+
+
+
+
+

mkdocs-base.yml

@@ -217,6 +217,7 @@ nav:
   - Reference:
       - Breaking API changes: api_rbac.md
       - Limitations: reference/known_limitations.md
+      - Migrate from PostgreSQL 12: reference/postgresql12_migration.md
       - Telemetry on Percona Everest: reference/telemetry.md
       - Migrate to Percona Everest: reference/migration_guide.md
       - Copyright and licensing information: reference/copyright.md