加载扩展

使用了 HOOK 的扩展插件需要显式加载，并重启数据库服务器生效。
Module:
Tags:

除了纯 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 用于提供一种自动记录慢查询执行计划的手段，用于微观优化特定慢查询 SQL
  • pg_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过程中保留复制槽