docker-postgres-upgrade实战：10分钟完成PostgreSQL数据库升级

【免费下载链接】docker-postgres-upgrade a PoC for using "pg_upgrade" inside Docker -- learn from it, adapt it for your needs; don't expect it to work as-is! 项目地址: https://gitcode.com/gh_mirrors/do/docker-postgres-upgrade

docker-postgres-upgrade是一个基于Docker的PostgreSQL数据库升级工具，它利用pg_upgrade命令在容器环境中实现PostgreSQL版本间的快速迁移。本文将详细介绍如何使用这个工具在10分钟内安全高效地完成PostgreSQL数据库的升级工作。

📌 为什么选择docker-postgres-upgrade？

PostgreSQL数据库升级通常是一个复杂且耗时的过程，涉及数据备份、兼容性检查、数据迁移等多个步骤。而docker-postgres-upgrade通过容器化方式，将整个升级过程标准化、自动化，大大降低了操作难度和时间成本。

该工具支持多种版本组合的升级路径，从versions.json文件中可以看到，目前支持从PostgreSQL 14到15、16、17、18等多个版本的升级，以及15到16、17、18等跨版本升级。

📋 升级前的准备工作

在开始升级前，请确保你已经：

1. 对当前数据库进行完整备份
2. 确认目标PostgreSQL版本与应用程序兼容
3. 安装并配置好Docker环境

升级前的目录结构建议如下（以从17升级到18为例）：

/mnt/bigdrive/postgresql/
├── 17/
│   └── docker/
└── 18/
    └── docker/

⚡ 快速升级步骤

步骤1：克隆项目仓库

首先，克隆项目到本地：

git clone https://gitcode.com/gh_mirrors/do/docker-postgres-upgrade
cd docker-postgres-upgrade

步骤2：停止当前PostgreSQL容器

确保旧版本的PostgreSQL容器已停止：

docker stop postgres-container
docker rm postgres-container

步骤3：执行升级命令

使用以下命令启动升级容器，这里以从PostgreSQL 17升级到18为例：

docker run --rm \
  --mount 'type=bind,src=/mnt/bigdrive/postgresql,dst=/var/lib/postgresql' \
  --env 'PGDATAOLD=/var/lib/postgresql/17/docker' \
  --env 'PGDATANEW=/var/lib/postgresql/18/docker' \
  tianon/postgres-upgrade:17-to-18 \
  --link

--link参数用于创建硬链接而非复制数据文件，可显著提高升级速度。

步骤4：启动新版本PostgreSQL

升级完成后，启动新版本的PostgreSQL容器：

docker run -dit \
  --name postgres-container \
  --env POSTGRES_PASSWORD='password' \
  --mount 'type=bind,src=/mnt/bigdrive/postgresql,dst=/var/lib/postgresql' \
  --env PGDATA="/var/lib/postgresql/18/docker" \
  postgres:18

步骤5：验证升级结果

检查容器日志确认升级成功：

docker logs --tail 100 postgres-container

📝 替代升级方案

如果你的目录结构不符合上述要求，可以使用另一种挂载方式（性能会略低）：

docker run --rm \
  --mount 'type=bind,src=/path/to/old/data,dst=/var/lib/postgresql/OLD/docker' \
  --mount 'type=bind,src=/path/to/new/data,dst=/var/lib/postgresql/NEW/docker' \
  --env 'PGDATAOLD=/var/lib/postgresql/OLD/docker' \
  --env 'PGDATANEW=/var/lib/postgresql/NEW/docker' \
  tianon/postgres-upgrade:OLD-to-NEW

🔍 升级脚本解析

升级的核心逻辑在docker-upgrade脚本中实现，主要流程包括：

1. 检查命令参数并准备环境
2. 创建并设置数据目录权限
3. 初始化新数据库（如果需要）
4. 执行pg_upgrade命令进行升级

关键代码片段：

if [ "$1" = 'pg_upgrade' -a "$(id -u)" = '0' ]; then
  mkdir -p "$PGDATAOLD" "$PGDATANEW"
  chmod 700 "$PGDATAOLD" "$PGDATANEW"
  chown postgres .
  chown -R postgres "$PGDATAOLD" "$PGDATANEW"
  exec gosu postgres "$BASH_SOURCE" "$@"
fi

🚀 完整测试流程

项目提供了一个完整的测试流程，可以帮助你熟悉升级过程：

mkdir -p postgres-upgrade-testing
cd postgres-upgrade-testing
OLD='17'
NEW='18'

# 启动旧版本PostgreSQL并添加测试数据
docker run -dit \
  --name postgres-upgrade-testing \
  --env POSTGRES_PASSWORD='password' \
  --env POSTGRES_INITDB_ARGS='--data-checksums' \
  --mount "type=bind,src=$PWD,dst=/var/lib/postgresql" \
  --env PGDATA="/var/lib/postgresql/$OLD/docker" \
  "postgres:$OLD"

# 等待数据库启动
sleep 5

# 添加测试数据
docker exec -it -u postgres postgres-upgrade-testing pgbench -i -s 10

# 停止旧版本容器
docker stop postgres-upgrade-testing
docker rm postgres-upgrade-testing

# 执行升级
docker run --rm \
  --env POSTGRES_INITDB_ARGS='--data-checksums' \
  --mount "type=bind,src=$PWD,dst=/var/lib/postgresql" \
  --env "PGDATAOLD=/var/lib/postgresql/$OLD/docker" \
  --env "PGDATANEW=/var/lib/postgresql/$NEW/docker" \
  "tianon/postgres-upgrade:$OLD-to-$NEW" \
  --link

# 启动新版本PostgreSQL
docker run -dit \
  --name postgres-upgrade-testing \
  --env POSTGRES_PASSWORD='password' \
  --env POSTGRES_INITDB_ARGS='--data-checksums' \
  --mount "type=bind,src=$PWD,dst=/var/lib/postgresql" \
  --env PGDATA="/var/lib/postgresql/$NEW/docker" \
  "postgres:$NEW"

💡 注意事项

1. 升级前务必做好数据备份
2. 不同版本间可能存在兼容性差异，建议先在测试环境验证
3. 生产环境升级建议安排在低峰期进行
4. 升级完成后，可以安全删除旧版本数据目录：sudo rm -rf "$OLD"

通过docker-postgres-upgrade工具，原本复杂的PostgreSQL升级过程变得简单高效。无论是从14升级到15，还是直接跨版本升级到18，都能通过类似的步骤快速完成。这个工具特别适合需要频繁升级PostgreSQL版本的开发和运维人员使用。

【免费下载链接】docker-postgres-upgrade a PoC for using "pg_upgrade" inside Docker -- learn from it, adapt it for your needs; don't expect it to work as-is! 项目地址: https://gitcode.com/gh_mirrors/do/docker-postgres-upgrade