Add pg_upgrade doc EN&CN #245
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hiiii, @YYbupt8 welcome!🎊 Thanks for taking the effort to make our project better! 🙌 Keep making such awesome contributions!
|
|
||
| --- | ||
|
|
||
| ## 详细说明 |
There was a problem hiding this comment.
文档整体结构逻辑顺序混乱。上面部分的内容已经闭环了（使用前提、升级步骤、升级模式等等），下面部分又重新介绍升级前的准备工作和升级后的清理工作，还给出了示例。请确保文档整体结构逻辑通顺，且相同的内容不反复出现。
|
|
||
| --- | ||
|
|
||
| 通过遵循本指南，您可以顺利完成 PostgreSQL 数据库的升级。如有疑问，请参考 [PostgreSQL 官方文档](https://www.postgresql.org/docs/14/pgupgrade.html)。 |
There was a problem hiding this comment.
上面第 142 行已经提到这个参考链接了，无需再重复。
| ### 1. **升级前的准备工作** | ||
| 在升级之前，请确保完成以下准备工作： | ||
| - 备份所有数据。 | ||
| - 检查所有扩展的兼容性。 | ||
| - 确保源集群和目标集群的数据目录位于不同的位置。 |
|
|
||
| # PostgreSQL 数据库升级工具 | ||
|
|
||
| `pg_upgrade` 是 PostgreSQL 提供的一个用于升级数据库集群的工具。它允许用户将 PostgreSQL 数据库从一个主版本升级到另一个主版本，而无需进行其他耗时的数据转储和恢复操作。 |
There was a problem hiding this comment.
产品名不正确。Apache Cloudberry 基于 PostgreSQL 内核开发，继承了 PG 的一些功能，但是在 Apache Cloudberry 的文档中，需要正确书写产品名。
| ## 升级模式 | ||
| `pg_upgrade` 支持两种升级模式： | ||
|
|
||
| ### 1. **拷贝模式（Copy Mode）** | ||
| - 默认模式。 | ||
| - 将旧集群的数据文件复制到新集群中。 | ||
| - 需要额外的磁盘空间来存储副本。 | ||
|
|
||
| ### 2. **链接模式（Link Mode）** | ||
| - 使用硬链接来共享数据文件，避免复制数据。 | ||
| - 节省磁盘空间，但要求源集群和目标集群位于同一文件系统上。 | ||
| - 启用方式：在 `pg_upgrade` 命令中添加 `--link` 参数。 | ||
|
|
||
| ```bash | ||
| pg_upgrade --link ... | ||
| ``` |
There was a problem hiding this comment.
在升级操作前，用户需要了知不同的升级模式，并进行选择。建议调整内容顺序。
|
|
||
| ```bash | ||
| # 示例：安装 PostgreSQL 14 | ||
| sudo apt-get install postgresql-14 |
There was a problem hiding this comment.
说明一下适用的操作系统，因为这不是一条在所有操作系统上的通用命令。
| --- | ||
|
|
||
| ## 升级步骤 | ||
| 以下是使用 `pg_upgrade` 进行升级的基本步骤： |
There was a problem hiding this comment.
这部分「升级步骤」是示例还是基本步骤呢？如果是基本步骤，需要确保每一步命令具有通用性（目前不具有通用性）。如果是示例，请指出路径、版本等都是示例，执行时需要替换为实际的路径和版本。
| ## 升级步骤 | ||
| 以下是使用 `pg_upgrade` 进行升级的基本步骤： | ||
|
|
||
| ### 1. 安装新版本 PostgreSQL |
There was a problem hiding this comment.
”新“和”旧“是相对的，请明确指出从哪个版本升级到哪个版本，好让读者有正确的预期。
| 1. **扩展兼容性**：某些扩展可能不兼容新版本，需手动更新或重新安装。 | ||
| 2. **配置文件**：`pg_upgrade` 不会自动迁移配置文件（如 `postgresql.conf` 和 `pg_hba.conf`），需手动复制。 | ||
| 3. **权限**：确保运行 `pg_upgrade` 的用户具有足够的权限访问源集群和目标集群。 |
There was a problem hiding this comment.
考虑把这部分作为升级的前提条件并挪动到相应的位置。如果在操作前不知道这些注意事项，则无法升级成功。
|
|
||
| ## 常见问题 | ||
|
|
||
| ### 1. 升级失败怎么办？ |
| -B /usr/lib/postgresql/14/bin \ # 新版本的二进制文件路径 | ||
| -d /path/to/old/data \ # 旧集群的数据目录 | ||
| -D /path/to/new/data # 新集群的数据目录 | ||
| ``` |
There was a problem hiding this comment.
PostgreSQL 的 pg_upgrade 文档有单独介绍常见的参数。建议参考 PG 文档，单独用一个部分介绍常见的命令行参数。
| ```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 | ||
| ``` |
There was a problem hiding this comment.
这部分的升级步骤和第 42 - 96 行所写的步骤顺序是不同。请避免出现前后矛盾。
closes: #ISSUE_Number
Change logs
Contributor's checklist
Here are some reminders before you submit your pull request: