huntress/postgres-partman

PostgreSQL with pg_partman 镜像文档

镜像概述

本镜像基于官方PostgreSQL数据库构建，预安装并配置了pg_partman扩展。pg_partman是一款强大的表分区管理工具，专为简化PostgreSQL表分区（尤其是时间序列数据）的创建、维护和自动化管理而设计，支持自动分区创建、过期分区清理、分区模板定制等功能，适用于需要高效管理大量时序数据或大型分区表的场景。

核心功能与特性

• 预集成pg_partman：无需手动安装配置，镜像启动后即可使用pg_partman扩展
• 多分区类型支持：兼容时间序列分区（按秒、分钟、小时、天、月等）、列表分区及范围分区
• 自动化分区管理：
  • 自动创建未来分区（如提前创建未来30天的日分区）
  • 自动清理过期分区（支持按时间或数量阈值删除/归档旧分区）
• 原生兼容性：与PostgreSQL 10+原生分区功能完全兼容，支持分区表查询优化
• 灵活配置：支持自定义分区间隔、保留策略、分区模板及通知机制
• 轻量级集成：基于官方PostgreSQL镜像构建，保持原版镜像特性与性能

使用场景

• 时间序列数据存储：日志系统、监控指标（如Prometheus数据）、IoT传感器数据等需按时间分区的场景
• 大型数据集管理：需按业务维度（如用户ID、地区）进行列表/范围分区的超大型表
• 自动化运维需求：数据库管理员需减少手动分区维护工作量的生产环境
• 开发测试环境：快速搭建带分区功能的PostgreSQL环境，验证分区策略
• 历史数据归档：需定期归档或清理过期数据（如保留最近6个月数据）的业务系统

使用方法与配置说明

1. 基本运行

使用以下命令启动容器，映射端口并设置数据库密码：

bash
docker run -d \
  --name pg-partman-db \
  -e POSTGRES_PASSWORD=StrongPassword123 \
  -e POSTGRES_USER=dbadmin \
  -e POSTGRES_DB=timeseries_db \
  -p 5432:5432 \
  postgres-with-pg_partman:latest

2. 启用pg_partman扩展

容器启动后，通过psql连接数据库并启用扩展（首次使用需执行）：

bash
# 进入容器
docker exec -it pg-partman-db psql -U dbadmin -d timeseries_db

# 在数据库中启用pg_partman
CREATE EXTENSION pg_partman;

3. 创建分区表示例（时间序列分区）

以按天分区的日志表为例，创建自动维护的分区结构：

sql
-- 创建父表（注意：父表需为未分区表，由pg_partman管理分区）
CREATE TABLE metrics (
  id SERIAL,
  metric_name TEXT,
  value NUMERIC,
  recorded_at TIMESTAMPTZ NOT NULL
);

-- 使用pg_partman创建时间序列分区（按天分区，保留30天数据，提前创建7天分区）
SELECT partman.create_parent(
  p_parent_table => 'public.metrics',  -- 父表名
  p_control => 'recorded_at',         -- 分区控制字段（时间类型）
  p_type => 'time',                   -- 分区类型（time/list/range）
  p_interval => 'daily',              -- 分区间隔（hourly/monthly等）
  p_retention := '30 days',           -- 保留30天数据
  p_premake := 7                      -- 提前创建7天的未来分区
);

4. 配置自动分区维护

pg_partman依赖定期执行维护函数以创建/清理分区，推荐通过以下方式配置：

方式1：使用cron任务（需容器内安装cron）

bash
# 在容器内添加cron任务（每天凌晨2点执行维护）
echo "0 2 * * * psql -U dbadmin -d timeseries_db -c 'SELECT partman.run_maintenance();'" | crontab -

方式2：使用pg_cron扩展（若已安装）

sql
-- 创建定时任务（每小时执行一次维护）
SELECT cron.schedule(
  'pg_partman_maintenance',
  '0 * * * *',
  'SELECT partman.run_maintenance();'
);

环境变量配置

docker-compose示例

yaml
version: '3.8'
services:
  pg-partman:
    image: postgres-with-pg_partman:latest
    container_name: pg-partman
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: StrongPassword123
      POSTGRES_USER: dbadmin
      POSTGRES_DB: metrics_db
      PG_PARTMAN_RETENTION: "90 days"
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  pg_data:

注意事项

• 首次使用需启用扩展：必须执行CREATE EXTENSION pg_partman;才能使用分区功能
• 维护任务依赖：自动分区创建/清理需确保partman.run_maintenance()定期执行
• 分区间隔选择：根据数据量调整分区间隔（如高频数据用小时分区，低频用月分区）
• 备份策略：分区表备份需确保包含所有子分区，推荐使用pg_dump -Fc格式
• 版本兼容性：确保镜像PostgreSQL版本与pg_partman版本兼容（参考https://github.com/pgpartman/pg_partman%EF%BC%89

扩展阅读

• https://github.com/pgpartman/pg_partman
• PostgreSQL分区表官方指南