diff --git a/CN/modules/ROOT/pages/4.4.adoc b/CN/modules/ROOT/pages/4.4.adoc index c154503..0c5e008 100644 --- a/CN/modules/ROOT/pages/4.4.adoc +++ b/CN/modules/ROOT/pages/4.4.adoc @@ -153,6 +153,111 @@ 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 +---- + +==== 第二步：停止源 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 5432 -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 index b080eb3..43215cd 100644 --- a/EN/modules/ROOT/pages/4.4.adoc +++ b/EN/modules/ROOT/pages/4.4.adoc @@ -143,6 +143,112 @@ 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 +---- + +==== 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 5432 -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]。