跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

扩展

pgcli PostgreSQL 扩展指南

pgcli 支持从 Pigsty DEB 仓库安装和管理 PostgreSQL 扩展。

工作原理

扩展被烘焙到派生容器镜像中:

  1. pg extension install 构建新镜像(基于当前镜像 + Pigsty 仓库 + 扩展包)
  2. 停止并移除旧容器
  3. 从新镜像重新创建容器(主机数据卷被保留)
  4. 更新配置文件中的 image_tag

这种方法的优势:

  • 扩展在容器重建后仍然存在(烘焙到镜像层)
  • pg start 不需要在每次启动时运行 apt-get install
  • 扩展文件是持久的并与容器生命周期解耦

命令

安装扩展

# 安装单个扩展
pg extension install pg_stat_statements

# 安装多个扩展(单次镜像构建,逗号分隔)
pg extension install pgmq,uuid-ossp,pg_stat_statements

# 针对特定实例
pg extension install pg_stat_statements -i pg01

重启确认: 需要 shared_preload_libraries 的扩展(例如 pg_stat_statements、pg_cron)需要 PostgreSQL 重启。默认情况下,会提示你确认:

# 交互式确认(默认)
pg extension install pg_stat_statements
# 输出:
# Installing extensions that require shared_preload_libraries will cause a PostgreSQL restart.
# Extensions to be installed: [pg_stat_statements]
# This will cause a brief interruption to database connections.
# Restart PostgreSQL now? [y/N]:

# 跳过确认并自动重启
pg extension install pg_stat_statements --auto-restart

如果你拒绝重启,可以稍后应用更改:

pg stop -i pg01
pg start -i pg01

列出已安装扩展

pg extension list -i pg01

示例输出:

Installed extensions in "pg01":
  pg_stat_statements (managed)
  uuid-ossp (managed)
  plpgsql (unmanaged)
  • managed:由 pgcli 跟踪(记录在配置中,包含在镜像中)
  • unmanaged:手动安装的扩展(不在配置中跟踪)

移除扩展

pg extension remove pgmq -i pg01

工作流:

  1. DROP EXTENSION IF EXISTS pgmq
  2. 更新配置和 shared_preload_libraries
  3. 无镜像重建 — -ext 镜像在实例间共享,包永远不会被卸载

重启确认: 如果移除需要 shared_preload_libraries 的扩展(例如 pg_stat_statements、pg_cron),会在重启前提示你确认:

# 交互式确认(默认)
pg extension remove pg_stat_statements -i pg01
# 输出:
# Removing extensions that require shared_preload_libraries will cause a PostgreSQL restart.
# Extensions to be removed: [pg_stat_statements]
# This will cause a brief interruption to database connections.
# Restart PostgreSQL now? [y/N]:

# 跳过确认并自动重启
pg extension remove pg_stat_statements -i pg01 --auto-restart

如果你拒绝重启,可以稍后应用更改:

pg stop -i pg01
pg start -i pg01

查看可用扩展

pg extension available

列出所有 440 个已知扩展:

  • 45 个内置(contrib,已在基础镜像中——无需镜像构建)
  • 395 个 Pigsty 目录(来自 Pigsty DEB 仓库,需要镜像构建)

扩展目录

参见扩展目录获取 45 个内置扩展完整列表(无需安装)。

参见常用扩展获取常用扩展详细使用示例。

目录外的扩展

只有目录中的扩展(builtin + Pigsty)可以通过 pg extension install 安装。未知扩展名称会在构建开始前被拒绝:

  [X] Unknown extension(s): [nonexistent_ext]

      These extensions are not in the Pigsty catalog or builtin contrib list.
      Check available extensions: pg extension available
      Full Pigsty catalog: https://pigsty.cc/ext/list/

完整目录:https://pigsty.cc/ext/list/

配置

安装扩展后,配置会被更新:

instances:
  pg01:
    extensions:
      - pg_stat_statements
      - uuid-ossp
      - pgmq
    podman:
      image_tag: ghcr.io/mars-base/pgcli/pgcli-pg:18-2.58.0-ext

image_tag 指向包含所有已安装扩展的派生镜像。

共享预加载库

需要 shared_preload_libraries 的扩展会在 postgresql.conf 中自动配置:

# === pgcli extensions (managed — do not edit) ===
shared_preload_libraries = 'pg_stat_statements,pg_cron'
# === end pgcli extensions ===

必须最先加载的扩展(如 citus、timescaledb)会自动放在位置 0,不管安装 顺序如何 —— 如果它们出现在其他位置,PostgreSQL 会 FATAL。

这是 postmaster 级别参数;更改后必须重启 PostgreSQL。

故障排除

扩展安装失败

  [X] Unknown extension(s): [nonexistent_ext]

原因:扩展名称不在内置 contrib 列表或 Pigsty 目录中。

解决方法:

  • 验证扩展名称:pg extension available
  • 检查 Pigsty 目录:https://pigsty.cc/ext/list/
  • 注意确切的 SQL 扩展名称(例如 vector 而不是 pgvector)

CREATE EXTENSION 失败

ERROR: extension "pgmq" already exists

扩展已安装但未在配置中跟踪。你可以安全地忽略这个,或手动将其添加到配置:

extensions:
  - pgmq

共享预加载库冲突

如果 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 - 扩展目录

基础镜像中内置的 PostgreSQL 扩展列表

本页列出基础镜像中所有内置扩展。使用示例请参见常用扩展。

内置扩展(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 扩展的使用示例

最常用 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 重启后预加载表数据。
# 一次性安装所有扩展
pg extension install pg_stat_statements,pg_repack,pg_prewarm --auto-restart

# 查找 top 5 慢查询
pg exec "SELECT query, calls, total_exec_time::numeric(10,2) AS ms
         FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;"

# 重组膨胀表
pg exec -- pg_repack -U admin -d default_db -t my_table --no-superuser-check

# 预热表
pg exec "SELECT pg_prewarm('my_table');"

数据类型与标识符

扩展 安装 描述
uuid-ossp 内置 UUID 生成(v1/v3/v5)。PG 18 已内置 gen_random_uuid() (v4) 和 uuidv7() (v7)——无需安装扩展。
hstore 内置 键值对存储。
citext 内置 不区分大小写的文本。Foo = foo。
# UUID 生成(PG 18 内置——无需安装扩展)
pg exec "SELECT gen_random_uuid();"  # v4 随机 UUID(PG 13 起内置)
pg exec "SELECT uuidv7();"           # v7 时间有序 UUID(PG 18 新增)

# uuid-ossp 扩展——仅在需要 v1/v3/v5 UUID 时安装
pg exec "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"
pg exec "SELECT uuid_generate_v1();"  # v1 时间戳 + MAC 地址
pg exec "SELECT uuid_generate_v3(uuid_ns_url(), 'https://example.com');"  # v3 基于 MD5
pg exec "SELECT uuid_generate_v5(uuid_ns_url(), 'https://example.com');"  # v5 基于 SHA-1

# 键值存储
pg exec "SELECT 'theme => dark, lang => en'::hstore -> 'theme';"
# 返回: dark

# 不区分大小写匹配
pg exec "CREATE TABLE users (email citext);
         INSERT INTO users VALUES ('Alice@Example.COM');
         SELECT * FROM users WHERE email = 'alice@example.com';"

搜索与文本

扩展 安装 描述
pg_trgm 内置 三元组相似性,用于模糊搜索和自动补全。
unaccent 内置 去除重音,用于灵活的国际化文本搜索。
# 模糊搜索
pg exec "SELECT name, similarity(name, 'John') FROM users
         ORDER BY similarity(name, 'John') DESC LIMIT 5;"

# 创建三元组索引加速模糊搜索
pg exec "CREATE INDEX users_name_trgm_idx ON users USING gin (name gin_trgm_ops);"

# 去除重音
pg exec "SELECT unaccent('Crème Brûlée');"  -- 返回 'Creme Brulee'

# 组合使用实现不区分重音的模糊搜索
pg exec "SELECT name FROM users WHERE name % unaccent('Creme Brulee');"

安全与加密

扩展 安装 描述
pgcrypto 内置 哈希、加密/解密、随机数生成。
pgaudit pg extension install pgaudit 审计日志。合规(GDPR、HIPAA、SOX)必需。
# 使用 bcrypt 哈希密码
pg exec "SELECT crypt('my_password', gen_salt('bf'));"

# 验证密码
pg exec "SELECT (crypt('my_password', stored_hash) = stored_hash);"

# 对称加密/解密
pg exec "SELECT pgp_sym_decrypt(pgp_sym_encrypt('secret', 'key'), 'key');"

# 启用特定操作的审计日志
pg exec "SET pgaudit.log = 'read, ddl';"

地理空间

扩展 安装 描述
postgis pg extension install postgis 完整空间数据库:几何类型、空间索引、距离/面积计算。
pg extension install postgis --auto-restart

# 创建包含空间数据的表
pg exec "CREATE TABLE places (id serial, name text, geom geometry(Point, 4326));"
pg exec "INSERT INTO places (name, geom) VALUES
         ('San Francisco', ST_MakePoint(-122.4, 37.8)),
         ('London', ST_MakePoint(-0.1276, 51.5074));"

# 查找 5km 范围内的地点
pg exec "SELECT name FROM places
         WHERE ST_DWithin(geom, ST_MakePoint(-122.4, 37.8)::geography, 5000);"

# 计算两个城市间的距离(米)
pg exec "SELECT ST_Distance(
           ST_MakePoint(-74.006, 40.7128)::geography,
           ST_MakePoint(-0.1276, 51.5074)::geography);"

AI 与向量搜索

扩展 安装 描述
pgvector pg extension install vector 存储和搜索嵌入向量。AI 应用标准。
pg extension install vector --auto-restart

# 创建带向量列的表
pg exec "CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3));"
pg exec "INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');"

# 查找最近邻(欧几里得距离)
pg exec "SELECT id FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;"

# 创建 IVFFlat 索引加速近似搜索
pg exec "CREATE INDEX items_embedding_idx ON items USING ivfflat (embedding vector_l2_ops);"

时序数据

扩展 安装 描述
timescaledb pg extension install timescaledb 优化的时序存储,支持超级表。
pg extension install timescaledb --auto-restart

# 创建超级表
pg exec "CREATE TABLE sensor (time timestamptz NOT NULL, value float);
         SELECT create_hypertable('sensor', 'time');"

# 时间桶聚合
pg exec "SELECT time_bucket('1 hour', time) AS bucket, avg(value)
         FROM sensor GROUP BY bucket ORDER BY bucket;"

定时任务与分布式

扩展 安装 描述
pg_cron pg extension install pg_cron Cron 定时任务调度器。pgcli 自动配置。
citus pg extension install citus 分布式 PostgreSQL,支持分片。
pg extension install pg_cron --auto-restart

# 调度每日清理任务(午夜运行)
pg exec "SELECT cron.schedule('cleanup', '0 0 * * *',
         'DELETE FROM logs WHERE created_at < now() - interval ''30 days''');"

# 列出已调度的任务
pg exec "SELECT jobid, schedule, command FROM cron.job;"

# 取消调度
pg exec "SELECT cron.unschedule('cleanup');"

外部数据

扩展 安装 描述
postgres_fdw 内置 将外部 PostgreSQL 服务器作为本地表查询。
pg_duckdb pg extension install pg_duckdb 嵌入式 DuckDB 分析引擎。读取 Parquet/CSV,OLAP 查询加速。
# 创建外部服务器
pg exec "CREATE SERVER remote FOREIGN DATA WRAPPER postgres_fdw
         OPTIONS (host '10.0.0.2', port '5432', dbname 'analytics');"

# 创建用户映射
pg exec "CREATE USER MAPPING FOR current_user SERVER remote
         OPTIONS (user 'reader', password 'secret');"

# 导入远程 schema 作为外部表
pg exec "IMPORT FOREIGN SCHEMA public FROM SERVER remote INTO remote_schema;"

# 像查询本地表一样查询远程数据
pg exec "SELECT * FROM remote_schema.events LIMIT 10;"
pg extension install pg_duckdb --auto-restart

# 在 DuckDB 中执行 SQL —— duckdb.query 是表函数(必须在 FROM 子句中使用)
pg exec "SELECT * FROM duckdb.query(\$\$ SELECT 42 AS answer, 'hello' AS msg \$\$);"

# 将表导出为 Parquet 文件
pg exec "COPY my_table TO '/tmp/my_table.parquet' (FORMAT 'parquet');"

# 直接读取 Parquet/CSV 文件
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT * FROM read_parquet('/tmp/my_table.parquet') WHERE id > 2 \$\$);"

# 将整个查询下推到 DuckDB 执行(OLAP 加速)
pg exec "SET duckdb.force_execution = true;
         SELECT category, sum(amount) FROM sales GROUP BY category;"

# 纯 DuckDB SQL(完全绕过 PostgreSQL 规划器)
pg exec "SELECT * FROM duckdb.raw_query(\$\$ SELECT range AS n FROM range(1, 6) \$\$);"

# --- 从 S3 / MinIO 读取文件(无需复制文件) ---

# 先创建 S3 secret(use_ssl 是文本类型:'true'/'false')
pg exec "SELECT duckdb.create_simple_secret('S3', '<access_key>', '<secret_key>',
         '', 'us-east-1', 'path', '', 'minio.example.com:9000',
         's3://bucket', '', 'false');"

# 直接查询 bucket 中的 CSV
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT category, count(*) AS cnt, sum(sales) AS total_sales
         FROM read_csv('s3://bucket/products.csv', auto_detect=true)
         GROUP BY category ORDER BY total_sales DESC \$\$);"

兼容性说明

扩展 PG 18 状态 备注
pgml 不可用 仅支持 PG 14-17(无 PG 18 包)
uuid-ossp 部分需要 PG 18 内置:gen_random_uuid() (v4)、uuidv7() (v7)。扩展仅在需要 v1/v3/v5 时安装