PostgreSQL 9.6 SQL数据库服务器容器镜像

该容器镜像包含PostgreSQL 9.6 SQL数据库服务器，适用于OpenShift和通用场景。用户可选择基于RHEL、CentOS或Fedora的镜像：RHEL镜像可在Red Hat容器目录获取，CentOS镜像在Docker Hub，Fedora镜像在Fedora Registry。生成的镜像可使用podman运行。

注意：本文档中的示例使用podman命令，所有此类命令均可替换为docker，参数保持不变。

概述

本容器镜像提供PostgreSQL数据库服务端（postgres daemon）和客户端应用的容器化打包。PostgreSQL服务端接受客户端连接，并代表客户端提供对PostgreSQL数据库内容的访问。更多关于PostgreSQL项目的信息，请访问***网站。

使用方法

以下示例基于rhscl/postgresql-96-rhel7镜像（在OpenShift中可通过postgresql:9.6镜像流标签获取）。

基本运行（无持久化）

若只需设置必填环境变量且不将数据库存储在主机目录，执行以下命令：

bash
$ podman run -d --name postgresql_database -e POSTGRESQL_USER=user -e POSTGRESQL_PASSWORD=pass -e POSTGRESQL_DATABASE=db -p 5432:5432 rhscl/postgresql-96-rhel7

此命令将创建名为postgresql_database的容器，运行PostgreSQL数据库，其中包含数据库db和用户user（密码pass）。> 注意：postgres用户为内部保留用户，不可用于常规访问。

容器会暴露5432端口并映射到主机。若需数据库在容器重启后持久化，需添加-v /host/db/path:/var/lib/pgsql/data参数（见下文），该目录为PostgreSQL数据库集群目录。

在OpenShift中使用

可使用OpenShift提供的模板或示例模板部署：

bash
$ oc process -f examples/postgresql-ephemeral-template.json -p POSTGRESQL_VERSION=9.6 -p POSTGRESQL_USER=user -p POSTGRESQL_PASSWORD=pass -p POSTGRESQL_DATABASE=db | oc create -f -

初始化与启动流程

若数据库集群目录未初始化，入口脚本会先运行initdb并设置必要的数据库用户和密码。初始化完成（或目录已存在）后，将执行postgres并以PID 1运行。可通过podman stop postgresql_database停止后台运行的容器。

环境变量和卷

环境变量

可通过-e VAR=VALUE参数设置以下环境变量：

必选环境变量

• POSTGRESQL_USER：要创建的PostgreSQL用户名
• POSTGRESQL_PASSWORD：用户账户密码
• POSTGRESQL_DATABASE：数据库名称
• POSTGRESQL_ADMIN_PASSWORD（可选）：postgres管理员账户密码

迁移相关环境变量

• POSTGRESQL_MIGRATION_REMOTE_HOST：迁移源主机名/IP
• POSTGRESQL_MIGRATION_ADMIN_PASSWORD：远程postgres管理员密码
• POSTGRESQL_MIGRATION_IGNORE_ERRORS（可选，默认no）：设为yes可忽略SQL导入错误

PostgreSQL配置环境变量（可选）

• POSTGRESQL_MAX_CONNECTIONS（默认：100）：允许的最大客户端连接数
• POSTGRESQL_MAX_PREPARED_TRANSACTIONS（默认：0）：最大预备事务数，使用预备事务时建议至少与max_connections相同
• POSTGRESQL_SHARED_BUFFERS（默认：32M）：PostgreSQL用于缓存数据的内存大小
• POSTGRESQL_EFFECTIVE_CACHE_SIZE（默认：128M）：操作系统和数据库可用于磁盘缓存的内存估计值

卷挂载点

可通过-v /host/dir:/container/dir:Z挂载以下目录：

• /var/lib/pgsql/data：PostgreSQL数据库集群目录

注意：从主机挂载目录到容器时，需确保挂载目录具有适当权限，且目录的所有者和组与容器内运行的用户UID或名称匹配。
通常（除非使用podman run -u指定用户），容器内进程以UID 26运行。在GNU/Linux上，可通过以下命令修复数据目录权限：

bash
$ setfacl -m u:26:-wx /your/data/dir
$ podman run <...> -v /your/data/dir:/var/lib/pgsql/data:Z <...>

数据迁移

PostgreSQL容器支持从远程PostgreSQL服务器迁移数据，命令如下：

bash
$ podman run -d --name postgresql_database \
    -e POSTGRESQL_MIGRATION_REMOTE_HOST=172.17.0.2 \
    -e POSTGRESQL_MIGRATION_ADMIN_PASSWORD=remoteAdminP@ssword \
    [ 可选配置变量 ]
    openshift/postgresql-92-centos7

迁移通过备份与恢复方式实现（对远程集群运行pg_dumpall并通过psql本地导入）。由于过程是流式（Unix管道）的，不会创建中间备份文件，以节省存储空间。

迁移错误处理

默认情况下，若迁移过程中SQL命令失败，迁移脚本会终止以确保全有或全无的迁移结果。这适用于从使用相同原理创建的旧版本PostgreSQL容器（如从openshift/postgresql-92-centos7迁移到centos/postgresql-95-centos7）。从其他类型的PostgreSQL容器迁移可能失败。

若需忽略错误并执行尽力迁移（可能丢失数据，需用户手动检查和修复），可设置POSTGRESQL_MIGRATION_IGNORE_ERRORS=yes。

注意事项

• 容器镜像仅为方便提供迁移帮助，不保证完全自动迁移成功。迁移前请做好手动干预准备。
• 迁移场景中无需设置POSTGRESQL_USER等变量，所有数据（包括数据库、角色、密码）均从旧集群复制。
• 需确保新容器使用与旧容器相同的可选配置变量。若远程集群有非默认配置，可能需手动复制配置文件。
• 安全警告：默认情况下，新旧集群间的IP通信未加密，需用户配置SSL或通过其他方式确保安全。

PostgreSQL自动调优

当运行PostgreSQL镜像时指定--memory参数，且未设置POSTGRESQL_SHARED_BUFFERS和POSTGRESQL_EFFECTIVE_CACHE_SIZE，这两个值将根据--memory参数自动计算：

• shared_buffers：设为内存的1/4
• effective_cache_size：设为内存的1/2

计算依据上游建议。

PostgreSQL管理员账户

默认情况下，postgres管理员账户无密码，仅允许本地连接。可通过设置POSTGRESQL_ADMIN_PASSWORD环境变量为其设置密码，允许远程登录。本地连接仍无需密码。

修改密码

密码是镜像配置的一部分，修改数据库用户（POSTGRESQL_USER）和postgres管理员密码的唯一支持方式是修改对应的环境变量（POSTGRESQL_PASSWORD和POSTGRESQL_ADMIN_PASSWORD）。容器每次启动时，会将密码重置为环境变量中存储的值。通过SQL语句或其他方式修改密码会导致环境变量值与实际密码不匹配，容器重启后将被覆盖。

数据库升级（切换到新版本PostgreSQL镜像）

警告：升级数据目录前，请务必备份所有数据，并做好手动回滚准备！

本镜像支持自动升级由sclorg镜像提供的PostgreSQL 9.5版本（仅此版本）的数据目录。升级过程通过设置POSTGRESQL_UPGRADE变量显式触发，内部使用pg_upgrade工具实现（需容器包含两个版本的PostgreSQL服务器，详见man pg_upgrade）。

升级方式

pg_upgrade需初始化新数据目录（通常位于/var/lib/pgsql/data，外部挂载点），通过启动新旧服务器并“备份-恢复”数据实现。根据数据文件处理方式，POSTGRESQL_UPGRADE支持以下值：

• copy：数据文件从旧目录复制到新目录。升级失败时数据丢失风险低。
• hardlink：数据文件从旧目录硬链接到新目录，性能更优，但升级失败后旧目录将不可用。

注意事项

• 升级需足够磁盘空间存储复制的数据，空间不足可能导致数据丢失。
• 升级前确保备份数据，升级过程可能需要大量文件复制。

扩展镜像

可在OpenShift中使用Source构建策略或独立的source-to-image（s2i）工具扩展本镜像。以下示例基于rhscl/postgresql-96-rhel7镜像（OpenShift中通过postgresql:9.6镜像流标签获取）。

构建扩展镜像

OpenShift中构建

bash
$ oc new-app postgresql:9.6~[***] \
  --name new-postgresql \
  --context-dir examples/extending-image/ \
  -e POSTGRESQL_USER=user \
  -e POSTGRESQL_DATABASE=db \
  -e POSTGRESQL_PASSWORD=password

独立s2i构建

bash
$ s2i build --context-dir examples/extending-image/ [***] rhscl/postgresql-96-rhel7 new-postgresql

自定义目录

扩展时可提供以下目录，文件将复制到新镜像的/opt/app-root/src目录，用户文件优先于/usr/share/container-scripts/中的默认文件：

• postgresql-pre-start/：容器启动初期执行所有*.sh脚本（PostgreSQL未运行）。
• postgresql-cfg/：包含的*.conf文件将追加到postgresql.conf末尾。
• postgresql-init/：数据库首次初始化后（initdb成功且数据目录非空）执行所有*.sh脚本（本地PostgreSQL已运行）。持久化数据目录重新部署时不执行。
• postgresql-start/：每次容器启动时执行所有*.sh脚本（在postgresql-init/之后，若存在）。

故障排除

PostgreSQL服务日志默认输出到标准输出，可通过以下命令查看容器日志：

bash
podman logs <容器名>

之后日志会重定向到日志收集进程，存储在pg_log目录。

另请参阅

本容器镜像的Dockerfile及源码位于[***]

• CentOS的Dockerfile名为Dockerfile
• RHEL7的Dockerfile名为Dockerfile.rhel7
• RHEL8的Dockerfile名为Dockerfile.rhel8
• Fedora的Dockerfile名为Dockerfile.fedora