tianon/postgres-upgrade 镜像文档

镜像概述和主要用途

本镜像是一个在 Docker 环境中使用 pg_upgrade 工具进行 PostgreSQL 版本升级的概念验证（PoC）实现。其核心用途是协助用户在 Docker 容器化环境中，将 PostgreSQL 数据库从当前版本（OLD）升级到目标版本（NEW）。注意：此镜像为概念验证工具，需根据实际需求进行适配和测试，不可直接用于生产环境。

镜像源码可参考：[***]

核心功能和特性

标签格式

镜像标签遵循 OLD-to-NEW 格式，其中：

• OLD：当前运行的 PostgreSQL 版本（如 9.4）
• NEW：目标升级的 PostgreSQL 版本（如 9.5）

性能优化

支持通过 --link 参数启用链接模式，避免数据复制，直接创建新旧数据目录的硬链接，显著提升升级性能（具体原理参见 pg_upgrade 文档）。

灵活的目录适配

提供两种目录结构适配方案：

• 推荐方案：符合特定目录结构时使用 --link 模式（高性能）
• 替代方案：目录结构不符合时直接挂载（性能较低）

使用场景和适用范围

适用场景

• 需要在 Docker 容器环境中对 PostgreSQL 数据库进行主版本升级（如从 9.4 升级到 9.5）
• 希望通过容器化方式简化 pg_upgrade 工具的环境配置和依赖管理

限制条件

• 需手动管理新旧版本数据目录的挂载和权限
• 升级前需确保旧版本数据库已停止运行
• 仅支持 PostgreSQL 主版本升级，且需保证 OLD 和 NEW 版本的兼容性（参考 PostgreSQL ***升级说明）

使用方法和配置说明

前提条件

1. 已停止旧版本 PostgreSQL 容器（避免数据文件被占用）
2. 已准备新旧版本数据目录（推荐提前备份数据）

推荐方法：目录结构符合要求时（使用 --link）

目录结构要求

数据目录需满足以下层级结构，其中 DIR 为宿主机根目录，OLD 和 NEW 分别为当前和目标 PostgreSQL 版本：

console
$ find DIR -mindepth 2 -maxdepth 2
DIR/OLD/data  # 旧版本数据目录
DIR/NEW/data  # 新版本数据目录（需提前创建空目录）

升级命令格式

console
$ docker run --rm \
  -v DIR:/var/lib/postgresql \  # 挂载宿主机根目录到容器内 /var/lib/postgresql
  tianon/postgres-upgrade:OLD-to-NEW \  # 指定镜像标签（OLD-to-NEW）
  --link  # 启用链接模式（提升性能）

具体示例（9.4 升级到 9.5）

假设：

• 旧版本 OLD=9.4，新版本 NEW=9.5
• 宿主机根目录 DIR=/mnt/bigdrive/postgresql

1. 验证目录结构：

console
$ find /mnt/bigdrive/postgresql -mindepth 2 -maxdepth 2
/mnt/bigdrive/postgresql/9.4/data  # 旧版本数据目录（原 postgres:9.4 容器挂载路径）
/mnt/bigdrive/postgresql/9.5/data  # 新版本数据目录（为空目录，供 postgres:9.5 使用）

2. 执行升级：

console
$ docker run --rm \
  -v /mnt/bigdrive/postgresql:/var/lib/postgresql \
  tianon/postgres-upgrade:9.4-to-9.5 \
  --link

替代方法：目录结构不符合要求时（不使用 --link）

目录结构要求

直接挂载旧版本数据目录（PGDATAOLD）和新版本数据目录（PGDATANEW），无需特定层级关系。

升级命令格式

console
$ docker run --rm \
  -v PGDATAOLD:/var/lib/postgresql/OLD/data \  # 挂载旧版本数据目录
  -v PGDATANEW:/var/lib/postgresql/NEW/data \  # 挂载新版本数据目录（需为空）
  tianon/postgres-upgrade:OLD-to-NEW  # 不使用 --link 参数

具体示例（9.4 升级到 9.5）

假设：

• 旧版本数据目录 PGDATAOLD=/mnt/bigdrive/postgresql-9.4
• 新版本数据目录 PGDATANEW=/mnt/bigdrive/postgresql-9.5

执行升级：

console
$ docker run --rm \
  -v /mnt/bigdrive/postgresql-9.4:/var/lib/postgresql/9.4/data \
  -v /mnt/bigdrive/postgresql-9.5:/var/lib/postgresql/9.5/data \
  tianon/postgres-upgrade:9.4-to-9.5

完整升级流程示例（9.4 升级到 9.5）

1. 准备工作

console
# 创建工作目录
$ mkdir -p postgres-upgrade-testing && cd postgres-upgrade-testing

# 定义版本和目录变量
$ OLD='9.4'
$ NEW='9.5'

2. 启动旧版本 PostgreSQL 并准备测试数据

console
# 拉取旧版本镜像
$ docker pull "postgres:$OLD"

# 启动旧版本容器（挂载数据目录）
$ docker run -dit \
  --name postgres-upgrade-testing \
  -v "$PWD/$OLD/data:/var/lib/postgresql/data" \
  "postgres:$OLD"

# 等待容器启动（约5秒）
$ sleep 5

# 查看容器日志确认启动成功
$ docker logs --tail 100 postgres-upgrade-testing

# 生成测试数据（使用 pgbench）
$ docker exec -it \
  -u postgres \
  postgres-upgrade-testing \
  pgbench -i -s 10

3. 停止旧版本容器并执行升级

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

# 运行升级容器（使用推荐方法，--link 模式）
$ docker run --rm \
  -v "$PWD":/var/lib/postgresql \
  "tianon/postgres-upgrade:$OLD-to-$NEW" \
  --link

4. 启动新版本 PostgreSQL 并验证

console
# 拉取新版本镜像
$ docker pull "postgres:$NEW"

# 启动新版本容器（挂载升级后的新数据目录）
$ docker run -dit \
  --name postgres-upgrade-testing \
  -v "$PWD/$NEW/data:/var/lib/postgresql/data" \
  "postgres:$NEW"

# 等待容器启动并查看日志确认成功
$ sleep 5 && docker logs --tail 100 postgres-upgrade-testing

5. 清理旧版本数据（可选）

console
$ sudo rm -rf "$OLD"

注意事项

1. 概念验证性质：本镜像为技术验证工具，升级前需在测试环境充分验证，生产环境使用前必须进行适配和定制。
2. 数据备份：升级前务必备份旧版本数据目录，避免数据丢失。
3. 目录权限：确保宿主机数据目录对 Docker 容器有读写权限（建议使用与 PostgreSQL 容器相同的用户权限）。
4. 版本兼容性：仅支持***声明兼容的 PostgreSQL 版本升级，跨多个主版本升级需分步进行（如 9.4→9.5→9.6）。
5. 升级后验证：启动新版本容器后，需通过 psql 或应用验证数据完整性和功能正常性。