Merge pull request #769 from EnterpriseDB/DOCS-3266

PSR to PGD migration guide

Author: mpfuster

advocacy_docs/supported-open-source/warehousepg/warehousepg/admin_guide/index.mdx

@@ -30,4 +30,4 @@ Information about configuring, managing and monitoring WarehousePG installations
 -   **[Loading and Unloading Data](load/topics)**  
     The topics in this section describe methods for loading and writing data into and out of a WarehousePG, and how to format data files.
 -   **[Managing Performance](performance.mdx)**  
-    The topics in this section cover WarehousePG performance management, including how to monitor performance and how to configure workloads to prioritize resource utilization.
+    The topics in this section cover WarehousePG performance management, including how to monitor performance and how to configure workloads to prioritize resource utilization.

product_docs/docs/pgd/6.2/index.mdx

@@ -14,11 +14,6 @@ navigation:
   - overview
   - planning
   - lifecycle
-  - deployments
-  - installing
-  - connections
-  - production-best-practices
-  - terminology
   - "#Configuration and Management"
   - nodes
   - node_management

product_docs/docs/pgd/6.2/lifecycle/migrating/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Migrating to Postgres Distributed (PGD)
+navTitle: Migrating to PGD
+description: Migrate from PSR to EDB Postgres Distributed.
+navigation:
+  - migration-psr
+---
+
+Moving from a traditional architecture to EDB Postgres Distributed (PGD) allows your organization to achieve high availability, geographically distributed workloads, and multi-master write capabilities.
+
+The following guide details the tested and supported pathways for transitioning your existing infrastructure into a highly available PGD cluster.
+
+- [Migrate from Postgres Physical Streaming Replication (PSR) to PGD:](/pgd/latest/lifecycle/migrating/migration-psr/) Transition a standard primary-standby architecture to a PGD cluster using a seed-node approach to minimize downtime during data transfer and version upgrades.

product_docs/docs/pgd/6.2/lifecycle/migrating/migration-psr/1-preparation.mdx

@@ -0,0 +1,53 @@
+---
+title: Preparing your environment
+navTitle: Preparing your environment
+description: Preparing your environment to perform a migration from PSR to PGD.
+---
+
+Before beginning the migration from Physical Streaming Replication (PSR) to Postgres Distributed (PGD), you must identify the key roles of your nodes and establish your target topology. This ensures the environment can handle the temporary overhead of the migration and provides a clear path for the cluster transition.
+
+## Choosing a source node
+
+You must choose a source node from your existing cluster to provide the initial data and subsequent updates for the PGD cluster. Because logical replication cannot be cascaded from a standby node, only the current primary node is a viable source.
+
+Consider the following:
+- **Resource overhead:** During migration, the source node node must perform additional logical decoding for at least two PGD nodes, requiring extra CPU capacity.
+- **Storage:** The source node will need to retain additional WAL data to keep replicas in sync, necessitating more disk space than standard operations.
+- **Optimization:** If the current primary is underpowered, consider a switchover (promotion) to a more favorable node before starting the migration.
+- **Failover handling:** If the primary node fails during the migration, you must abort and restart the process using a new primary as the source.
+
+## Choosing a seed node
+
+The seed node is a new node selected from the group that will form your PGD cluster. This node serves a unique transitional role during the migration:
+
+1. It receives a full copy of the database from the source node.
+1. It performs the in-place major version upgrade.
+1. It initializes the final PGD cluster.
+
+
+## Planning your PGD cluster topology
+
+Establish your target topology in advance. Define locations, hostnames, PGD node names, and connection strings (DSNs) before proceeding. This guide assumes a two-node PGD start: the seed node (first node) and one additional node. Adding further nodes follows the same process as the second node.
+
+Use the following table to map the required environment variables for your cluster, ensuring consistency across all configuration scripts.
+
+| Variable | Description | Example | 
+| -------- | ----------- | ------- | 
+| `${SEED_NODE_PGD_NAME}` | The PGD-specific name assigned to the seed node. | node-1 | 
+| `${SEED_NODE_DSN}` | Connection string to reach the seed node. | host=node-1 port=5444 dbname=pgddb user=postgres | 
+| `${ADD_NODE_PGD_NAME}` | The PGD-specific name for the second node. | node-2 | 
+| `${ADD_NODE_DSN}` | Connection string to reach the additional node. | host=node-2 port=5432 dbname=pgddb user=postgres | 
+| `${PGD_CLUSTER_NAME}` | The name of the PGD node group containing all nodes. | pgd_cluster_main | 
+
+## Command environment setup
+
+The migration steps specify which node to use for each command.
+
+To ensure the migration commands execute correctly, verify your environment meets the following requirements:
+
+- **Shell permissions:** Execute all commands as `root` unless the instructions explicitly specify using `su`.
+- **Environment variables:** Ensure `${PGDATA}` is set to your Postgres data directory (e.g., `/var/lib/edb/as14/data` for EPAS 14). You may also need to set `${PGPORT}`.
+- **Target database:** Connect to the specific database to migrate (not the default `postgres` or `edb` databases) by setting `${PGDATABASE}` before running `psql`.
+
+
+Next step: [Transfer data to the seed node](2-data-transfer).

product_docs/docs/pgd/6.2/lifecycle/migrating/migration-psr/2-data-transfer.mdx

@@ -0,0 +1,155 @@
+---
+title: Transferring data to the seed node
+navTitle: Transferring data to the seed node
+description: Initialize the seed node through manual physical replication..
+---
+
+In this phase, you initialize the seed node by creating a standby copy of the database on the seed node that mirrors the source node via physical replication. This standby serves as the seed node for the eventual PGD cluster. To minimize interference with the existing cluster—particularly if it is managed by Failover Manager (EFM)—this replica is added manually. 
+
+## Preparing the source node for logical replication
+
+You must prepare the seed node to transition to logical replication. If not already enabled, set the `wal_level` to `logical` on the source node. Since this change requires a database restart, it is best to perform this step ahead of time.
+
+1. Run the following command on the source node:
+
+    ```SQL
+    ALTER SYSTEM SET wal_level = 'logical';
+    ```
+
+1. Restart the source node Postgres service for the configuration change to take effect:
+
+    ```bash
+    su -u enterprisedb --command "pg_ctl restart"
+    ```
+
+1. After the restart, verify that the `wal_level` is correct and that there are sufficient replication slots and worker processes available. For a setup with **M** existing standbys and **N** future PGD nodes, ensure these parameters are at least what is indicated below:
+
+    ```SQL
+    SHOW wal_level;                         -- Expected 'logical'
+
+    SHOW max_replication_slots;             -- Must be at least M + N
+    SHOW max_wal_senders;                   -- Must be at least M + N
+    SHOW max_logical_replication_workers;   -- Must be at least N
+    ```
+
+## Allowing outbound logical replication
+
+Configure the source environment to permit external logical connections and establish the necessary authentication credentials for the migration stream.
+
+1. The source node requires a role with replication privileges to facilitate data migration. You can use an existing role or create a separate role, for example:
+
+    ```SQL
+    CREATE ROLE repl LOGIN NOSUPERUSER REPLICATION PASSWORD 'your_password_here';
+    ```
+
+    EDB recommends using a `.pgpass` file to manage credentials securely without including passwords in connection strings (DSNs). 
+
+1. Verify connectivity from the PGD nodes using the following command to ensure they can connect without interactive password entry:
+
+    ```bash
+    su -u enterprisedb -c "psql --no-password '${SOURCE_DSN} replication=1' \ 
+    --command 'IDENTIFY SYSTEM'"
+    ```
+
+    Ensure you test connectivity between the seed node and all future PGD nodes; this may require updating `pg_hba.conf` on the source node.
+
+## Preparing the seed node
+
+Install the same distribution and version of Postgres on the seed node to accommodate a physical backup. See [Installing EPAS](/epas/latest/installing/), [Installing PGE](/pge/latest/installing/), or [Installing Postgres](/supported-open-source/postgresql/installing/) for details.
+
+!!! Note
+    Don't install EFM on the seed node, as it must be managed manually during the migration.
+
+## Creating a physical backup
+
+Once the source is configured, execute the following command from the seed node to pull a physical snapshot of the database from the source node. Ensure the destination `${PGDATA}` directory does not exist before starting the transfer.
+
+```bash
+su -u enterprisedb -c "pg_basebackup '${SOURCE_DSN}'    \
+  --pgdata=$(PGDATA)                                    \
+  --write-recovery-conf                                 \
+  --wal-method=stream                                   \
+  --create-slot                                         \
+  --slot=migration_phy_slot                             \
+  --progress                                            \
+  --verbose"
+```
+
+This command uses a spread checkpoint by default to minimize the I/O impact on the source node. For faster transfers at the cost of higher disk I/O, you can append `--checkpoint=fast`.
+
+The transfer duration depends on the total volume of data and the network bandwidth between the source and seed nodes. For environments with limited bandwidth, you can enable compression using the `--compress-level=[0-9]` flag to optimize the transfer speed; refer to the official [pg_basebackup documentation](https://www.postgresql.org/docs/14/app-pgbasebackup.html) for detailed configuration options.
+
+## Configuring and starting the seed node
+
+1. Once the transfer is complete, adjust the seed node's `postgresql.conf` and `pg_hba.conf` to reflect its local environment (hostnames, IP addresses, and paths). Validate that the replication settings on the seed node match the requirements for PGD:
+
+    ```SQL
+    SHOW wal_level;                         -- Expected: 'logical'
+    SHOW max_replication_slots;             -- Should be at least M + N
+    SHOW max_wal_senders;                   -- Should be at least M + N
+    SHOW max_logical_replication_workers;   -- Should be at least N
+    ```
+
+1. Start the database on the seed node to initiate streaming:
+
+    ```bash
+    su -u enterprisedb --command "pg_ctl start"
+    ```
+
+## Verifying physical replication
+
+Monitor the replication status from both the source and seed nodes to ensure they are synchronized.
+
+On the source node:
+
+1. Check the migration slot status. It must show the slot assigned to the seed node with a low or decreasing `lag_size`:
+
+    ```SQL
+    SELECT slot_name, active, restart_lsn, confirmed_flush_lsn, 
+            pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS lag_size
+    FROM pg_replication_slots
+    WHERE slot_name = 'migration_phy_slot';
+    ```
+
+1. Verify active connections. Confirm that the seed node's IP address appears in the replication statistics:
+
+    ```sql
+    SELECT client_addr, state, sent_lsn, write_lsn, flush_lsn, replay_lsn,
+            pg_size_pretty(pg_wal_lsn_diff(sent_lsn, replay_lsn)) AS replay_lag
+    FROM pg_stat_replication;
+    ```
+
+On the seed node:
+
+1. Confirm the recovery mode. The node must be correctly acting as a standby:
+
+    ```sql
+    SELECT pg_is_in_recovery();             -- Must return true
+    ```
+
+1. Verify the WAL receiver status. Check the health of the connection to the primary (source node):
+
+    ```sql
+    SELECT slot_name, sender_host || ':' || sender_port AS sender, status,
+    now() - last_msg_send_time    AS last_msg_send_age,
+    now() - last_msg_receipt_time AS last_msg_receipt_age,
+    now() - latest_end_time       AS last_end_age,
+    pg_size_pretty(pg_wal_lsn_diff(latest_end_lsn, written_lsn)) AS write_lag_size,
+    pg_size_pretty(pg_wal_lsn_diff(latest_end_lsn, flushed_lsn)) AS flush_lag_size
+    FROM pg_stat_wal_receiver;
+    ```
+
+1. Compare receive vs. replay position. This identifies the replay lag — the amount of data received but not yet applied to the database:
+
+    ```sql
+    SELECT pg_size_pretty(pg_wal_lsn_diff(pg_last_wal_receive_lsn(),
+                                        pg_last_wal_replay_lsn())) AS lag_bytes;
+    ```
+
+1. Monitor lag by time. Measure the time difference between the current time and the last replayed transition:
+
+    ```sql
+    SELECT EXTRACT(EPOCH FROM (now() - pg_last_xact_replay_timestamp())) AS lag_seconds;
+    ```
+
+Next step: [Convert to logical replication](3-convert-to-logical-replication).

product_docs/docs/pgd/6.2/lifecycle/migrating/migration-psr/3-convert-to-logical-replication.mdx

@@ -0,0 +1,114 @@
+---
+title: Converting to logical replication
+navTitle: Converting to logical replication
+description: Transitioning the seed node from physical to logical replication.
+---
+
+To facilitate a major version upgrade of your Postgres distribution and the subsequent installation of Postgres Distributed (PGD), you must convert the replication stream to the seed node to logical replication. For a seamless transition without data loss, logical replication must resume at the exact Log Sequence Number (LSN) within the WAL stream of the source node where physical replication was interrupted. This is known as the switch-over LSN.
+
+## Creating a publication on the source node
+
+Prepare the source node by defining which data will be replicated and creating a dedicated slot to hold WAL files.
+
+1. Create a publication for all tables in the database:
+
+    ```SQL
+    CREATE PUBLICATION migration_seed_pub FOR ALL TABLES;
+    ```
+
+1. Verify the publications:
+
+    ```sql
+    SELECT * FROM pg_publication;
+    SELECT * FROM pg_publication_tables;
+    ```
+
+1. Create a logical replication slot:
+
+    ```sql
+    SELECT pg_create_logical_replication_slot('migration_node_${SEED_NODE_NAME}', 'pgoutput');
+    ```
+
+    Creating the slot at this stage ensures that the source node begins retaining the necessary WAL data before the switch-over operation. Because the source node will eventually support multiple PGD nodes, each slot is named specifically to identify the target node it serves.
+
+## Promoting the seed node
+
+Promoting the seed node stops the incoming physical replication stream and converts the node into a standalone, writable instance.
+
+!!! Warning
+    To maintain data integrity, you must prevent any application writes to the seed node at this stage. Applications should continue to write exclusively to the source node.
+
+On the seed node, run the following command:
+
+```bash
+su -u enterprisedb --command "pg_ctl promote"
+```
+
+## Enabling logical replication to the seed node
+
+After promotion, you must align the new logical replication slot with the point where physical replication ended.
+
+1.  On the seed node, identify the last LSN replayed from the physical stream:
+
+    ```sql
+    SELECT pg_last_wal_replay_lsn();
+    ```
+
+1.  On the source node, manually move the logical slot forward to that LSN. Replace `${SWITCH_OVER_LSN}` with the value retrieved from the step above.
+
+    ```sql
+    SELECT pg_replication_slot_advance('migration_node_${SEED_NODE_NAME}', '${SWITCH_OVER_LSN}');
+    ```
+
+1. Create a logical subscription on the seed node:
+
+    ```SQL
+    CREATE SUBSCRIPTION migration_seed_sub
+            CONNECTION '${SOURCE_DSN}'
+            PUBLICATION migration_seed_pub
+                WITH (
+                    enabled = false,
+                    copy_data = false,
+                    create_slot = false,
+                    slot_name = 'migration_node_${SEED_NODE_NAME}'
+                    );
+    ```
+
+1. Verify that the subscription has correctly identified the tables for replication:
+
+    ```sql
+    SELECT n.nspname AS schemaname,
+        c.relname AS tablename,
+        sr.srsubstate AS state,
+        s.subname AS subscription_name
+    FROM pg_subscription_rel sr
+    JOIN pg_class c ON sr.srrelid = c.oid
+    JOIN pg_namespace n ON c.relnamespace = n.oid
+    JOIN pg_subscription s ON sr.srsubid = s.oid
+    WHERE s.subname = 'migration_seed_sub'
+    ORDER BY n.nspname, c.relname;
+    ```
+
+1. Enable logical replication:
+
+    ```SQL
+    ALTER SUBSCRIPTION migration_seed_sub ENABLE;
+    ```
+
+## Cleaning up physical replication
+
+1. Once the logical stream is verified and active, run the following command on the source node to remove the legacy physical replication components and free up resources:
+
+    ```SQL
+    SELECT pg_drop_replication_slot('migration_phy_slot');
+    ```
+
+1. On the seed node, run the following commands to remove any remaining configuration parameters for physical replication:
+
+    ```SQL
+    ALTER SYSTEM RESET primary_conninfo;
+    ALTER SYSTEM RESET primary_slot_name;
+    ```
+
+
+Next step: [Upgrade the seed node](4-upgrade-seed-node).