PostgreSQL Docker镜像文档

快速参考

维护者：
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
18.0-alpine3.22, 18-alpine3.22, alpine3.22, 18.0-alpine, 18-alpine, alpine
18.0-alpine3.21, 18-alpine3.21, alpine3.21
17.6, 17, 17.6-trixie, 17-trixie
17.6-bookworm, 17-bookworm
17.6-alpine3.22, 17-alpine3.22, 17.6-alpine, 17-alpine
17.6-alpine3.21, 17-alpine3.21
16.10, 16, 16.10-trixie, 16-trixie
16.10-bookworm, 16-bookworm
16.10-alpine3.22, 16-alpine3.22, 16.10-alpine, 16-alpine
16.10-alpine3.21, 16-alpine3.21
15.14, 15, 15.14-trixie, 15-trixie
15.14-bookworm, 15-bookworm
15.14-alpine3.22, 15-alpine3.22, 15.14-alpine, 15-alpine
15.14-alpine3.21, 15-alpine3.21
14.19, 14, 14.19-trixie, 14-trixie
14.19-bookworm, 14-bookworm
14.19-alpine3.22, 14-alpine3.22, 14.19-alpine, 14-alpine
14.19-alpine3.21, 14-alpine3.21
13.22, 13, 13.22-trixie, 13-trixie
13.22-bookworm, 13-bookworm
13.22-alpine3.22, 13-alpine3.22, 13.22-alpine, 13-alpine
13.22-alpine3.21, 13-alpine3.21

快速参考（续）

问题反馈地址：
[***]
支持的架构：(更多信息)
amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, mips64le, ppc64le, riscv64, s390x
镜像 artifact 详情：
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 i386/postgres

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

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

postgresql.org/docs

通过 `psql` 连接

console
$ docker run -it --rm --network some-network i386/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 在初始化期间仍会显示“The files belonging to this database system will be owned by user "postgres"”。这指的是镜像中 /etc/passwd 中的 Linux 系统用户（postgres 守护进程运行的用户），与 POSTGRES_USER 选项无关。有关更多详细信息，请参见“任意 --user 说明”部分。