PostgreSQL Manager

用于管理本地开发环境中共享的 PostgreSQL Docker 容器。

架构

postgres-manager/
├── docker-compose.yml   # PostgreSQL 16 Alpine 容器
└── run.sh               # 生命周期管理 + 数据库管理 CLI

加入由 proxy-manager 创建的共享网络 nginx-proxy_net，以便应用容器可通过主机名 codai_postgres 连接。数据通过命名卷（named volume）持久化保存。

命令

./run.sh start                    # 启动 PostgreSQL 容器
./run.sh stop                     # 停止容器（数据保留在卷中）
./run.sh status                   # 查看状态 + 列出数据库
./run.sh wait                     # 阻塞等待 PostgreSQL 就绪
./run.sh create-db          # 创建数据库（幂等操作）
./run.sh drop-db            # 删除数据库（交互式确认）
./run.sh dump          # 执行 pg_dump src | psql dest
./run.sh list-dbs                 # 列出所有非模板数据库
./run.sh psql []              # 启动 psql 交互式会话

任务执行方式

首次启动 PostgreSQL

cd postgres-manager && ./run.sh start

首次运行时，Docker 将创建数据卷并初始化数据库 codai_main。

为新实例创建数据库

./run.sh create-db codai_feature

将主数据库快照复制到新实例

./run.sh dump codai_main codai_feature

删除工作树（worktree）数据库

./run.sh drop-db codai_feature   # 提示确认

打开交互式 psql

./run.sh psql                    # 连接到 codai_main
./run.sh psql codai_feature      # 连接到指定数据库

启动顺序

1. proxy-manager start — 创建共享 Docker 网络
2. postgres-manager start — 加入共享网络
3. worktree-manager start

配置

应用连接方式

后端容器连接 PostgreSQL 的地址如下：

• 主机名：codai_postgres（共享网络中的容器名）
• 端口：5432
• 用户名：codai / 密码：pgpass
• 数据库：codai_main（或实例专用数据库）

规则

• 禁止删除 POSTGRES_MAIN_DB — 它是所有快照的唯一可信数据源。
• drop-db 操作始终要求交互式确认。
• 所有 SQL 或 Shell 操作前，数据库名均需通过正则表达式 ^[a-z][a-z0-9_]{0,62}$ 校验。
• stop 不影响 Docker 卷中的持久化数据；仅当明确需要清除持久化数据时，才使用 docker compose down -v。
• 容器配置了 restart: unless-stopped — Docker 守护进程重启后会自动恢复运行；完成使用后请显式执行 ./run.sh stop。
• 宿主机端口（POSTGRES_PORT）仅绑定至 127.0.0.1；在共享机器上应设置非默认的 POSTGRES_PASSWORD。
• 网络配置为 external: true — proxy-manager 必须优先启动。

相关插件

• proxy-manager — 创建共享 Docker 网络（需最先启动）
• mysql-manager — MySQL 替代方案
• redis-manager — 内存缓存配套组件
• worktree-manager — 使用 PostgreSQL 的应用实例管理器