PostgreSQL自动升级镜像（pgautoupgrade）技术文档

1. 镜像概述与主要用途

pgautoupgrade 是一个基于官方 PostgreSQL 镜像（如 postgres:17-alpine）构建的 Docker 容器，核心功能是在启动时自动检测并升级数据库文件。该镜像支持从 PostgreSQL 9.5 及以上版本升级至目标版本，通过 pg_upgrade 工具的 --link 选项实现快速原地升级，并可自动启动数据库服务。主要用途是简化 PostgreSQL 版本升级流程，解决手动升级带来的复杂性和兼容性问题，适用于需要长期维护且需保持数据库版本最新的场景。

2. 核心功能与特性

• 自动版本检测与升级：启动时检查数据库文件版本，若低于目标版本则自动执行升级，无需手动干预。
• 快速原地升级：采用 pg_upgrade --link 工具，实现原地升级以缩短升级时间。
• 多版本与基础镜像支持：提供 Alpine（如 17-alpine）和 Debian（如 17-bookworm）两种基础镜像，支持指定目标 PostgreSQL 版本（如 17、16 等）。
• “One shot”模式：支持仅执行升级操作，完成后不启动数据库服务。
• 可配置索引重建：默认升级后重建所有数据库索引，可通过环境变量禁用以优化大型数据库升级效率。
• 跨基础系统兼容性：提供 Debian 基础镜像，解决从官方 Debian 镜像升级至 Alpine 镜像的兼容性问题。

3. 使用场景与适用范围

• 现有数据库升级：适用于 PostgreSQL 9.5 及以上版本数据库需要升级至新版本（如 17）的场景。
• 长期维护系统：如 Redash 等依赖 PostgreSQL 的应用，需避免因版本升级导致的服务中断或配置问题。
• 自动化版本管理：需统一管理数据库版本，确保使用最新稳定版或特定目标版本的环境。
• 跨基础系统迁移：支持从 Debian 基础镜像升级至 Alpine 或反之，解决跨系统升级兼容性问题。

4. 使用方法与配置说明

4.1 镜像标签选择

根据目标 PostgreSQL 版本及基础系统选择标签：

4.2 基本部署示例

4.2.1 使用 docker run 启动

docker run -d \
  --name pgautoupgrade \
  -v /path/to/local/data:/var/lib/postgresql/data \  # 挂载宿主机数据目录
  -e POSTGRES_PASSWORD=your_secure_password \       # 数据库管理员密码（必填）
  -p 5432:5432 \                                    # 暴露数据库端口
  pgautoupgrade/pgautoupgrade:17-alpine             # 目标镜像（Alpine 基础）

4.2.2 Docker Compose 配置

version: '3'
services:
  postgres:
    image: pgautoupgrade/pgautoupgrade:17-alpine
    container_name: pgautoupgrade
    volumes:
      - postgres_data:/var/lib/postgresql/data  # 使用命名卷持久化数据
    environment:
      - POSTGRES_PASSWORD=your_secure_password  # 数据库管理员密码（必填）
      - POSTGRES_USER=postgres                  # 管理员用户名（默认：postgres）
      - POSTGRES_DB=postgres                    # 初始数据库名（默认：postgres）
    ports:
      - "5432:5432"                             # 端口映射

volumes:
  postgres_data:  # 定义命名卷

4.3 “One shot”模式（仅执行升级）

添加环境变量 PGAUTO_ONESHOT=yes，容器仅执行升级操作，完成后自动退出，不启动数据库服务：

docker run -it \
  --name pgauto-upgrade \
  -v /path/to/local/data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e PGAUTO_ONESHOT=yes \
  pgautoupgrade/pgautoupgrade:17-alpine

4.4 跳过升级后索引重建

默认升级后会重建所有数据库索引（耗时较长），可通过 PGAUTO_REINDEX=no 禁用：

docker run -d \
  --name pgautoupgrade \
  -v /path/to/local/data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e PGAUTO_REINDEX=no \
  pgautoupgrade/pgautoupgrade:17-alpine

4.5 Debian 与 Alpine 基础镜像选择

• 原 Debian 基础镜像（如官方 postgres:16-bookworm）：升级时需选择 Debian 目标镜像（如 17-bookworm），避免跨系统兼容性问题。
• 原 Alpine 基础镜像：可直接选择 Alpine 目标镜像（如 17-alpine）。

Debian 基础镜像部署示例：

docker run -d \
  --name pgautoupgrade-debian \
  -v /path/to/local/data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=your_secure_password \
  pgautoupgrade/pgautoupgrade:17-bookworm

5. 环境变量配置

6. 注意事项

6.1 数据备份警告

重要：本镜像通过 pg_upgrade --link 执行原地升级，若过程中发生错误可能导致数据损坏。升级前必须备份数据库数据目录，确保可恢复。

6.2 跨基础镜像兼容性

• 从官方 Debian 基础镜像（如 postgres:16-bookworm）升级时，需选择 Debian 目标镜像（如 17-bookworm），避免跨系统兼容性问题。
• 从 Alpine 基础镜像升级时，选择 Alpine 目标镜像（如 17-alpine）。

7. 源代码与贡献

本镜像源码托管于 GitHub：[***]