docker compose 是本地快速搭建可复现、隔离且支持数据持久化的 postgresql 开发环境的最直接高效方式，需先安装 docker 和 docker compose，再创建 docker-compose.yml 配置服务、挂载数据卷与初始化脚本，最后启动并验证连接。
如果您希望在本地快速搭建一个可复现、隔离且支持数据持久化的 PostgreSQL 开发环境，则 Docker Compose 是最直接高效的实现方式。以下是完成该目标的具体步骤：
一、准备 Docker 环境
确保系统已安装 Docker 和 Docker Compose，二者是运行容器化 PostgreSQL 的基础依赖。未安装时将无法解析服务定义或启动容器实例。
1、验证 Docker 是否就绪：docker --version
2、验证 Docker Compose 是否可用：docker-compose --version
3、若命令报错，需前往 https://www.docker.com/products/docker-desktop/ 下载并安装 Docker Desktop（Windows/macOS）或按发行版指南安装 Docker Engine + Compose 插件（Linux）。
二、创建标准 docker-compose.yml 配置文件
该配置文件定义 PostgreSQL 服务的镜像版本、认证凭据、端口映射及数据持久化路径，是整个环境的核心声明。
1、新建项目目录：mkdir -p ~/postgres-dev && cd ~/postgres-dev
2、创建 docker-compose.yml 文件，内容如下：
3、写入以下 YAML 内容（使用 PostgreSQL 16 官方 Alpine 镜像，轻量且安全）：
version: '3.8'
services:
postgres:
image: postgres:16.11-alpine3.23
container_name: pg-local
environment:
POSTGRES_USER: devuser
POSTGRES_PASSWORD: devpass
POSTGRES_DB: devdb
ports:
- "5432:5432"
volumes:
- ./postgres-data:/var/lib/postgresql/data
restart: unless-stopped
三、启用数据持久化与初始化脚本
通过绑定挂载本地目录，可确保容器重启或重建后数据库状态不丢失；初始化脚本则在首次启动时自动建库、建表、插入示例数据。
1、创建初始化脚本目录：mkdir -p ./init
2、新建 SQL 初始化文件：touch ./init/01-init.sql
3、向 ./init/01-init.sql 写入建表语句，例如：
CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE);
INSERT INTO users (name, email) SELECT 'Alice', 'alice@example.com' WHERE NOT EXISTS (SELECT FROM users WHERE email = 'alice@example.com');
四、挂载初始化脚本并启动服务
Docker 在首次启动 PostgreSQL 容器时，会自动执行 /docker-entrypoint-initdb.d/ 目录下所有以 .sql 或 .sh 结尾的文件，从而完成结构与初始数据部署。
1、修改 docker-compose.yml 中的 volumes 部分，追加初始化脚本挂载项：
volumes:
- ./postgres-data:/var/lib/postgresql/data
- ./init:/docker-entrypoint-initdb.d:ro
2、保存文件后，在项目根目录执行启动命令：docker-compose up -d
3、等待约 5–10 秒，检查容器是否运行：docker-compose ps，状态应为 Up
五、验证连接与数据库状态
确认服务已就绪且可被本地客户端访问，是验证环境搭建成功的关键环节。此时数据库应响应连接请求并返回预设的初始数据。
1、使用 psql 命令行工具连接：psql -h localhost -p 5432 -U devuser -d devdb
2、在 psql 提示符中执行查询：SELECT * FROM users;
3、预期返回至少一行记录，如：(1, Alice, alice@example.com)
