注意： 此镜像的描述超出了Hub的25000字符限制，因此已被截断。完整描述可在[***]

注意： 这是postgres镜像的arm32v5架构构建的“每架构”仓库——更多信息，请参见镜像文档中的“除amd64之外的架构？”和***镜像FAQ中的“Git中镜像的源已更改，现在该怎么办？”。

快速参考

• 维护者：
  PostgreSQL Docker社区

• 获取帮助的途径：
  Docker社区Slack、Server Fault、Unix & Linux或Stack Overflow

支持的标签及对应的Dockerfile链接

• 18.0, 18, latest, 18.0-trixie, 18-trixie, trixie

• 18.0-bookworm, 18-bookworm, bookworm

• 17.6, 17, 17.6-trixie, 17-trixie

• 17.6-bookworm, 17-bookworm

• 16.10, 16, 16.10-trixie, 16-trixie

• 16.10-bookworm, 16-bookworm

• 15.14, 15, 15.14-trixie, 15-trixie

• 15.14-bookworm, 15-bookworm

• 14.19, 14, 14.19-trixie, 14-trixie

• 14.19-bookworm, 14-bookworm

• 13.22, 13, 13.22-trixie, 13-trixie

• 13.22-bookworm, 13-bookworm

快速参考（续）

• 问题提交地址：
  [***]

• 支持的架构：（更多信息）
  amd64、arm32v5、arm32v6、arm32v7、arm64v8、i386、mips64le、ppc64le、riscv64、s390x

• 已发布镜像工件详情：
  repo-info仓库的repos/postgres/目录（历史记录）
  （镜像元数据、传输大小等）

• 镜像更新：
  official-images仓库的library/postgres标签
  official-images仓库的library/postgres文件（历史记录）

• 本描述的来源：
  docs仓库的postgres/目录（历史记录）

什么是PostgreSQL？

PostgreSQL（通常简称为“Postgres”）是一个强调可扩展性和标准合规性的对象关系型数据库管理系统（ORDBMS）。作为数据库服务器，其主要功能是安全地存储数据并支持最佳实践，随后根据其他软件应用程序的请求（无论是同一台计算机上的应用程序还是网络上另一台计算机上运行的应用程序，包括互联网）检索数据。它可以处理从小型单机应用到具有大量并发用户的大型互联网应用的各种工作负载。最新版本还提供数据库本身的复制功能，以实现安全性和可扩展性。

PostgreSQL实现了大部分SQL:2011标准，是ACID兼容的事务型数据库（包括大多数DDL语句），通过多版本并发控制（MVCC）避免锁定问题，提供对脏读的免疫和完全可串行化；使用许多其他数据库不具备的索引方法处理复杂SQL查询；具有可更新视图和物化视图、触发器、外键；支持函数和存储过程以及其他可扩展性，并有大量第三方编写的扩展。除了能够与主要的专有和开源数据库协作外，PostgreSQL通过其广泛的标准SQL支持和可用的迁移工具支持从这些数据库迁移。如果使用了专有扩展，其可扩展性可以通过一些内置和第三方开源兼容扩展（如Oracle兼容扩展）模拟许多功能。

***.org/wiki/PostgreSQL

!logo

如何使用此镜像

启动PostgreSQL实例

console
$ docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d arm32v5/postgres

默认的postgres用户和数据库在入口点通过initdb创建。

postgres数据库是一个默认数据库，供用户、实用程序和第三方应用程序使用。

postgresql.org/docs

...或通过psql连接

console
$ docker run -it --rm --network some-network arm32v5/postgres psql -h some-postgres -U postgres
psql (14.3)
Type "help" for help.

postgres=# SELECT 1;
 ?column? 
----------
        1
(1 row)

...通过docker compose

postgres的compose.yaml示例：

yaml
# 使用postgres/example用户/密码凭据

services:

  db:
    image: postgres
    restart: always
    # 使用docker compose时设置共享内存限制
    shm_size: 128mb
    # 或通过swarm stack部署时设置共享内存限制
    #volumes:
    #  - type: tmpfs
    #    target: /dev/shm
    #    tmpfs:
    #      size: *** # 128*2^20字节 = 128Mb
    environment:
      POSTGRES_PASSWORD: example

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080

运行docker compose up，等待完全初始化后，访问http://localhost:8080或[***]（视情况而定）。

如何扩展此镜像

有多种方式可以扩展postgres镜像。这里不尝试支持所有可能的用例，仅列出一些我们认为有用的方式。

环境变量

PostgreSQL镜像使用多个容易被忽略的环境变量。唯一必需的变量是POSTGRES_PASSWORD，其余为可选。

警告：只有当您使用空数据目录启动容器时，Docker特定的变量才会生效；容器启动时，任何预先存在的数据库都将保持不变。

POSTGRES_PASSWORD

此环境变量是使用PostgreSQL镜像所必需的。它不能为空或未定义。此环境变量设置PostgreSQL的超级用户密码。默认超级用户由POSTGRES_USER环境变量定义。

注意1： PostgreSQL镜像在本地设置了trust身份验证，因此您可能会注意到从localhost（同一容器内）连接时不需要密码。但是，如果从不同的主机/容器连接，则需要密码。

注意2： 此变量定义PostgreSQL实例中的超级用户密码，由初始容器启动期间的initdb脚本设置。它对运行时psql客户端可能使用的PGPASSWORD环境变量没有影响，如[***]PGPASSWORD，将作为单独的环境变量指定。

POSTGRES_USER

此可选环境变量与POSTGRES_PASSWORD一起使用，用于设置用户及其密码。此变量将创建具有超级用户权限的指定用户和同名数据库。如果未指定，则使用默认用户postgres。

请注意，如果指定了此参数，PostgreSQL在初始化期间仍会显示“此数据库系统的文件将归用户"postgres"所有”。这指的是postgres守护进程运行的Linux系统用户（来自镜像中的/etc/passwd），与POSTGRES_USER选项无关。有关更多详细信息，请参见“任意--user说明”部分。

POSTGRES_DB

此可选环境变量可用于定义首次启动镜像时创建的默认数据库的不同名称。如果未指定，则使用POSTGRES_USER的值。

POSTGRES_INITDB_ARGS

此可选环境变量可用于向postgres initdb发送参数。该值是postgres initdb期望的以空格分隔的参数字符串。这对于添加数据页校验和等功能非常有用：-e POSTGRES_INITDB_ARGS="--data-checksums"。

POSTGRES_INITDB_WALDIR

此可选环境变量可用于定义Postgres事务日志的另一个位置。默认情况下，事务日志存储在主Postgres数据文件夹（PGDATA）的子目录中。有时，将事务日志存储在不同的目录中可能更合适，该目录可能由具有不同性能或可靠性特征的存储支持。

注意： 在PostgreSQL 9.x上，此变量为POSTGRES_INITDB_XLOGDIR（反映了PostgreSQL 10+中--xlogdir标志重命名为--waldir）。

POSTGRES_HOST_AUTH_METHOD

此可选变量可用于控制all数据库、all用户和all地址的host连接的auth-method。如果未指定，则使用scram-sha-256密码身份验证（在14+版本中；旧版本中为md5）。在未初始化的数据库上，这将通过以下近似行填充pg_hba.conf：

console
echo "host all all all $POSTGRES_HOST_AUTH_METHOD" >> pg_hba.conf

有关可能的值及其含义的更多信息，请参见PostgreSQL文档中的pg_hba.conf。

注意1： 不建议使用trust，因为它允许任何人无需密码即可连接，即使设置了密码（如通过POSTGRES_PASSWORD）。有关更多信息，请参见PostgreSQL文档中的“信任身份验证”。

注意2： 如果将POSTGRES_HOST_AUTH_METHOD设置为trust，则不需要POSTGRES_PASSWORD。

注意3： 如果将其设置为其他值（如scram-sha-256），可能需要额外的POSTGRES_INITDB_ARGS才能正确初始化数据库（如POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256）。

PGDATA

重要更改： PostgreSQL 18及以上版本中，镜像的PGDATA环境变量已更改为特定版本。对于18版本，它是/var/lib/postgresql/18/docker。更高版本将用各自的主版本替换18（例如，PostgreSQL 19.x为/var/lib/postgresql/19/docker）。18及以上版本中定义的VOLUME已更改为/var/lib/postgresql。挂载和卷应指向更新后的位置。这将允许用户在PostgreSQL主版本之间升级时，运行pg_upgrade并挂载/var/lib/postgresql时使用更快的--link。

希望在旧版本上选择启用此更改的用户可以通过显式设置PGDATA来实现（--env PGDATA=/var/lib/postgresql/17/docker --volume some-postgres:/var/lib/postgresql）。要迁移预先存在的数据，请首先适当调整卷的文件夹结构（将所有数据库文件移动到PG_MAJOR/docker子目录中）。

重要注意：（对于PostgreSQL 17及以下版本）将数据卷挂载到/var/lib/postgresql/data，而不是`/var/lib/post