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

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

注意：本文档中的示例使用podman命令，你可以将其替换为docker，参数保持不变。

描述

该容器镜像提供PostgreSQL postgres守护进程和客户端应用的容器化打包。postgres服务器守护进程接受客户端连接，并代表客户端提供对PostgreSQL数据库内容的访问。更多信息可访问PostgreSQL项目网站([***]

用法

假设使用rhscl/postgresql-12-rhel7镜像（在OpenShift中可通过postgresql:12镜像流标签获取）。若仅设置必填环境变量且不将数据库存储在主机目录，执行以下命令：

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

这将创建一个名为postgresql_database的容器，运行PostgreSQL数据库db，用户凭据为user:pass。

注意：postgres用户保留用于内部使用

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

在OpenShift实例中，可使用OpenShift提供的模板或示例中的模板实现相同功能：

$ oc process -f examples/postgresql-ephemeral-template.json -p POSTGRESQL_VERSION=12 -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传递给Docker run命令。

环境变量

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_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上，可通过以下方式修复数据目录权限：

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

数据迁移

PostgreSQL容器支持从远程PostgreSQL服务器迁移数据。可按以下方式运行：

$ 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选项进行尽力而为的迁移（可能丢失部分数据，用户需检查标准错误输出并在迁移后手动修复问题）。

请注意，容器镜像仅为用户提供便利，不保证完全自动迁移。因此，在开始数据库迁移前，请确保已准备好执行手动步骤以确保所有数据迁移成功。

注意：在迁移场景中，无需设置POSTGRESQL_USER等变量，所有数据（包括数据库、角色和密码信息）均从旧集群复制。确保使用与初始化旧PostgreSQL容器相同的可选配置变量。若远程集群有非默认配置，可能还需手动复制配置文件。

安全警告：旧集群与新集群之间的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服务器10版本（仅限此版本）的数据目录。升级过程设计为只需从镜像A切换到镜像B，并适当设置$POSTGRESQL_UPGRADE变量以显式请求数据库数据转换。

升级过程内部通过pg_upgrade二进制文件实现，因此容器需包含两个版本的PostgreSQL服务器（更多信息参见man pg_upgrade）。

pg_upgrade过程及新版本服务器需要初始化全新的数据目录。容器工具会自动在/var/lib/pgsql/data（通常是外部绑定挂载点）下创建该目录。pg_upgrade的执行类似备份恢复方法——在容器内启动旧版和新版PostgreSQL服务器，同时“备份”旧数据目录并“恢复”到新数据目录。此操作需要大量数据文件复制，因此可通过设置$POSTGRESQL_UPGRADE选择升级类型：

copy

数据文件从旧数据目录复制到新数据目录。此选项在升级失败时数据丢失风险较低。

hardlink

数据文件从旧数据目录硬链接到新数据目录，可提升性能，但升级失败时旧目录将不可用。

注意：由于需要复制数据目录，请确保有足够的空间；空间不足导致的升级失败可能导致数据丢失。

扩展镜像

可在OpenShift中使用Source构建策略，或通过独立的source-to-image应用（若可用）扩展该镜像。以下假设使用rhscl/postgresql-12-rhel7镜像（在OpenShift中通过postgresql:12镜像流标签获取）。

例如，使用[***]中的配置构建自定义镜像new-postgresql：

通过OpenShift：

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

通过s2i：

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

传递给OpenShift的目录可包含以下一个或多个子目录：

postgresql-pre-start/

容器启动初期会加载此目录中的所有*.sh文件。此时PostgreSQL守护进程未在后台运行。

postgresql-cfg/

包含的配置文件（*.conf）将在镜像的postgresql.conf文件末尾包含。

postgresql-init/

包含的shell脚本（*.sh）在数据库首次初始化（initdb成功运行使数据目录非空后）时加载。加载这些脚本时，本地PostgreSQL服务器正在运行。对于带有持久数据目录的重新部署场景，脚本不会加载（无操作）。

postgresql-start/

语义与postgresql-init/相同，但这些脚本始终加载（若postgresql-init/脚本存在，则在其后加载）。

s2i构建期间，所有提供的文件将复制到新镜像的/opt/app-root/src目录。同名文件仅能用于一次自定义，用户提供的文件优先于/usr/share/container-scripts/中的默认文件，因此可覆盖默认文件。

故障排除

Postgres守护进程最初将日志输出到标准输出，因此可在容器日志中查看。通过以下命令检查日志：

podman logs <容器名>

之后日志输出会重定向到日志收集进程，并显示在pg_log目录中。

参见

该容器镜像的Dockerfile和其他源码可在[***]