Add guide for Upgrading from PostgreSQL to IvorySQL

Author: jiaoshuntian

CN/modules/ROOT/pages/master/operation_guide.adoc

@@ -150,6 +150,114 @@ pg_upgrade https://www.postgresql.org/docs/current/pgupgrade.html[文档]概述
 
 这种升级方法可以用内置的逻辑复制工具和外部的逻辑复制系统如pglogical，Slony，Londiste，和Bucardo。
 
+== 使用 pg_upgrade 将 PostgreSQL 升级到 IvorySQL
+
+`pg_upgrade` 支持将原生 PostgreSQL 集群升级到 IvorySQL。当源集群为原生 PostgreSQL ，而目标为 IvorySQL 集群时，必须使用 `-g`（`--using-ora-pg`）参数。
+
+从 PostgreSQL 升级到 IvorySQL 属于“跨产品”迁移，建议在生产环境操作前完成完整的测试验证，并制定详细的回滚方案。
+
+=== 参数说明
+
+[cols="1,3"]
+|===
+| 参数 | 说明
+
+| `-g` / `--using-ora-pg`
+| 表示源集群为 PostgreSQL ，而目标为 IvorySQL 集群。启用此选项后，`pg_upgrade` 在连接两端集群时统一使用 PostgreSQL 标准端口，从而正确处理升级。
+|===
+
+=== 升级步骤
+
+==== 第一步：初始化新 IvorySQL 集群
+
+[source,bash]
+----
+# 使用 IvorySQL 的 initdb 初始化新集群
+/opt/ivorysql/bin/initdb -D /data/ivorysql/data
+
+# 停止新集群
+/opt/ivorysql/bin/pg_ctl -D /data/ivorysql/data stop
+----
+
+==== 第二步：停止源 PostgreSQL 集群
+
+[source,bash]
+----
+/usr/lib/postgresql/16/bin/pg_ctl -D /data/pg/data stop
+----
+
+==== 第三步：运行升级检查（可选）
+
+使用 `-c` 仅做兼容性检查，不修改任何数据：
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_upgrade \
+  -b /usr/lib/postgresql/16/bin \   # 源 PG 可执行文件目录
+  -B /opt/ivorysql/bin \            # 目标 IvorySQL 可执行文件目录
+  -d /data/pg/data \                # 源 PG 数据目录
+  -D /data/ivorysql/data \          # 目标 IvorySQL 数据目录
+  -g \                              # 源为 PostgreSQL，目标为 IvorySQL
+  -c                                # 仅检查，不升级
+----
+
+==== 第四步：执行升级
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_upgrade \
+  -b /usr/lib/postgresql/16/bin \
+  -B /opt/ivorysql/bin \
+  -d /data/pg/data \
+  -D /data/ivorysql/data \
+  -g
+----
+
+==== 第五步：启动 IvorySQL 并验证
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_ctl -D /data/ivorysql/data start
+
+# 验证数据库是否正常
+/opt/ivorysql/bin/psql -p 5433 -c "SELECT version();"
+----
+
+==== 第六步：清理旧集群
+
+升级完成后，`pg_upgrade` 会生成一个清理脚本：
+
+[source,bash]
+----
+./delete_old_cluster.sh
+----
+
+=== 常用参数速查
+
+[cols="1,2,2"]
+|===
+| 参数 | 长选项 | 说明
+
+| `-b` | `--old-bindir` | 源集群可执行文件目录
+| `-B` | `--new-bindir` | 目标集群可执行文件目录
+| `-d` | `--old-datadir` | 源集群数据目录
+| `-D` | `--new-datadir` | 目标集群数据目录
+| `-g` | `--using-ora-pg` | 源为 PostgreSQL 升级到 IvorySQL
+| `-p` | `--old-port` | 源集群端口
+| `-P` | `--new-port` | 目标集群 PG 端口
+| `-q` | `--old-oraport` | 源集群 Oracle 端口
+| `-Q` | `--new-oraport` | 目标集群 Oracle 端口
+| `-j` | `--jobs` | 并行进程数
+| `-k` | `--link` | 使用硬链接替代文件复制
+| `-c` | `--check` | 仅检查兼容性，不执行升级
+| `-v` | `--verbose` | 输出详细日志
+|===
+
+=== 注意事项
+
+* `-g` 参数仅在 **源为纯 PostgreSQL 集群**、目标为 **IvorySQL** 时使用。若源集群已是 IvorySQL，则无需此参数。
+* 升级期间源集群和目标集群均须处于停止状态。
+* 升级前务必对源集群做完整备份。
 
 == 管理IvorySQL版本
 

EN/modules/ROOT/pages/master/operation_guide.adoc

@@ -140,6 +140,115 @@ We can also create a fallback server using logical replication of an updated ver
 
 This upgrade method can be used with built-in logical replication tools and external logical replication systems such as pglogical, Slony, Londiste, and Bucardo.
 
+== Use pg_upgrade to upgrade PostgreSQL to IvorySQL
+
+`pg_upgrade` supports upgrading native PostgreSQL clusters to IvorySQL. When the source cluster is native PostgreSQL and the target is an IvorySQL cluster, the `-g`（`--using-ora-pg`）parameter must be used.
+
+Upgrading from PostgreSQL to IvorySQL is considered a "cross-product" migration. It is recommended to complete comprehensive testing and validation before performing the operation in a production environment, and to develop a detailed rollback plan.
+
+=== Parameter description
+
+[cols="1,3"]
+|===
+| parameter | description
+
+| `-g` / `--using-ora-pg`
+| Indicates that the source cluster is PostgreSQL and the target is an IvorySQL cluster. When this option is enabled, `pg_upgrade` uniformly uses the PostgreSQL standard port when connecting to both clusters, ensuring proper handling of the upgrade.
+|===
+
+=== Upgrade steps
+
+==== Step 1: Initialize the new IvorySQL cluster
+
+[source,bash]
+----
+# Use IvorySQL's initdb to initialize the new cluster
+/opt/ivorysql/bin/initdb -D /data/ivorysql/data
+
+# Stop the new cluster
+/opt/ivorysql/bin/pg_ctl -D /data/ivorysql/data stop
+----
+
+==== Step 2: Stop the source PostgreSQL cluster
+
+[source,bash]
+----
+/usr/lib/postgresql/16/bin/pg_ctl -D /data/pg/data stop
+----
+
+==== Step 3: Run the upgrade check (optional)
+
+Use `-c` to perform compatibility checks only without modifying any data:
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_upgrade \
+  -b /usr/lib/postgresql/16/bin \   # Source PG executable directory
+  -B /opt/ivorysql/bin \            # Target IvorySQL executable directory
+  -d /data/pg/data \                # Source PG data directory
+  -D /data/ivorysql/data \          # Target IvorySQL data directory
+  -g \                              # Source is PostgreSQL, target is IvorySQL
+  -c                                # Check only, do not upgrade
+----
+
+==== Step 4: Perform the upgrade
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_upgrade \
+  -b /usr/lib/postgresql/16/bin \
+  -B /opt/ivorysql/bin \
+  -d /data/pg/data \
+  -D /data/ivorysql/data \
+  -g
+----
+
+==== Step 5: Start IvorySQL and verify
+
+[source,bash]
+----
+/opt/ivorysql/bin/pg_ctl -D /data/ivorysql/data start
+
+# Verify if the database is functioning properly
+/opt/ivorysql/bin/psql -p 5433 -c "SELECT version();"
+----
+
+==== Step 6: Clean up the old cluster
+
+After the upgrade is completed,`pg_upgrade` will generate a cleanup script:
+
+[source,bash]
+----
+./delete_old_cluster.sh
+----
+
+=== Quick reference for common parameters
+
+[cols="1,2,2"]
+|===
+| Parameters | Long options | Description
+
+| `-b` | `--old-bindir` | Source cluster executable directory
+| `-B` | `--new-bindir` | Target cluster executable directory
+| `-d` | `--old-datadir` | Source cluster data directory
+| `-D` | `--new-datadir` | Target cluster data directory
+| `-g` | `--using-ora-pg` | Upgrade from PostgreSQL to IvorySQL
+| `-p` | `--old-port` | Source cluster port
+| `-P` | `--new-port` | Target cluster PG port
+| `-q` | `--old-oraport` | Source cluster Oracle port
+| `-Q` | `--new-oraport` | Target cluster Oracle port
+| `-j` | `--jobs` | Number of parallel processes
+| `-k` | `--link` | Use hard links instead of file copying
+| `-c` | `--check` | Check compatibility only, do not perform the upgrade
+| `-v` | `--verbose` | Output detailed logs
+|===
+
+=== Precautions
+
+* The `-g` parameter is only used when the **source is a pure PostgreSQL cluster**、and the target is **IvorySQL** . If the source cluster is already IvorySQL, this parameter is not needed.
+* Both the source and target clusters must be in a stopped state during the upgrade.
+* Be sure to perform a complete backup of the source cluster before upgrading.
+
 == Managing IvorySQL Versions
 
 IvorySQL is based on PostgreSQL and is updated at the same frequency as PostgreSQL, with one major release per year and one minor release per quarter. IvorySQL 5.0 is based on PostgreSQL 18.0, and all versions of IvorySQL are backward compatible.The relevant version features can be viewed by looking at https://www.ivorysql.org/en/releases-page/[Official Website]。