这是本节的多页打印视图。 .
扩展
pgcli 支持从 Pigsty DEB 仓库安装和管理 PostgreSQL 扩展。
工作原理
扩展被烘焙到派生容器镜像中:
pg extension install构建新镜像(基于当前镜像 + Pigsty 仓库 + 扩展包)- 停止并移除旧容器
- 从新镜像重新创建容器(主机数据卷被保留)
- 更新配置文件中的
image_tag
这种方法的优势:
- 扩展在容器重建后仍然存在(烘焙到镜像层)
pg start不需要在每次启动时运行apt-get install- 扩展文件是持久的并与容器生命周期解耦
命令
安装扩展
重启确认: 需要 shared_preload_libraries 的扩展(例如 pg_stat_statements、pg_cron)需要 PostgreSQL 重启。默认情况下,会提示你确认:
如果你拒绝重启,可以稍后应用更改:
列出已安装扩展
示例输出:
- managed:由 pgcli 跟踪(记录在配置中,包含在镜像中)
- unmanaged:手动安装的扩展(不在配置中跟踪)
移除扩展
工作流:
DROP EXTENSION IF EXISTS pgmq- 更新配置和
shared_preload_libraries - 无镜像重建 —
-ext镜像在实例间共享,包永远不会被卸载
重启确认: 如果移除需要 shared_preload_libraries 的扩展(例如 pg_stat_statements、pg_cron),会在重启前提示你确认:
如果你拒绝重启,可以稍后应用更改:
查看可用扩展
列出所有 440 个已知扩展:
- 45 个内置(contrib,已在基础镜像中——无需镜像构建)
- 395 个 Pigsty 目录(来自 Pigsty DEB 仓库,需要镜像构建)
扩展目录
参见扩展目录获取 45 个内置扩展完整列表(无需安装)。
参见常用扩展获取常用扩展详细使用示例。
目录外的扩展
只有目录中的扩展(builtin + Pigsty)可以通过 pg extension install 安装。未知扩展名称会在构建开始前被拒绝:
完整目录:https://pigsty.cc/ext/list/
配置
安装扩展后,配置会被更新:
image_tag 指向包含所有已安装扩展的派生镜像。
共享预加载库
需要 shared_preload_libraries 的扩展会在 postgresql.conf 中自动配置:
必须最先加载的扩展(如 citus、timescaledb)会自动放在位置 0,不管安装
顺序如何 —— 如果它们出现在其他位置,PostgreSQL 会 FATAL。
这是 postmaster 级别参数;更改后必须重启 PostgreSQL。
故障排除
扩展安装失败
原因:扩展名称不在内置 contrib 列表或 Pigsty 目录中。
解决方法:
- 验证扩展名称:
pg extension available - 检查 Pigsty 目录:https://pigsty.cc/ext/list/
- 注意确切的 SQL 扩展名称(例如
vector而不是pgvector)
CREATE EXTENSION 失败
扩展已安装但未在配置中跟踪。你可以安全地忽略这个,或手动将其添加到配置:
共享预加载库冲突
如果 shared_preload_libraries 在 postgresql.conf 中被手动编辑,pgcli 的标记块会覆盖它。
解决方法:删除手动配置并让 pgcli 管理它。
注释
- 扩展数量:45 个内置(contrib)+ 395 个 Pigsty 目录 = 440 个已知扩展
- 镜像大小:每个扩展增加 10-50MB 到镜像,但 Pigsty 包已优化
- 构建时间:首次扩展安装需要 1-3 分钟(下载 + 构建);后续安装更快(缓存命中)
- 副本行为:副本可以安装扩展,但
CREATE EXTENSION会被拒绝(只读)。在主实例上安装;副本通过物理复制同步 - 扩展升级:
ALTER EXTENSION ... UPDATE TO ...尚不支持;通过pg exec手动运行
1 - 扩展目录
本页列出基础镜像中所有内置扩展。使用示例请参见常用扩展。
内置扩展(45 个)
这些扩展已包含在 PostgreSQL 基础镜像中,无需镜像构建或 pg extension install。直接运行 CREATE EXTENSION 即可启用。
需要 shared_preload_libraries
这些扩展启用后需要重启 PostgreSQL。通过 pg extension install 安装时,pgcli 会自动处理重启。
| 扩展 | 描述 |
|---|---|
pg_stat_statements |
SQL 性能分析——跟踪查询执行次数、时间和资源使用 |
pg_cron |
数据库内置 Cron 定时任务调度器 |
pg_hint_plan |
查询提示,影响查询计划器 |
pg_stat_monitor |
高级性能监控,包含查询计划 |
pg_qualstats |
查询谓词统计,用于索引推荐 |
pg_stat_kcache |
内核级 CPU/IO 性能统计 |
pg_wait_sampling |
等待事件采样,用于性能分析 |
pg_track_settings |
跟踪配置变更历史 |
timescaledb |
时序数据库扩展,支持超级表 |
pg_prewarm |
重启后将表数据预加载到共享缓冲区 |
无需重启
这些扩展可以通过 CREATE EXTENSION 立即启用,无需重启。
| 扩展 | 描述 |
|---|---|
uuid-ossp |
UUID 生成函数(v1/v3/v4/v5) |
hstore |
单列键值对存储 |
pgcrypto |
哈希(bcrypt/sha256)、加密/解密、随机数生成 |
pg_trgm |
三元组相似性匹配,用于模糊搜索 |
unaccent |
去除字符重音,用于国际化文本搜索 |
fuzzystrmatch |
模糊字符串匹配(Levenshtein、Soundex、Metaphone) |
intarray |
整数数组操作(去重、排序、交集) |
isn |
ISBN/ISSN/EAN 标准数字类型及验证 |
pg_repack |
在线表重组,无需排他锁 |
pg_squeeze |
表空间回收 |
pg_partman |
自动分区管理 |
pgvector (Pigsty) |
向量相似性搜索,用于 AI 应用 |
postgis (Pigsty) |
地理空间数据支持 |
pgmq (Pigsty) |
轻量级消息队列 |
tablefunc |
交叉表/透视表函数 |
btree_gist |
GiST 索引的 B-tree 支持 |
btree_gin |
GIN 索引的 B-tree 支持 |
citext |
不区分大小写的文本类型 |
cube |
多维立方体数据类型 |
ltree |
层次化标签树数据类型 |
seg |
浮点区间数据类型 |
earthdistance |
地球表面大圆距离计算 |
postgres_fdw |
将外部 PostgreSQL 服务器作为本地表查询 |
file_fdw |
将服务器文件作为外部表读取 |
dblink |
连接其他 PostgreSQL 数据库 |
amcheck |
验证 B-tree 索引完整性 |
pageinspect |
底层页面检查,用于调试 |
pg_buffercache |
查看共享缓冲区内容 |
pg_freespacemap |
查看表的空闲空间映射 |
pg_visibility |
查看表的可见性映射 |
pg_walinspect |
检查 WAL 记录 |
pgstattuple |
表级元组统计 |
pgrowlocks |
显示行级锁信息 |
pg_surgery |
底层堆元组操作 |
xml2 |
XML 解析和 XPath 函数 |
dict_int |
整数文本搜索字典 |
dict_xsyn |
扩展同义词文本搜索字典 |
bloom |
布隆过滤器索引访问方法 |
autoinc |
自增触发器函数 |
insert_username |
插入用户名触发器函数 |
moddatetime |
自动更新时间戳触发器 |
refint |
引用完整性触发器函数 |
tcn |
触发器变更通知 |
sslinfo |
SSL 连接信息函数 |
lo |
大对象类型支持 |
intagg |
整数数组聚合/枚举 |
tsm_system_rows |
按行数进行表采样 |
tsm_system_time |
按时间进行表采样 |
pg_logicalinspect |
逻辑复制槽检查 |
2 - 常用扩展
最常用 PostgreSQL 扩展的使用示例,已在 PG 18 + pgcli 环境下测试通过。
性能与监控
| 扩展 | 安装 | 描述 |
|---|---|---|
pg_stat_statements |
pg extension install pg_stat_statements |
SQL 性能分析。生产环境必备。 |
pg_repack |
pg extension install pg_repack |
在线表重组,回收膨胀空间。 |
pg_prewarm |
pg extension install pg_prewarm |
重启后预加载表数据。 |
数据类型与标识符
| 扩展 | 安装 | 描述 |
|---|---|---|
uuid-ossp |
内置 | UUID 生成(v1/v3/v5)。PG 18 已内置 gen_random_uuid() (v4) 和 uuidv7() (v7)——无需安装扩展。 |
hstore |
内置 | 键值对存储。 |
citext |
内置 | 不区分大小写的文本。Foo = foo。 |
搜索与文本
| 扩展 | 安装 | 描述 |
|---|---|---|
pg_trgm |
内置 | 三元组相似性,用于模糊搜索和自动补全。 |
unaccent |
内置 | 去除重音,用于灵活的国际化文本搜索。 |
安全与加密
| 扩展 | 安装 | 描述 |
|---|---|---|
pgcrypto |
内置 | 哈希、加密/解密、随机数生成。 |
pgaudit |
pg extension install pgaudit |
审计日志。合规(GDPR、HIPAA、SOX)必需。 |
地理空间
| 扩展 | 安装 | 描述 |
|---|---|---|
postgis |
pg extension install postgis |
完整空间数据库:几何类型、空间索引、距离/面积计算。 |
AI 与向量搜索
| 扩展 | 安装 | 描述 |
|---|---|---|
pgvector |
pg extension install vector |
存储和搜索嵌入向量。AI 应用标准。 |
时序数据
| 扩展 | 安装 | 描述 |
|---|---|---|
timescaledb |
pg extension install timescaledb |
优化的时序存储,支持超级表。 |
定时任务与分布式
| 扩展 | 安装 | 描述 |
|---|---|---|
pg_cron |
pg extension install pg_cron |
Cron 定时任务调度器。pgcli 自动配置。 |
citus |
pg extension install citus |
分布式 PostgreSQL,支持分片。 |
外部数据
| 扩展 | 安装 | 描述 |
|---|---|---|
postgres_fdw |
内置 | 将外部 PostgreSQL 服务器作为本地表查询。 |
pg_duckdb |
pg extension install pg_duckdb |
嵌入式 DuckDB 分析引擎。读取 Parquet/CSV,OLAP 查询加速。 |
兼容性说明
| 扩展 | PG 18 状态 | 备注 |
|---|---|---|
pgml |
不可用 | 仅支持 PG 14-17(无 PG 18 包) |
uuid-ossp |
部分需要 | PG 18 内置:gen_random_uuid() (v4)、uuidv7() (v7)。扩展仅在需要 v1/v3/v5 时安装 |