From d5b809e3ba6e92a1d7aa83fea1ff3e148b57e8af Mon Sep 17 00:00:00 2001
From: guanLouise <3072469381@qq.com>
Date: Thu, 9 Jan 2025 14:38:17 +0800
Subject: [PATCH] Add pg_upgrade documentation in English and Chinese

---
 docs/pg_upgrade-English.md                    | 68 ++++++++++++++++++
 .../current/pg_upgrade.md                     | 69 +++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 docs/pg_upgrade-English.md
 create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/pg_upgrade.md

diff --git a/docs/pg_upgrade-English.md b/docs/pg_upgrade-English.md
new file mode 100644
index 00000000000..39d127cf20f
--- /dev/null
+++ b/docs/pg_upgrade-English.md
@@ -0,0 +1,68 @@
+**Cloudberry System Tool: pg_upgrade**
+
+### Overview
+
+`pg_upgrade` is a tool used to upgrade a PostgreSQL database from one version to another without interrupting service. It allows the database to continue running during the upgrade process and supports upgrades from PostgreSQL 9.3 and later to the latest version.
+
+### Installation and Configuration
+
+`pg_upgrade` is typically installed as part of PostgreSQL. 
+
+1. **Install the New PostgreSQL Version**
+   - Download the latest version of PostgreSQL from the official PostgreSQL website or repository.
+   - Install the new version, ensuring that you have the necessary permissions and following the installation guide appropriate for your operating system.
+   
+1. **Install pg_upgrade**
+   
+   - `pg_upgrade` is included by default with the PostgreSQL installation. If you have installed PostgreSQL from source, make sure to include `pg_upgrade` in your installation.
+   - For custom installation locations, use the `prefix` variable during the installation process to specify the location:
+     ```
+     make prefix=/path/to/new/pgsql install
+
+### Usage
+
+To use `pg_upgrade` to upgrade a database, follow these steps:
+
+1. Stop the old version of the PostgreSQL server.
+
+2. Use the `pg_upgrade` command to perform the upgrade. For example:
+
+   ```
+     pg_upgrade -d /path/to/old/data -D /path/to/new/data -U postgres
+   ```
+
+   This will upgrade the database from the old version located at `/path/to/old/data` to the new version located at `/path/to/new/data`, using the `postgres` user for the upgrade.
+
+3. Start the new version of the PostgreSQL server.
+
+### Options
+
+Here are some common `pg_upgrade` options:
+
+- `-d` or `--old-datadir`: Specify the path to the old version database data directory.
+- `-D` or `--new-datadir`: Specify the path to the new version database data directory.
+- `-U` or `--username`: Specify the database username to use for the upgrade.
+- `-v` or `--verbose`: Increase the level of detail in the output.
+- `-k` or `--keep-old`: Keep the old version data directory after the upgrade.
+- `-l` or `--link`: Use hard links instead of copying files to speed up the upgrade process.
+- `-o` or `--old-bindir`: Specify the binary file directory of the old version PostgreSQL.
+- `-n` or `--new-bindir`: Specify the binary file directory of the new version PostgreSQL.
+
+### Notes
+
+- Before upgrading, ensure that all database connections are closed.
+- During the upgrade process, you need to have enough disk space to store the new version database files.
+- `pg_upgrade` does not support cross-architecture upgrades, such as from 32-bit to 64-bit or vice versa.
+- If you use third-party plugins or extensions, you may need to reinstall or upgrade them.
+
+### Result Interpretation
+
+After the upgrade is complete, `pg_upgrade` will display a success message. If an error occurs during the upgrade process, the tool will report the corresponding error information.
+
+### Reference
+
+For more information about `pg_upgrade`, refer to the PostgreSQL official documentation: https://www.postgresql.org/docs/14/pgupgrade.html
+
+### Conclusion
+
+`pg_upgrade` is a powerful tool that allows users to upgrade their PostgreSQL database from one version to another without interrupting service. By following the correct steps and notes, users can successfully complete the upgrade process and ensure the safety and reliability of their database.
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/pg_upgrade.md b/i18n/zh/docusaurus-plugin-content-docs/current/pg_upgrade.md
new file mode 100644
index 00000000000..2598edbc4a8
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/pg_upgrade.md
@@ -0,0 +1,69 @@
+**Cloudberry 系统工具：pg_upgrade**
+
+### 概述
+
+`pg_upgrade` 是一个用于在不中断服务的情况下将 Apache Cloudberry 数据库从一个版本升级到另一个版本的工具。它可以在升级过程中保持数据库运行，并且支持从 PostgreSQL 9.3 及更高版本到最新版本的升级。
+
+### 安装和配置
+
+`pg_upgrade` 通常作为 PostgreSQL 的一部分进行安装。
+
+1. **安装新版本的 PostgreSQL**
+   - 从官方 PostgreSQL 网站或仓库下载最新版本的 PostgreSQL。
+   - 安装新版本，确保您具有必要的权限，并遵循适合您的操作系统的安装指南。
+   
+1. **安装 pg_upgrade**
+   
+   - `pg_upgrade` 默认包含在 PostgreSQL 安装中。如果您是从源代码安装 PostgreSQL，请确保在安装中包含 `pg_upgrade`。
+   - 对于自定义安装位置，请在安装过程中使用 `prefix` 变量指定位置：
+     ```
+     make prefix=/path/to/new/pgsql install
+     ```
+
+### 使用
+
+要使用 `pg_upgrade` 升级数据库，需要执行以下步骤：
+
+1. 停止旧版本的 PostgreSQL 服务器。
+
+2. 使用 `pg_upgrade` 命令进行升级。例如：
+
+   ```
+     pg_upgrade -d /path/to/old/data -D /path/to/new/data -U postgres
+   ```
+
+   这将从 `/path/to/old/data` 中的旧版本数据库升级到 `/path/to/new/data` 中的新版本数据库，并使用 `postgres` 用户进行升级。
+
+3. 启动新版本的 PostgreSQL 服务器。
+
+### 选项
+
+以下是一些常用的 `pg_upgrade` 选项：
+
+- `-d` 或 `--old-datadir`：指定旧版本数据库数据目录的路径。
+- `-D` 或 `--new-datadir`：指定新版本数据库数据目录的路径。
+- `-U` 或 `--username`：指定用于升级的数据库用户名。
+- `-v` 或 `--verbose`：增加输出的详细程度。
+- `-k` 或 `--keep-old`：在升级后保留旧版本的数据目录。
+- `-l` 或 `--link`：使用硬链接而不是复制文件来加速升级过程。
+- `-o` 或 `--old-bindir`：指定旧版本 PostgreSQL 的二进制文件目录。
+- `-n` 或 `--new-bindir`：指定新版本 PostgreSQL 的二进制文件目录。
+
+### 注意事项
+
+- 在升级之前，确保所有的数据库连接都已关闭。
+- 在进行升级时，需要有足够的磁盘空间来存储新版本的数据库文件。
+- `pg_upgrade` 不支持跨架构升级，例如从 32 位到 64 位或反之。
+- 如果您使用了第三方插件或扩展，可能需要重新安装或升级它们。
+
+### 结果解释
+
+升级完成后，`pg_upgrade` 将显示一条成功消息。如果升级过程中出现错误，工具将报告相应的错误信息。
+
+### 参考资料
+
+更多关于 `pg_upgrade` 的信息可以在 PostgreSQL 官方文档中找到：https://www.postgresql.org/docs/14/pgupgrade.html
+
+### 结论
+
+`pg_upgrade` 是一个强大的工具，可以帮助用户在不中断服务的情况下将 PostgreSQL 数据库从一个版本升级到另一个版本。通过遵循正确的步骤和注意事项，用户可以顺利完成升级过程，并确保数据库的安全和可靠性。
\ No newline at end of file