Add guide for Upgrading from PostgreSQL to IvorySQL

jiaoshuntian · jiaoshuntian · commit c3a5a528d78f · 2026-03-18T18:24:48.000+08:00
diff --git a/CN/modules/ROOT/pages/4.4.adoc b/CN/modules/ROOT/pages/4.4.adoc
@@ -153,6 +153,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版本
 
diff --git a/EN/modules/ROOT/pages/4.4.adoc b/EN/modules/ROOT/pages/4.4.adoc
@@ -143,6 +143,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 {ivorysql-version} is based on PostgreSQL {pg-version}, 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]。
