企业官网建设流程全解析

如何10分钟安装配置pg_pathman：从零到第一个分区的完整指南（含2个常见坑）

【免费下载链接】pg_pathmanPartitioning tool for PostgreSQL项目地址: https://gitcode.com/gh_mirrors/pg/pg_pathman

👋 还在为大表性能头疼吗？本文带你用 10 分钟完成pg_pathman的安装与配置。pg_pathman 是 PostgreSQL 的经典表分区工具（分区扩展），支持 RANGE 与 HASH 两种分区方案，能显著加速海量数据的查询与管理。

📌 先说明一句：pg_pathman 当前版本为 1.5.12，支持 PostgreSQL 11 ~ 15。项目已进入维护状态（不再新功能开发），官方建议新库可评估 PostgreSQL 10+ 自带的原生分区。但若你维护的是 11~15 的存量库、又想要比原生分区更强的管理函数（拆分/合并/自动建分区/跨分区更新等），pg_pathman 依然是利器。

一、安装前准备：版本兼容性快速核对

在动手前，先确认你的 PostgreSQL 版本在支持范围内：

11 / 14 / 15 版本对应的内核补丁已随仓库提供，见补丁目录：patches/（内含各 REL 版本的 core diff 文件）。

二、一键编译安装 pg_pathman（含坑1）

1. 获取源码

git clone https://gitcode.com/gh_mirrors/pg/pg_pathman cd pg_pathman

2. 编译并安装

make install USE_PGXS=1

⚠️坑1：PG_CONFIG 指错 PostgreSQL如果你的 PostgreSQL 是非默认安装（自己编译、Docker 容器、多版本共存），USE_PGXS=1会默认找系统里的第一个pg_config，可能装错版本导致"找不到共享库"。解决办法是显式指定：

make install USE_PGXS=1 PG_CONFIG=/your/pg/path/bin/pg_config

可用which -a pg_config或ls /usr/lib/postgresql/*/bin确认正确路径。

安装成功后，pg_pathman的.so会进入 PostgreSQL 的lib目录，扩展脚本pg_pathman--1.5.sql会进入extension目录（见pg_pathman.control中的声明）。

三、修改配置：预加载库（含坑2）

1. 修改 postgresql.conf

找到postgresql.conf，修改（或追加）这一行：

shared_preload_libraries = 'pg_pathman'

仓库中的conf.add文件就是这一行的现成配置示例，可直接参考。

2. 重启数据库（必须！）

sudo systemctl restart postgresql

⚠️坑2：只改了配置忘了重启 / 与其他扩展顺序冲突shared_preload_libraries只在数据库启动时生效，reload无效，必须 restart。

另外 pg_pathman 使用了ProcessUtility_hook等钩子函数，与同样使用钩子的扩展（如pg_stat_statements）可能偶发冲突。若遇到怪异报错，请按顺序书写：

shared_preload_libraries = 'pg_stat_statements, pg_pathman'

简单记忆：把 pg_pathman 放在最后，让它最先执行钩子。

四、创建扩展：3 条 SQL 搞定

连接数据库（psql -U postgres），执行：

CREATE SCHEMA pathman; GRANT USAGE ON SCHEMA pathman TO PUBLIC; CREATE EXTENSION pg_pathman WITH SCHEMA pathman;

验证是否加载成功：

SELECT pathman_version();

返回类似1.5.12的完整版本号即代表安装成功 🎉

🔒 安全小贴士：建议把 pg_pathman 装到一个干净的 schema，并限制非超级用户的 CREATE 权限，避免函数被恶意重载（search-path 攻击面）。

五、10 分钟内的第一个分区：RANGE 分区实战

下面用一个"日志表按天分区"的经典场景走完全流程。

1. 建表并灌入示例数据

CREATE TABLE journal ( id SERIAL, dt TIMESTAMP NOT NULL, level INTEGER, msg TEXT ); CREATE INDEX ON journal(dt); INSERT INTO journal (dt, level, msg) SELECT g, random() * 6, md5(g::text) FROM generate_series('2015-01-01'::date, '2015-12-31'::date, '1 minute') g;

2. 一条函数调用完成 RANGE 分区

SELECT create_range_partitions('journal', 'dt', '2015-01-01'::date, '1 day'::interval);

这一步会：按dt列、以"1 天"为步长，自动创建 365 个分区，并把父表数据迁移到各分区（父表随后被自动禁用，只留索引原型）。

3. 看效果：查询计划只扫 2 个分区

EXPLAIN SELECT * FROM journal WHERE dt >= '2015-06-01' AND dt < '2015-06-03';

计划里只会出现journal_152、journal_153两个分区的 Seq Scan —— 这就是分区裁剪的威力：扫描量从全年直接缩小到 2 天。

4. 顺手体验 HASH 分区

CREATE TABLE items (id SERIAL PRIMARY KEY, name TEXT, code BIGINT); SELECT create_hash_partitions('items', 'id', 100);

按id哈希成 100 个分区，插入时由PartitionFilter自定义计划节点自动把行路由到对应分区，无需触发器。

六、常用管理命令速查清单 🧰

完成初始分区后，日常运维高频函数：

💡 小贴士：RANGE 分区默认开启自动建分区——当 INSERT 的数据超出已有范围时，pg_pathman 会自动追加新分区，日志表几乎可以"零维护"运行。

七、排错锦囊：开关与应急

遇到疑难杂症时，先看 GUC 开关逐项关闭定位，再看pathman_config（主配置表）和pathman_config_params（可选参数表）中的记录是否与预期一致。

八、写在最后

至此，你已用大约 10 分钟完成了 pg_pathman 的编译安装 → 配置预加载 → 创建扩展 → 建立第一个 RANGE 分区的完整闭环，并避开了 PG_CONFIG 指错版本、忘记重启/扩展顺序冲突这两个最常见的坑。

后续可以进一步探索项目源码：核心逻辑位于src/目录（如pl_range_funcs.c实现 RANGE 分区函数、partition_router.c实现跨分区 UPDATE 路由），测试用例在sql/与tests/目录中，都是很好的学习材料。祝你的大表从此飞起！🚀

【免费下载链接】pg_pathmanPartitioning tool for PostgreSQL项目地址: https://gitcode.com/gh_mirrors/pg/pg_pathman