📝 PostgreSQL 18.x Docker 镜像 PGDATA 路径变更说明

本文档旨在记录 PostgreSQL 官方 Docker 镜像自版本 18.0 起，其默认数据目录（PGDATA）路径的变化，并指导如何正确配置卷挂载以实现数据持久化。

🚀 核心变更：PGDATA 路径版本化

从 PostgreSQL 18.x 开始，官方 Docker 镜像将数据库的数据存储位置 (PGDATA 环境变量) 更改为版本特定的路径。

PostgreSQL PGDATA 路径变更

PostgreSQL 版本 旧版本 PGDATA 默认路径 18.x 版本 PGDATA 默认路径
17.x 及以前 /var/lib/postgresql/data N/A
18.x 及以后 N/A /var/lib/postgresql/18/docker

🔍 变更原因

采用版本化的 PGDATA 路径有以下重要意义：

  1. 便于升级 (pg_upgrade): 允许用户将不同主版本的数据库数据目录（例如 /var/lib/postgresql/17/docker 和 /var/lib/postgresql/18/docker）并行挂载到父目录 /var/lib/postgresql 下，从而更有效地利用 pg_upgrade 等工具进行版本间升级。
  2. 确保数据持久性: 在重新创建或升级容器时，通过将卷准确挂载到版本特定的路径，确保了数据的正确持久化。

💾 数据持久化配置

当使用 PostgreSQL 18.x 官方镜像时，必须将您的持久化卷（无论是命名卷还是绑定挂载）挂载到新的 PGDATA 路径：/var/lib/postgresql/18/docker。

使用 Docker Compose

在您的 docker-compose.yaml 文件中，应将卷配置指向新的路径：

1
2
3
4
5
6
7
8
9
10
11
services:
  postgres:
    image: postgres:18.0-alpine3.22
    container_name: postgres
    # ... 其他配置 ...
    volumes:
      # ⚠️ 必须指向版本特定的 PGDATA 路径
      - pg18-data-volume:/var/lib/postgresql/18/docker

volumes:
  pg18-data-volume:

使用 Docker Run (绑定挂载示例)

使用 docker run 命令进行绑定挂载时，也需要指定新的路径：

1
2
3
4
5
docker run -d \
  -v my_postgres_data:/var/lib/postgresql/18/docker \
  -e POSTGRES_PASSWORD=your_password \
  --name postgres18 \
  postgres:18.0-alpline3.22

⚠️ 升级注意事项

在从 PostgreSQL 17.x 或更早版本升级到 18.x 时，由于主版本之间的内部存储格式不兼容，不能简单地更改镜像标签并重用旧的 /var/lib/postgresql/data 卷。

正确的主版本升级流程应是：

  1. 从旧版本容器中执行 pg_dumpall 创建完整的 SQL 备份。
  2. 停止旧容器，创建并启动一个新的 PostgreSQL 18.x 容器，并使用 新路径 挂载卷。
  3. 将第 1 步中的 SQL 备份文件导入（psql）到新的 PostgreSQL 18.x 容器中。