ongres/postgres-util

PostgreSQL实用工具OCI镜像文档

镜像概述

本镜像为PostgreSQL数据库提供一系列实用工具的OCI（开放容器倡议）标准镜像，集成了PostgreSQL官方及社区常用的数据库管理工具，旨在简化PostgreSQL数据库的日常运维工作，包括备份、恢复、数据迁移、性能监控等任务。镜像遵循OCI标准，可无缝集成到Docker、Kubernetes等容器化环境中。

核心功能与特性

工具集包含

• 备份工具：pg_dump（单库备份）、pg_dumpall（全库备份）、pg_basebackup（基础备份，支持时间点恢复）
• 恢复工具：pg_restore（恢复pg_dump生成的备份文件）、psql（执行SQL脚本恢复文本格式备份）
• 数据迁移工具：结合pg_dump与pg_restore实现不同PostgreSQL实例间的数据迁移，支持自定义迁移策略（如仅迁移数据、结构等）
• 性能监控工具：pg_stat_statements（需配合数据库配置启用，分析SQL执行统计信息）、pg_top（实时监控数据库活动）
• 数据库管理工具：psql（PostgreSQL官方交互式客户端，支持执行SQL命令、数据库管理操作）、pg_isready（检查数据库连接状态）

镜像特性

• 遵循OCI标准，兼容主流容器运行时（Docker、containerd等）
• 轻量级设计，基于最小化基础镜像构建，减少资源占用
• 工具版本与主流PostgreSQL版本兼容（支持PostgreSQL 10+）
• 无需预装PostgreSQL服务端，仅包含工具集，降低容器体积

使用场景与适用范围

• 数据库备份与恢复：定期执行全库/单库备份，或在数据库升级、迁移前创建备份；从备份文件恢复数据库数据
• 数据迁移：在不同PostgreSQL实例（如开发环境到生产环境、不同版本数据库间）迁移数据
• 容器化环境运维：在Kubernetes、Docker Compose等容器编排平台中，作为辅助容器执行PostgreSQL管理任务
• 自动化脚本集成：嵌入Shell/Python等自动化脚本，实现备份策略自动化、数据迁移自动化等
• 临时数据库访问：通过psql工具临时连接PostgreSQL数据库，执行查询或管理操作，无需在本地安装PostgreSQL客户端

使用方法与配置说明

前提条件

• 已安装Docker或其他OCI兼容容器运行时
• 可访问目标PostgreSQL数据库（网络连通，且具有足够权限的数据库用户）

基本使用命令格式

bash
docker run [选项] postgres-utilities:latest [工具名称] [工具参数]

常用工具使用示例

1. 使用psql连接PostgreSQL数据库

bash
docker run --rm -it \
  -e PGHOST=<数据库主机IP或域名> \
  -e PGPORT=<数据库端口，默认5432> \
  -e PGUSER=<数据库用户名> \
  -e PGPASSWORD=<数据库用户密码> \
  -e PGDATABASE=<数据库名称> \
  docker.xuanyuan.run/postgres-utilities:latest \
  psql -c "SELECT version();"

说明：
--rm：容器退出后自动删除；-it：交互式终端；通过环境变量传递数据库连接信息（或直接在psql参数中指定，如psql -h <host> -p <port> -U <user> -d <dbname>）

2. 使用pg_dump备份数据库

bash
# 备份为自定义格式（支持压缩、选择性恢复）
docker run --rm -v $(pwd):/backup \
  docker.xuanyuan.run/postgres-utilities:latest \
  pg_dump -h <db-host> -p <db-port> -U <db-user> -d <db-name> \
  -F c -f /backup/db_backup_$(date +%Y%m%d).dump -Z 6

参数说明：
-v $(pwd):/backup：挂载本地目录到容器内/backup，用于保存备份文件；
-F c：自定义格式备份（推荐，支持压缩和灵活恢复）；
-f /backup/...：备份文件路径（容器内路径，对应本地挂载目录）；
-Z 6：压缩级别（1-9，越高压缩率越好但耗时越长）

3. 使用pg_restore从备份文件恢复数据库

bash
docker run --rm -v $(pwd):/backup \
  docker.xuanyuan.run/postgres-utilities:latest \
  pg_restore -h <目标db-host> -p <目标db-port> -U <目标db-user> -d <目标db-name> \
  /backup/db_backup_20240101.dump

4. 使用pg_dumpall备份所有数据库

bash
docker run --rm -v $(pwd):/backup \
  docker.xuanyuan.run/postgres-utilities:latest \
  pg_dumpall -h <db-host> -p <db-port> -U <db-user> \
  -f /backup/full_backup_$(date +%Y%m%d).sql

环境变量说明

注意事项

• 工具权限：执行工具的数据库用户需具有对应操作权限（如pg_dump需SELECT权限，pg_dumpall需超级用户权限）
• 网络配置：确保容器与目标PostgreSQL数据库之间网络连通（可通过--network参数指定Docker网络）
• 备份文件存储：建议通过-v挂载本地目录或持久化卷（Volume）保存备份文件，避免容器删除后文件丢失
• 镜像版本：建议使用指定版本标签（如:14对应PostgreSQL 14工具集），避免因工具版本与数据库版本不兼容导致问题