From 010b86e9bd8e3734e1488e8962c0b99e06bf500b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=A8=E9=A2=96?=
 <yangying9498@yangyingdeMacBook-Pro.local>
Date: Mon, 3 Mar 2025 16:13:08 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pg_upgrade_CH.md | 202 +++++++++++++++++++++++++++++++++++++++++++++++
 pg_upgrade_EN.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 401 insertions(+)
 create mode 100644 pg_upgrade_CH.md
 create mode 100644 pg_upgrade_EN.md

diff --git a/pg_upgrade_CH.md b/pg_upgrade_CH.md
new file mode 100644
index 00000000000..1aab775f4e1
--- /dev/null
+++ b/pg_upgrade_CH.md
@@ -0,0 +1,202 @@
+
+
+---
+
+# PostgreSQL 数据库升级工具
+
+`pg_upgrade` 是 PostgreSQL 提供的一个用于升级数据库集群的工具。它允许用户将 PostgreSQL 数据库从一个主版本升级到另一个主版本，而无需进行其他耗时的数据转储和恢复操作。
+
+---
+
+## 目录
+1. [简介](#简介)
+2. [使用前提](#使用前提)
+3. [升级步骤](#升级步骤)
+4. [升级模式](#升级模式)
+5. [注意事项](#注意事项)
+6. [常见问题](#常见问题)
+7. [参考文档](#参考文档)
+
+---
+
+## 简介
+`pg_upgrade` 是一个用于升级 PostgreSQL 数据库集群的工具。它通过直接升级数据文件的方式，避免了传统的数据转储和恢复的过程，从而显著提升了升级效率。
+
+### 主要特点
+- 支持跨主要版本的升级（例如，从 PostgreSQL 13 升级到 PostgreSQL 14）。
+- 支持原地升级（in-place upgrade）和链接模式升级（link mode）。
+- 保留数据库集群的配置和数据完整性。
+
+---
+
+## 使用前提
+在使用 `pg_upgrade` 之前，请确保升级环境已满足以下条件：
+1. **版本兼容性**：源集群和目标集群的 PostgreSQL 版本必须是相邻的主要版本（例如，13.x 到 14.x）。
+2. **数据目录**：源集群和目标集群的数据目录必须位于不同的位置。
+3. **扩展兼容性**：确保所有已安装的扩展在新版本中可用且兼容。
+4. **备份**：在升级前，务必对源集群进行完整备份。
+5. **停止服务**：升级过程中，源集群和目标集群必须停止运行。
+
+---
+
+## 升级步骤
+以下是使用 `pg_upgrade` 进行升级的基本步骤：
+
+### 1. 安装新版本 PostgreSQL
+安装目标版本的 PostgreSQL，并确保 `pg_upgrade` 工具可用。
+
+```bash
+# 示例：安装 PostgreSQL 14
+sudo apt-get install postgresql-14
+```
+
+### 2. 初始化新集群
+初始化一个新的 PostgreSQL 集群作为目标集群。
+
+```bash
+# 初始化新集群
+/usr/lib/postgresql/14/bin/initdb -D /path/to/new/data
+```
+
+### 3. 停止源集群和目标集群
+确保源集群和目标集群都已停止。
+
+```bash
+# 停止源集群
+pg_ctl -D /path/to/old/data stop
+
+# 停止目标集群
+pg_ctl -D /path/to/new/data stop
+```
+
+### 4. 运行 `pg_upgrade`
+使用 `pg_upgrade` 工具进行升级。
+
+```bash
+# 运行 pg_upgrade
+/usr/lib/postgresql/14/bin/pg_upgrade \
+  -b /usr/lib/postgresql/13/bin \  # 旧版本的二进制文件路径
+  -B /usr/lib/postgresql/14/bin \  # 新版本的二进制文件路径
+  -d /path/to/old/data \           # 旧集群的数据目录
+  -D /path/to/new/data             # 新集群的数据目录
+```
+
+### 5. 检查升级结果
+升级完成后，检查日志文件以确保没有错误。
+
+```bash
+less /path/to/new/data/pg_upgrade_server.log
+```
+
+### 6. 启动新集群
+启动升级后的新集群。
+
+```bash
+pg_ctl -D /path/to/new/data start
+```
+
+---
+
+## 升级模式
+`pg_upgrade` 支持两种升级模式：
+
+### 1. **拷贝模式（Copy Mode）**
+- 默认模式。
+- 将旧集群的数据文件复制到新集群中。
+- 需要额外的磁盘空间来存储副本。
+
+### 2. **链接模式（Link Mode）**
+- 使用硬链接来共享数据文件，避免复制数据。
+- 节省磁盘空间，但要求源集群和目标集群位于同一文件系统上。
+- 启用方式：在 `pg_upgrade` 命令中添加 `--link` 参数。
+
+```bash
+pg_upgrade --link ...
+```
+
+---
+
+## 注意事项
+1. **扩展兼容性**：某些扩展可能不兼容新版本，需手动更新或重新安装。
+2. **配置文件**：`pg_upgrade` 不会自动迁移配置文件（如 `postgresql.conf` 和 `pg_hba.conf`），需手动复制。
+3. **权限**：确保运行 `pg_upgrade` 的用户具有足够的权限访问源集群和目标集群。
+4. **测试**：在生产环境升级前，建议在测试环境中进行验证。
+
+---
+
+## 常见问题
+
+### 1. 升级失败怎么办？
+- 检查日志文件（`pg_upgrade_server.log` 和 `pg_upgrade_utility.log`）以获取错误信息。
+- 恢复备份并重新尝试升级。
+
+### 2. 如何回滚升级？
+- 如果升级失败，可以恢复备份的旧集群数据目录，并重新启动旧版本的 PostgreSQL。
+
+### 3. 是否支持跨多个主要版本升级？
+- 不支持。`pg_upgrade` 仅支持相邻的主要版本升级（例如，13.x 到 14.x）。如果需要跨多个版本升级，需逐步进行。
+
+---
+
+## 参考文档
+- [PostgreSQL 官方文档 - pg_upgrade](https://www.postgresql.org/docs/14/pgupgrade.html)
+- [PostgreSQL 升级指南](https://www.postgresql.org/docs/current/upgrading.html)
+
+---
+
+通过以上步骤和注意事项，您可以顺利使用 `pg_upgrade` 工具升级 PostgreSQL 数据库集群。
+
+---
+
+## 详细说明
+
+### 1. **升级前的准备工作**
+在升级之前，请确保完成以下准备工作：
+- 备份所有数据。
+- 检查所有扩展的兼容性。
+- 确保源集群和目标集群的数据目录位于不同的位置。
+
+### 2. **升级后的清理工作**
+升级完成后，您可以删除旧集群的数据目录以释放磁盘空间。但在此之前，请确保新集群运行正常。
+
+```bash
+# 删除旧集群数据目录
+rm -rf /path/to/old/data
+```
+
+### 3. **日志文件**
+`pg_upgrade` 会生成以下日志文件：
+- `pg_upgrade_server.log`：服务器日志。
+- `pg_upgrade_utility.log`：工具日志。
+
+检查这些日志文件以确认升级是否成功。
+
+---
+
+## 示例
+
+以下是一个完整的升级示例：
+
+```bash
+# 停止旧集群
+pg_ctl -D /var/lib/postgresql/13/data stop
+
+# 初始化新集群
+/usr/lib/postgresql/14/bin/initdb -D /var/lib/postgresql/14/data
+
+# 运行 pg_upgrade
+/usr/lib/postgresql/14/bin/pg_upgrade \
+  -b /usr/lib/postgresql/13/bin \
+  -B /usr/lib/postgresql/14/bin \
+  -d /var/lib/postgresql/13/data \
+  -D /var/lib/postgresql/14/data
+
+# 启动新集群
+pg_ctl -D /var/lib/postgresql/14/data start
+```
+
+---
+
+通过遵循本指南，您可以顺利完成 PostgreSQL 数据库的升级。如有疑问，请参考 [PostgreSQL 官方文档](https://www.postgresql.org/docs/14/pgupgrade.html)。
+
+--- 
diff --git a/pg_upgrade_EN.md b/pg_upgrade_EN.md
new file mode 100644
index 00000000000..5745df3d94c
--- /dev/null
+++ b/pg_upgrade_EN.md
@@ -0,0 +1,199 @@
+
+#  PostgreSQL Database Upgrade Tool
+
+`pg_upgrade` is a tool provided by PostgreSQL for upgrading database clusters. It allows users to upgrade a PostgreSQL database from one major version to another without the need for time-consuming data dump and restore operations.
+
+---
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Prerequisites](#prerequisites)
+3. [Upgrade Steps](#upgrade-steps)
+4. [Upgrade Modes](#upgrade-modes)
+5. [Important Notes](#important-notes)
+6. [Frequently Asked Questions](#frequently-asked-questions)
+7. [References](#references)
+
+---
+
+## Introduction
+`pg_upgrade` is a tool for upgrading PostgreSQL database clusters. It upgrades data files directly, avoiding the traditional data dump and restore process, significantly reducing upgrade time.
+
+### Key Features
+- Supports upgrading between major versions (e.g., from PostgreSQL 13 to PostgreSQL 14).
+- Supports in-place upgrades and link mode upgrades.
+- Preserves database cluster configurations and data integrity.
+
+---
+
+## Prerequisites
+Before using `pg_upgrade`, ensure the following conditions are met:
+1. **Version Compatibility**: The source and target clusters must be adjacent major versions (e.g., 13.x to 14.x).
+2. **Data Directories**: The data directories of the source and target clusters must be in different locations.
+3. **Extension Compatibility**: Ensure all installed extensions are available and compatible with the new version.
+4. **Backup**: Perform a full backup of the source cluster before upgrading.
+5. **Stop Services**: Both the source and target clusters must be stopped during the upgrade.
+
+---
+
+## Upgrade Steps
+Below are the basic steps to upgrade using `pg_upgrade`:
+
+### 1. Install the New PostgreSQL Version
+Install the target version of PostgreSQL and ensure the `pg_upgrade` tool is available.
+
+```bash
+# Example: Install PostgreSQL 14
+sudo apt-get install postgresql-14
+```
+
+### 2. Initialize the New Cluster
+Initialize a new PostgreSQL cluster as the target cluster.
+
+```bash
+# Initialize the new cluster
+/usr/lib/postgresql/14/bin/initdb -D /path/to/new/data
+```
+
+### 3. Stop the Source and Target Clusters
+Ensure both the source and target clusters are stopped.
+
+```bash
+# Stop the source cluster
+pg_ctl -D /path/to/old/data stop
+
+# Stop the target cluster
+pg_ctl -D /path/to/new/data stop
+```
+
+### 4. Run `pg_upgrade`
+Use the `pg_upgrade` tool to perform the upgrade.
+
+```bash
+# Run pg_upgrade
+/usr/lib/postgresql/14/bin/pg_upgrade \
+  -b /usr/lib/postgresql/13/bin \  # Path to the old version's binaries
+  -B /usr/lib/postgresql/14/bin \  # Path to the new version's binaries
+  -d /path/to/old/data \           # Data directory of the old cluster
+  -D /path/to/new/data             # Data directory of the new cluster
+```
+
+### 5. Check the Upgrade Results
+After the upgrade, check the log files to ensure there are no errors.
+
+```bash
+less /path/to/new/data/pg_upgrade_server.log
+```
+
+### 6. Start the New Cluster
+Start the upgraded new cluster.
+
+```bash
+pg_ctl -D /path/to/new/data start
+```
+
+---
+
+## Upgrade Modes
+`pg_upgrade` supports two upgrade modes:
+
+### 1. **Copy Mode**
+- The default mode.
+- Copies data files from the old cluster to the new cluster.
+- Requires additional disk space for the copy.
+
+### 2. **Link Mode**
+- Uses hard links to share data files, avoiding data duplication.
+- Saves disk space but requires the source and target clusters to be on the same file system.
+- Enable by adding the `--link` parameter to the `pg_upgrade` command.
+
+```bash
+pg_upgrade --link ...
+```
+
+---
+
+## Important Notes
+1. **Extension Compatibility**: Some extensions may not be compatible with the new version and may need to be updated or reinstalled manually.
+2. **Configuration Files**: `pg_upgrade` does not automatically migrate configuration files (e.g., `postgresql.conf` and `pg_hba.conf`). These must be copied manually.
+3. **Permissions**: Ensure the user running `pg_upgrade` has sufficient permissions to access the source and target clusters.
+4. **Testing**: Before upgrading in a production environment, test the upgrade in a staging environment.
+
+---
+
+## Frequently Asked Questions
+
+### 1. What if the upgrade fails?
+- Check the log files (`pg_upgrade_server.log` and `pg_upgrade_utility.log`) for error messages.
+- Restore from the backup and retry the upgrade.
+
+### 2. How to roll back the upgrade?
+- If the upgrade fails, restore the backup of the old cluster's data directory and restart the old version of PostgreSQL.
+
+### 3. Does it support upgrading across multiple major versions?
+- No. `pg_upgrade` only supports upgrading between adjacent major versions (e.g., 13.x to 14.x). To upgrade across multiple versions, perform the upgrades step-by-step.
+
+---
+
+## References
+- [PostgreSQL Official Documentation - pg_upgrade](https://www.postgresql.org/docs/14/pgupgrade.html)
+- [PostgreSQL Upgrade Guide](https://www.postgresql.org/docs/current/upgrading.html)
+
+---
+
+By following the steps and notes above, you can successfully use the `pg_upgrade` tool to upgrade your PostgreSQL database cluster.
+
+---
+
+## Detailed Instructions
+
+### 1. **Pre-Upgrade Preparation**
+Before upgrading, ensure the following preparations are complete:
+- Back up all data.
+- Check the compatibility of all extensions.
+- Ensure the source and target cluster data directories are in different locations.
+
+### 2. **Post-Upgrade Cleanup**
+After the upgrade, you can delete the old cluster's data directory to free up disk space. However, ensure the new cluster is running correctly before doing so.
+
+```bash
+# Delete the old cluster's data directory
+rm -rf /path/to/old/data
+```
+
+### 3. **Log Files**
+`pg_upgrade` generates the following log files:
+- `pg_upgrade_server.log`: Server logs.
+- `pg_upgrade_utility.log`: Tool logs.
+
+Check these log files to confirm the success of the upgrade.
+
+---
+
+## Example
+
+Below is a complete upgrade example:
+
+```bash
+# Stop the old cluster
+pg_ctl -D /var/lib/postgresql/13/data stop
+
+# Initialize the new cluster
+/usr/lib/postgresql/14/bin/initdb -D /var/lib/postgresql/14/data
+
+# Run pg_upgrade
+/usr/lib/postgresql/14/bin/pg_upgrade \
+  -b /usr/lib/postgresql/13/bin \
+  -B /usr/lib/postgresql/14/bin \
+  -d /var/lib/postgresql/13/data \
+  -D /var/lib/postgresql/14/data
+
+# Start the new cluster
+pg_ctl -D /var/lib/postgresql/14/data start
+```
+
+---
+
+By following this guide, you can successfully upgrade your PostgreSQL database. For further questions, refer to the [PostgreSQL Official Documentation](https://www.postgresql.org/docs/14/pgupgrade.html).
+
+---