加载扩展
Module:
除了纯 SQL 编写的扩展外,绝大多数扩展都会提供一个 .so
文件,这是一个动态连接库文件。大部分扩展并不需要显式加载,只需要通过 CREATE EXTENSION
直接启用 即可。
但一小部分扩展使用了 PostgreSQL 的 Hook 机制,要启用 这些扩展 需要一个额外的加载步骤 —— 您需要修改 PostgreSQL 集群的 shared_preload_libraries
参数,然后重启数据库服务器使其生效。
如果您在未加载/重启生效的情况下直接执行 CREATE EXTENSION
会报错。
快速上手
例如,在 conf/app/supa
配置模板中,我们定义了 Supabase 需要的扩展列表,并显式指定了 pg_libs
参数,用于加载扩展:
all:
children:
pg-meta:
hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
vars:
pg_cluster: pg-meta
pg_databases:
- name: postgres
pg_libs: 'timescaledb, plpgsql, plpgsql_check, pg_cron, pg_net, pg_stat_statements, auto_explain, pg_tle, plan_filter'
schemas: [ extensions ,auth ,realtime ,storage ,graphql_public ,supabase_functions ,_analytics ,_realtime ]
extensions: # 这里定义了在 postgres 数据库中 创建启用 的扩展列表
- { name: pgcrypto ,schema: extensions } # 加密函数
- { name: pg_net ,schema: extensions } # 异步 HTTP
- { name: pgjwt ,schema: extensions } # PostgreSQL 的 JSON Web Token API
- { name: uuid-ossp ,schema: extensions } # 生成通用唯一标识符 (UUID)
- { name: pgsodium } # pgsodium 是 PostgreSQL 的现代加密库
- { name: supabase_vault } # Supabase 保险库扩展
- { name: pg_graphql } # pg_graphql: GraphQL 支持
- { name: pg_jsonschema } # pg_jsonschema: 验证 JSON 模式
- { name: wrappers } # wrappers: 外部数据包装器集合
- { name: http } # http: 允许在数据库内检索网页
- { name: pg_cron } # pg_cron: PostgreSQL 的任务调度器
- { name: timescaledb } # timescaledb: 支持时间序列数据的可扩展插入和复杂查询
- { name: pg_tle } # pg_tle: PostgreSQL 的可信语言扩展
- { name: vector } # pgvector: 向量相似性搜索
- { name: pgmq } # pgmq: 类似 AWS SQS 和 RSMQ 的轻量级消息队列
并非所有扩展都需要通过 pg_libs
进行动态加载,例如这里的 pgcrypto
, pgjwt
, vector
等扩展,需要动态加载的扩展,请参考 需要加载的扩展 列表。
默认加载的扩展
在 Pigsty 中,默认会加载以下两个 PostgreSQL 第一方自带的 Contrib 扩展:
auto_explain
用于提供一种自动记录慢查询执行计划的手段,用于微观优化特定慢查询 SQLpg_stat_statements
用于跟踪所有执行的 SQL 语句的计划和执行统计信息,用于宏观统计一类 SQL 的执行指标
这是两个用于 PostgreSQL 宏观/微观查询优化 的重要自带扩展插件,因此在 Pigsty 中,pg_libs
的默认值是 pg_stat_statements, auto_explain
,
我们强烈建议您在配置加载项时保留这两个扩展,只需要在修改 pg_libs
,pg_parameters
或者直接修改 shared_preload_libraries
参数时将这两项保留即可。
修改集群配置
要修改 PostgreSQL 集群配置,有许多不同的方式,在 Pigsty 中,我们建议:
对于尚未创建的新集群,您可以在 pg_libs
参数中进行配置,指定 shared_preload_libraries
参数的初始值。
请注意,pg_libs
仅在 创建集群 时生效,在集群创建后,该参数被指定为真正的 PostgreSQL 参数 shared_preload_libraries
的初始值。
如果您需要修改默认加载的扩展,通常可以通过 Patroni 命令行 修改集群配置,直接修改 shared_preload_libraries
参数,应用后重启数据库集群生效。
对于已经初始化好的集群,您可以通过 Patroni 命令行 修改集群配置 来修改 shared_preload_libraries
参数,应用后重启数据库集群生效。
当然您也可以通过其他方式修改 shared_preload_libraries
参数,例如手工编辑 postgresql.conf
文件,或者 ALTER SYSTEM
命令等方式进行更改,
或者通过 pg_parameters
参数进行显式覆盖,只需要确保集群范围内此配置统一一致即可。
加载注意事项
在 shared_preload_libraries
中,如果有多个扩展插件需要加载,可以使用逗号分隔,例如:
shared_preload_libraries = 'timescaledb, pg_stat_statements, auto_explain'
请注意,citus
和 timescaledb
这两个扩展显式提出要求,要在 shared_preload_libraries
中预先加载,也就是放在最前面。
由于生态定位的问题,同时使用两者的情况非常罕见,但在这种情况中,建议将 citus
放在 timescaledb
之前。
全文检索插件 pg_search
要求显式加载,但是在 PostgreSQL 17 版本中,可以不显式加载。
MongoDB 仿真插件 documentdb
实际的动态库名称与扩展名不一致 —— 你需要使用 pg_documentdb
和 pg_documentdb_core
作为动态链接库的名称。
需要加载的扩展
在 扩展列表 中,带有 LOAD
标记的扩展,即为需要动态加载并重启的扩展,包括:
扩展名 | 扩展包名 | 分类 | 说明 |
---|---|---|---|
timescaledb | timescaledb | TIME | 时序数据库扩展插件 |
pg_cron | pg_cron | TIME | 定时任务调度器 |
pg_task | pg_task | TIME | 在特定时间点在后台执行SQL命令 |
vchord | vchord | RAG | 使用Rust重写的高性能向量扩展 |
pgml | pgml | RAG | PostgresML:用SQL运行机器学习算法并训练模型 |
pg_bestmatch | pg_bestmatch | FTS | 在数据库内生成BM25稀疏向量 |
vchord_bm25 | vchord_bm25 | FTS | BM25排序算法 |
citus | citus | OLAP | Citus 分布式数据库 |
pg_duckdb | pg_duckdb | OLAP | 在PostgreSQL中的嵌入式DuckDB扩展 |
pg_parquet | pg_parquet | OLAP | 在PostgreSQL与本地/S3中的Parquet文件复制数据 |
plan_filter | pg_plan_filter | FEAT | 使用执行计划代价过滤阻止特定查询语句 |
omni | omnigres | FEAT | PostgreSQL即平台,Omnigres主扩展与加载器 |
pg_tle | pg_tle | LANG | AWS 可信语言扩展 |
plpgsql_check | plpgsql_check | LANG | 对 plpgsql 函数进行扩展检查 |
pgpdf | pgpdf | TYPE | PDF数据类型,管理函数与全文检索 |
pglite_fusion | pglite_fusion | TYPE | 在PG表中嵌入SQLite数据库作为数据类型 |
pg_net | pg_net | UTIL | 用 SQL 进行异步非阻塞HTTP/HTTPS 请求的扩展 (supabase) |
pg_squeeze | pg_squeeze | ADMIN | 从关系中删除未使用空间 |
pgautofailover | pgautofailover | ADMIN | PG 自动故障迁移 |
pg_crash | pg_crash | ADMIN | 向数据库进程随机发送信号模拟故障 |
pg_prewarm | pg_prewarm | ADMIN | 预热关系数据 |
pg_tracing | pg_tracing | STAT | PostgreSQL分布式Tracing |
pg_stat_kcache | pg_stat_kcache | STAT | 内核统计信息收集 |
pg_stat_monitor | pg_stat_monitor | STAT | 提供查询聚合统计、客户端信息、执行计划详细信息和直方图 |
pg_qualstats | pg_qualstats | STAT | 收集有关 quals 的统计信息的扩展 |
pg_store_plans | pg_store_plans | STAT | 跟踪所有执行的 SQL 语句的计划统计信息 |
pg_wait_sampling | pg_wait_sampling | STAT | 基于采样的等待事件统计 |
bgw_replstatus | bgw_replstatus | STAT | 用于汇报本机主从状态的后台工作进程 |
pg_relusage | pg_relusage | STAT | 打印查询引用的表与列 |
auto_explain | auto_explain | STAT | 提供一种自动记录执行计划的手段 |
pg_stat_statements | pg_stat_statements | STAT | 跟踪所有执行的 SQL 语句的计划和执行统计信息 |
passwordcheck_cracklib | passwordcheck | SEC | 使用cracklib加固PG用户密码 |
supautils | supautils | SEC | 用于在云环境中确保数据库集群的安全 |
pgsodium | pgsodium | SEC | 表数据加密存储 TDE |
anon | pg_anon | SEC | 数据匿名化处理工具 |
pg_tde | pg_tde | SEC | 试点性质的加密存储引擎 |
pgaudit | pgaudit | SEC | 提供审计功能 |
pg_snakeoil | pg_snakeoil | SEC | PostgreSQL动态链接库反病毒功能 |
pgextwlist | pgextwlist | SEC | PostgreSQL扩展白名单功能 |
noset | pg_noset | SEC | 阻止非超级用户使用SET/RESET设置变量 |
sepgsql | sepgsql | SEC | 基于SELinux标签的强制访问控制 |
auth_delay | auth_delay | SEC | 在返回认证失败前暂停一会,避免爆破 |
passwordcheck | passwordcheck | SEC | 用于强制拒绝修改弱密码的扩展 |
documentdb | documentdb | SIM | 微软DocumentDB的API层 |
documentdb_core | documentdb | SIM | 微软DocumentDB的核心API层实现 |
documentdb_distributed | documentdb | SIM | DocumentDB多节点模式的API层 |
pg_statement_rollback | pg_statement_rollback | SIM | 在服务端提供类似Oracle/DB2的语句级回滚能力 |
babelfishpg_tsql | babelfishpg_tsql | SIM | SQL Server SQL语法兼容性扩展 |
pglogical_ticker | pglogical_ticker | ETL | pglogical复制延迟以秒计的精确视图 |
pg_failover_slots | pg_failover_slots | ETL | 在Failover过程中保留复制槽 |