这是本节的多页打印视图。点击此处打印.

安装使用

如何在 Pigsty 中安装，启用，更新，卸载 PostgreSQL 扩展插件。

1: 快速上手
2: 下载扩展
3: 安装扩展
4: 加载扩展
5: 启用扩展
6: 更新扩展
7: 卸载扩展

1 - 快速上手

如何在 Pigsty 中，通过开箱即用的方式安装并启用 PostgreSQL 扩展插件？

Pigsty 让您可以直接在 PGSQL 集群中，通过声明式的方式下载，安装，加载，启用 PostgreSQL 扩展。

开箱即用

Pigsty 为用户封装了扩展管理的复杂度，用户无需了解细节，只要在配置文件中按需进行声明即可：

例如，下面的配置文件片段声明了一个 PostgreSQL 集群，下载并安装了三个额外的扩展插件，动态加载了三个扩展，并启用了三个扩展。

all:
  children:
    pg-meta:
      hosts: {10.10.10.10: { pg_seq: 1, pg_role: primary }}
      vars:           
        pg_cluster: pg-meta
        pg_databases: {name: meta, extensions: [ postgis, timescaledb, vector ]} # 动态启用三个扩展（这里使用扩展名，而非扩展包名）
        pg_libs: 'timescaledb, pg_stat_statements, auto_explain'                 # 动态加载三个扩展（后两个为 PG 自带扩展，无需专门下载安装）
        pg_extensions: [ pgsql-main, postgis pgvector timescaledb ]              # 额外安装三个扩展（默认大版本 PG 17，pgsql-main 为内核）
        repo_extra_packages: [ postgis, timescaledb, vector ]                    # 额外下载三个扩展（全局参数）

执行 ./install.yml 剧本，本地仓库中将下载这三个额外扩展，创建的 PostgreSQL 集群 pg-meta 中将自动安装，加载，启用上述扩展。

关键问题

想要在 PostgreSQL 集群中使用扩展（Extension），通常涉及到下载、安装、加载、启用四个核心问题：

怎样下载扩展：repo_extra_packages

在 Pigsty 默认在线安装时，只会下载当前 PG 大版本对应的三个默认扩展（pg_repack, wal2json, pgvector）。

如果您想要下载更多扩展，将其加入 repo_extra_packages 中即可。您可以加入扩展包名，或者直接指定扩展类目进行批量下载。
安装哪些扩展：pg_extensions

在 Pigsty 配置模板中的样例集群中，已经提供了完整可用的扩展清单，您只需要将想要安装的扩展，添加到 pg_extensions 中即可。

如果您想要在集群创建完毕后，安装额外的扩展，那么在配置完毕后，执行 ./pgsql.yml -t pg_extension 子任务即可。
加载哪些扩展：pg_libs

一小部分使用了 PostgreSQL 钩子函数的扩展，需要动态加载并重启数据库后才可以启用，您需要将这些扩展添加到 pg_libs 中，并在重启数据库后生效。

如果您的数据库集群已经创建完毕，那么需要配置现有集群的 shared_preload_libraries 参数，并重启数据库集群后生效。
启用哪些扩展：pg_databases.extensions

绝大多数扩展在安装之后，都需要执行 CREATE EXTENSION DDL 语句，才会真实在具体的数据库中被创建并启用。

您可以手工执行此 DDL，或者在 pg_datbasese.extensions 中显式指定要在数据库中启用的扩展列表，这些扩展会在集群初始化时自动启用。

扩展包名

您可能注意到，在加载，启用扩展时，使用的是“扩展名”（ext），而在下载，安装扩展时，使用的是“扩展包名”（pkg）。例如，向量数据库扩展 PGVECTOR 的扩展名是 vector，而扩展包名是 pgvector 。

flowchart LR
    ext[( EXTNAME )] -- "n:1" --> pkg[( PKGNAME )]
    pkg[( PKGNAME )] -- "1:n" --> packages[( RPM/DEB )]

这里的扩展包名是由 Pigsty 添加的额外抽象层，解决了不同操作系统发行版的扩展包名差异问题，在绝大部分情况下，扩展名（ext）与扩展包名（pkg）是相同的。但是一个扩展包可能包含多个扩展，例如 postgis 扩展包中就包含了 postgis 与其他六个扩展。多个扩展（ext）可能对应同一个扩展包（pkg），此外，有些扩展名与操作系统发行版自带的软件包名有冲突，因此您需要使用扩展包名（pkg）来下载，安装扩展。

在 Pigsty 中，您可以在 repo_extra_packages, pg_packages, pg_extensions 等下载安装相关参数中使用扩展包名（pkg），例如要安装 postgis 扩展，您可以使用：

Pigsty 提供的标准扩展包名，Pigsty 会自动根据活跃 PG 大版本与操作系统翻译为对应的 RPM/DEB 包名。
带有 $v 占位符的包名，Pigsty 会自动使用 pg_version 的值替换占位符。
原始的操作系统 RPM/DEB 包名，您可以在包名中使用 * 通配符，或依次指定每个包名。

postgis                   # 指定扩展包别名，自动翻译为 DEB/RPM 包名，与当前活跃 PG 大版本
postgis35_$v*             # 指定 RPM 包名模式，同时使用 PG 大版本号占位符 $v 
postgis35_15*             # 直接指定 RPM 包名名称
postgresql-$v-postgis-3*  # 指定 DEB 包名模式，同时使用 PG 大版本号占位符 $v 
postgresql-14-postgis-3*  # 直接指定 DEB 包名称

Pigsty 中所有可用扩展的扩展包名与扩展名之间的映射关系，可以查询扩展列表页面。此外，一个扩展包在不同的操作系统和 PostgreSQL 大版本组合下，也会对应不同的具体 RPM/DEB 包名。

我们建议使用 Pigsty 提供的标准化扩展名（pkg）来下载安装扩展，在不同的操作系统发行版中， Pigsty 将标准扩展名翻译为对应 PG 大版本的 RPM / DEB 包名，并填充 PG 大版本号，这样您就无需关心不同 OS/PG 组合的扩展包名差异了。

尽管如此，不同操作系统与芯片架构上可用的扩展仍然会有略微差异，具体操作系统发行版可用的扩展列表，下面的配置文件为权威参考：

Pigsty 尽最大努力对齐 EL 操作系统与 Debian 操作系统生态的 PostgreSQL 扩展，但仍有少量扩展因为各种原因难以/尚未移植，请参考 RPM扩展列表与 DEB扩展列表了解更多信息。

复杂案例

下面是一个具体的例子：自建 Supabase 使用到的 app/supa 配置模板：

Supabase 是一个封装 PostgreSQL 作为底层存储的“上层抽象数据库”，它深度使用了 PostgreSQL 的扩展机制，以下片段定义了 Supabase 需要的扩展：

all:
  children:
    # pg-meta, the underlying postgres database for supabase
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:
          # supabase roles: anon, authenticated, dashboard_user
          - { name: anon           ,login: false }
          - { name: authenticated  ,login: false }
          - { name: dashboard_user ,login: false ,replication: true ,createdb: true ,createrole: true }
          - { name: service_role   ,login: false ,bypassrls: true }
          # supabase users: please use the same password
          - { name: supabase_admin             ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: true   ,roles: [ dbrole_admin ] ,superuser: true ,replication: true ,createdb: true ,createrole: true ,bypassrls: true }
          - { name: authenticator              ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false  ,roles: [ dbrole_admin, authenticated ,anon ,service_role ] }
          - { name: supabase_auth_admin        ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false  ,roles: [ dbrole_admin ] ,createrole: true }
          - { name: supabase_storage_admin     ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false  ,roles: [ dbrole_admin, authenticated ,anon ,service_role ] ,createrole: true }
          - { name: supabase_functions_admin   ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: false  ,roles: [ dbrole_admin ] ,createrole: true }
          - { name: supabase_replication_admin ,password: 'DBUser.Supa' ,replication: true ,roles: [ dbrole_admin ]}
          - { name: supabase_read_only_user    ,password: 'DBUser.Supa' ,bypassrls: true ,roles: [ dbrole_readonly, pg_read_all_data ] }
        pg_databases:
          - name: postgres
            baseline: supabase.sql
            owner: supabase_admin
            comment: supabase postgres database
            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 的轻量级消息队列
        # supabase required extensions
        pg_libs: 'timescaledb, plpgsql, plpgsql_check, pg_cron, pg_net, pg_stat_statements, auto_explain, pg_tle, plan_filter'
        pg_parameters:
          cron.database_name: postgres
          pgsodium.enable_event_trigger: off
        pg_hba_rules: # supabase hba rules, require access from docker network
          - { user: all ,db: postgres  ,addr: intra         ,auth: pwd ,title: 'allow supabase access from intranet'    }
          - { user: all ,db: postgres  ,addr: 172.17.0.0/16 ,auth: pwd ,title: 'allow access from local docker network' }
        node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every 1am

  vars:  # 全局参数配置
    pg_version: 17
    repo_modules: node,pgsql,infra,docker
    repo_packages: [node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility, docker ]
    repo_extra_packages: [pg17-core ,pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-olap ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl ]
    pg_extensions:                  [pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl ] #,pg17-olap]

在这里，我们声明了一个名为 pg-meta 的 PostgreSQL 集群，它使用默认的 postgres 数据库作为定制对象。

在 repo_extra_packages 按照 16 大分类分类批量下载所有可用扩展，而不是一个一个指定下载
在 pg_extensions 中指定需要安装的扩展包，这里按照了除了 pg17-olap 以外的所有扩展包
在 pg_libs 中对 Supabase 需要用到的扩展进行动态加载
在 pg_parameters 中指定扩展所需的配置参数，例如 pgsodium 与 pg_cron 扩展所必须的配置参数
在 pg_databases.extensions 中指定将扩展安装到哪个模式（schema）中

在 baseline: supabase.sql 中，还包含了其他对扩展进行自定义配置的 SQL Migration 逻辑。

最终，用户只需要执行 ./install.yml ，Supabase 所需的 PostgreSQL 集群就能被创建出来并开箱即用了！

2 - 下载扩展

如何下载新的扩展插件，并将其添加至 Pigsty 中？

在 Pigsty 的默认剧本中，扩展插件的下载与安装是分离的两个步骤。 Pigsty 会首先在 INFRA 模块安装的过程中，统一下载所有需要的软件至本地，并创建一个本地 YUM/APT 仓库供整套部署（包括本节点）使用。这样做可以加速安装，避免重复下载，避免数据库节点访问互联网，减少网络流量消耗，提高交付可靠性性，并解决重复安装版本不一致的风险。是严肃生产环境中推荐的做法。

不过，如果您的数据库节点可以直接访问互联网，那么确实还有另一种可行的方式：直接从互联网在线安装下载扩展插件。

快速上手

在 repo_packages 参数与 repo_extra_packages 参数中定义的软件包会在 Pigsty 安装过程中自动下载到本地软件仓库。

通常在指定下载与 PostgreSQL 大版本相关的软件包（例如内核与扩展）时，需要修改 repo_extra_packages 参数，而 repo_packages 留空以使用不同系统的默认值。

此参数的默认值为 [pgsql-main]，其中 pgsql-main 是一个由 Pigsty 定义的便捷别名，代表当前活跃 PG 大版本的内核与关键扩展包。

repo_extra_packages: [ pgsql-main ]  # 下载当前活跃 PG 大版本（17）的内核与关键扩展包（pgvector, pg_repack, wal2json）

如果您你想要添加特定的扩展插件，将 Pigsty 标准扩展包名 添加到此参数中即可。您无需指定 PG 大版本号，Pigsty 会自动下载当前活跃 PG 大版本相关的扩展包。

repo_extra_packages: [ pgsql-main, documentdb, citus, postgis, pgvector, pg_cron, rum ]

如果你想要下载当前 PG 版本 “所有可用”的扩展插件，可以类似 rich 配置模板所做的那样，将 16 个扩展分类的别名全部添加到此参数中即可：

repo_extra_packages: [ pgsql-main ,pgsql-time ,pgsql-gis ,pgsql-rag ,pgsql-fts ,pgsql-olap ,pgsql-feat ,pgsql-lang ,pgsql-type ,pgsql-util ,pgsql-func ,pgsql-admin ,pgsql-stat ,pgsql-sec ,pgsql-fdw ,pgsql-sim ,pgsql-etl]

如果你想要下载“所有可用”的扩展插件，还可以使用具体的 PG大版本相关别名 来指定：

repo_extra_packages: [
    pg17-core,pg17-time,pg17-gis,pg17-rag,pg17-fts,pg17-olap,pg17-feat,pg17-lang,pg17-type,pg17-util,pg17-func,pg17-admin,pg17-stat,pg17-sec,pg17-fdw,pg17-sim,pg17-etl,
    pg16-core,pg16-time,pg16-gis,pg16-rag,pg16-fts,pg16-olap,pg16-feat,pg16-lang,pg16-type,pg16-util,pg16-func,pg16-admin,pg16-stat,pg16-sec,pg16-fdw,pg16-sim,pg16-etl,
    pg15-core,pg15-time,pg15-gis,pg15-rag,pg15-fts,pg15-olap,pg15-feat,pg15-lang,pg15-type,pg15-util,pg15-func,pg15-admin,pg15-stat,pg15-sec,pg15-fdw,pg15-sim,pg15-etl,
    pg14-core,pg14-time,pg14-gis,pg14-rag,pg14-fts,pg14-olap,pg14-feat,pg14-lang,pg14-type,pg14-util,pg14-func,pg14-admin,pg14-stat,pg14-sec,pg14-fdw,pg14-sim,pg14-etl,
    pg13-core,pg13-time,pg13-gis,pg13-rag,pg13-fts,pg13-olap,pg13-feat,pg13-lang,pg13-type,pg13-util,pg13-func,pg13-admin,pg13-stat,pg13-sec,pg13-fdw,pg13-sim,pg13-etl,
]

如果你想要向本地仓库中添加新的扩展包，在修改上述参数后，重新运行 INFRA 模块的 repo_build 子任务即可：

./infra.yml -t repo_build   # 重新下载并重建本地仓库
./node.yml  -t node_repo    # 【可选】更新仓库元数据

别名翻译

PostgreSQL 有着繁荣的开源生态，安装 PostgreSQL 绝非安装几个内核 RPM/DEB 这么简单。

Pigsty 提供了一种优雅的抽象翻译层，将所需的 PostgreSQL 软件包分门别类，归结为一系列 “别名”（Alias），屏蔽了不同系统、架构、PG大版本之间的差异。

在 快速上手 中，我们已经使用了例如 pgsql-main 与 pgsql-core 等别名，这些别名会根据系统与架构自动翻译为具体的软件包名。以 EL 系统为例，pgsql-main 被翻译为 postgresql$v* 内核包，以及 pgvector_$v*，pg_repack_$v* 与 wal2json_$v* 三个扩展插件。

pgsql-main:   "postgresql$v* pg_repack_$v* wal2json_$v* pgvector_$v*"

同时，带有 $v 版本号占位符的包名会进一步被默认的 pg_version=17 替换为 PostgreSQL 17 对应的内核包与三个扩展包。带有 * 通配符的具体内核包又会进一步展开为postgresql17, postgresql17-server, postgresql17-libs, postgresql17-contrib, postgresql17-plperl, postgresql17-plpython3, postgresql17-pltcl, postgresql17-test, postgresql17-devel, postgresql17-llvmjit，而扩展中的 * 会展开为扩展本体 RPM + LLVMJIT，以及其他 RPM。 Pigsty 为用户封装处理好了这些细节。

完整的可用软件包与别名可以参考 roles/node_id/vars/<os.arch>.yml 里面包含了不同系统与架构的可用软件包/别名列表，以下是一些最常用的各个系统都提供的别名列表：

postgresql:   "postgresql$v*"
pgsql-main:   "postgresql$v* pg_repack_$v* wal2json_$v* pgvector_$v*"
pgsql-core:   "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-test postgresql$v-devel postgresql$v-llvmjit"
pgsql-simple: "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl"
pgsql-client: "postgresql$v"
pgsql-server: "postgresql$v-server postgresql$v-libs postgresql$v-contrib"
pgsql-devel:  "postgresql$v-devel"
pgsql-basic:  "pg_repack_$v* wal2json_$v* pgvector_$v*"

pgsql-time:   "timescaledb-tsl_$v* timescaledb-toolkit_$v pg_timeseries_$v periods_$v* temporal_tables_$v* e-maj_$v table_version_$v pg_cron_$v* pg_task_$v* pg_later_$v pg_background_$v*"
pgsql-gis:    "postgis35_$v* pgrouting_$v* pointcloud_$v* h3-pg_$v* q3c_$v* ogr_fdw_$v* geoip_$v pg_polyline_$v pg_geohash_$v*"
pgsql-rag:    "pgvector_$v* vchord_$v pgvectorscale_$v pg_vectorize_$v pg_similarity_$v* smlar_$v* pg_summarize_$v pg_tiktoken_$v pg4ml_$v"
pgsql-fts:    "pg_search_$v pgroonga_$v* pg_bigm_$v* zhparser_$v* pg_bestmatch_$v vchord_bm25_$v hunspell_cs_cz_$v hunspell_de_de_$v hunspell_en_us_$v hunspell_fr_$v hunspell_ne_np_$v hunspell_nl_nl_$v hunspell_nn_no_$v hunspell_ru_ru_$v hunspell_ru_ru_aot_$v"
pgsql-olap:   "citus_$v* pg_analytics_$v pg_duckdb_$v* pg_mooncake_$v* duckdb_fdw_$v* pg_parquet_$v pg_fkpart_$v pg_partman_$v* plproxy_$v*" #hydra_$v* #pg_strom_$v*
pgsql-feat:   "hll_$v* rum_$v pg_graphql_$v pg_jsonschema_$v jsquery_$v* pg_hint_plan_$v* hypopg_$v* index_advisor_$v pg_plan_filter_$v* imgsmlr_$v* pg_ivm_$v* pg_incremental_$v* pgmq_$v pgq_$v* pg_cardano_$v omnigres_$v" #apache-age_$v*
pgsql-lang:   "pg_tle_$v* plv8_$v* pllua_$v* pldebugger_$v* plpgsql_check_$v* plprofiler_$v* plsh_$v* pljava_$v*" #plprql_$v #plr_$v* #pgtap_$v* #postgresql_faker_$v* #dbt2-pgsql-extensions*
pgsql-type:   "prefix_$v* semver_$v* postgresql-unit_$v* pgpdf_$v* pglite_fusion_$v md5hash_$v* asn1oid_$v* pg_roaringbitmap_$v* pgfaceting_$v pgsphere_$v* pg_country_$v* pg_xenophile_$v pg_currency_$v* pgcollection_$v* pgmp_$v* numeral_$v* pg_rational_$v* pguint_$v* pg_uint128_$v* hashtypes_$v* ip4r_$v* pg_duration_$v* pg_uri_$v* pg_emailaddr_$v* acl_$v* timestamp9_$v* chkpass_$v*"
pgsql-util:   "pgsql_gzip_$v* pg_bzip_$v* pg_zstd_$v* pgsql_http_$v* pg_net_$v* pg_curl_$v* pgjq_$v* pgjwt_$v pg_smtp_client_$v pg_html5_email_address_$v url_encode_$v* pgsql_tweaks_$v pg_extra_time_$v pgpcre_$v icu_ext_$v* pgqr_$v* pg_protobuf_$v pg_envvar_$v* floatfile_$v* pg_readme_$v ddl_historization_$v data_historization_$v pg_schedoc_$v pg_hashlib_$v pg_xxhash_$v* postgres_shacrypt_$v* cryptint_$v* pg_ecdsa_$v* pgsparql_$v"
pgsql-func:   "pg_idkit_$v pg_uuidv7_$v* permuteseq_$v* pg_hashids_$v* sequential_uuids_$v topn_$v* quantile_$v* lower_quantile_$v* count_distinct_$v* omnisketch_$v* ddsketch_$v* vasco_$v* pgxicor_$v* tdigest_$v* first_last_agg_$v extra_window_functions_$v* floatvec_$v* aggs_for_vecs_$v* aggs_for_arrays_$v* pg_arraymath_$v* pg_math_$v* pg_random_$v* pg_base36_$v* pg_base62_$v* pg_base58_$v pg_financial_$v*"
pgsql-admin:  "pg_repack_$v* pg_squeeze_$v* pg_dirtyread_$v* pgfincore_$v* pg_cooldown_$v* ddlx_$v pg_prioritize_$v* pg_readonly_$v* pg_upless_$v pg_permissions_$v pg_catcheck_$v* preprepare_$v* pgcozy_$v pg_orphaned_$v* pg_crash_$v* pg_cheat_funcs_$v* pg_fio_$v pg_savior_$v* safeupdate_$v* pg_drop_events_$v table_log_$v" #pg_checksums_$v* #pg_auto_failover_$v* #pgagent_$v* #pgpool-II-pgsql-extensions
pgsql-stat:   "pg_profile_$v* pg_tracing_$v* pg_show_plans_$v* pg_stat_kcache_$v* pg_stat_monitor_$v* pg_qualstats_$v* pg_store_plans_$v* pg_track_settings_$v pg_wait_sampling_$v* system_stats_$v* pg_meta_$v pgnodemx_$v pg_sqlog_$v bgw_replstatus_$v* pgmeminfo_$v* toastinfo_$v* pg_explain_ui_$v pg_relusage_$v pagevis_$v powa_$v*"
pgsql-sec:    "passwordcheck_cracklib_$v* supautils_$v* pgsodium_$v* vault_$v* pg_session_jwt_$v pg_anon_$v pgsmcrypto_$v pgaudit_$v* pgauditlogtofile_$v* pg_auth_mon_$v* credcheck_$v* pgcryptokey_$v pg_jobmon_$v logerrors_$v* login_hook_$v* set_user_$v* pg_snakeoil_$v* pgextwlist_$v* pg_auditor_$v sslutils_$v* noset_$v*" #pg_tde_$v*
pgsql-fdw:    "wrappers_$v multicorn2_$v* odbc_fdw_$v* mysql_fdw_$v* tds_fdw_$v* sqlite_fdw_$v* pgbouncer_fdw_$v redis_fdw_$v* pg_redis_pubsub_$v* hdfs_fdw_$v* firebird_fdw_$v aws_s3_$v log_fdw_$v*" #jdbc_fdw_$v* #oracle_fdw_$v* #db2_fdw_$v* #mongo_fdw_$v* #kafka_fdw_$v
pgsql-sim:    "documentdb_$v* orafce_$v pgtt_$v* session_variable_$v* pg_statement_rollback_$v* pg_dbms_metadata_$v pg_dbms_lock_$v pgmemcache_$v*" #pg_dbms_job_$v #wiltondb
pgsql-etl:    "pglogical_$v* pglogical_ticker_$v* pgl_ddl_deploy_$v* pg_failover_slots_$v* db_migrator_$v wal2json_$v* postgres-decoderbufs_$v* decoder_raw_$v* mimeo_$v pg_fact_loader_$v* pg_bulkload_$v*" #wal2mongo_$v* #repmgr_$v*

postgresql:   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v"
pgsql-main:   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector"
pgsql-core:   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v"
pgsql-simple: "postgresql-$v postgresql-client-$v postgresql-plperl-$v postgresql-plpython3-$v postgresql-pltcl-$v"
pgsql-client: "postgresql-client-$v"
pgsql-server: "postgresql-$v"
pgsql-devel:  "postgresql-server-dev-$v"
pgsql-basic:  "postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector"
pgsql-time:    "postgresql-$v-timescaledb-tsl postgresql-$v-timescaledb-toolkit postgresql-$v-pg-timeseries postgresql-$v-periods postgresql-$v-temporal-tables postgresql-$v-emaj postgresql-$v-table-version postgresql-$v-cron postgresql-$v-pg-task postgresql-$v-pg-later postgresql-$v-pg-background"

pgsql-gis:     "postgresql-$v-postgis-3 postgresql-$v-postgis-3-scripts postgresql-$v-pgrouting postgresql-$v-pgrouting-scripts postgresql-$v-pointcloud postgresql-$v-h3 postgresql-$v-q3c postgresql-$v-ogr-fdw postgresql-$v-geoip postgresql-$v-pg-polyline postgresql-$v-pg-geohash postgresql-$v-mobilitydb"
pgsql-rag:     "postgresql-$v-pgvector postgresql-$v-vchord postgresql-$v-pgvectorscale postgresql-$v-pg-vectorize postgresql-$v-similarity postgresql-$v-smlar postgresql-$v-pg-summarize postgresql-$v-pg-tiktoken postgresql-$v-pg4ml postgresql-$v-pgml"
pgsql-fts:     "postgresql-$v-pg-search postgresql-$v-pgroonga postgresql-$v-pg-bigm postgresql-$v-zhparser postgresql-$v-pg-bestmatch postgresql-$v-vchord-bm25 postgresql-$v-hunspell-cs-cz postgresql-$v-hunspell-de-de postgresql-$v-hunspell-en-us postgresql-$v-hunspell-fr postgresql-$v-hunspell-ne-np postgresql-$v-hunspell-nl-nl postgresql-$v-hunspell-nn-no postgresql-$v-hunspell-ru-ru postgresql-$v-hunspell-ru-ru-aot"
pgsql-olap:    "postgresql-$v-citus postgresql-$v-pg-analytics postgresql-$v-pg-duckdb postgresql-$v-pg-mooncake postgresql-$v-duckdb-fdw postgresql-$v-pg-parquet postgresql-$v-pg-fkpart postgresql-$v-partman postgresql-$v-plproxy" #postgresql-$v-hydra
pgsql-feat:    "postgresql-$v-age postgresql-$v-hll postgresql-$v-rum postgresql-$v-pg-graphql postgresql-$v-pg-jsonschema postgresql-$v-jsquery postgresql-$v-pg-hint-plan postgresql-$v-hypopg postgresql-$v-index-advisor postgresql-$v-pg-plan-filter postgresql-$v-imgsmlr postgresql-$v-pg-ivm postgresql-$v-pg-incremental postgresql-$v-pgmq postgresql-$v-pgq3 postgresql-$v-pg-cardano postgresql-$v-omnigres" #postgresql-$v-rdkit
pgsql-lang:    "postgresql-$v-pg-tle postgresql-$v-plv8 postgresql-$v-pllua postgresql-$v-pldebugger postgresql-$v-plpgsql-check postgresql-$v-plprofiler postgresql-$v-plsh postgresql-$v-pljava" #postgresql-$v-plprql #postgresql-$v-plr #postgresql-$v-pgtap
pgsql-type:    "postgresql-$v-prefix postgresql-$v-semver postgresql-$v-unit postgresql-$v-pgpdf postgresql-$v-pglite-fusion postgresql-$v-md5hash postgresql-$v-asn1oid postgresql-$v-roaringbitmap postgresql-$v-pgfaceting postgresql-$v-pgsphere postgresql-$v-pg-country postgresql-$v-pg-xenophile postgresql-$v-pg-currency postgresql-$v-collection postgresql-$v-pgmp postgresql-$v-numeral postgresql-$v-rational postgresql-$v-pguint postgresql-$v-pg-uint128 postgresql-$v-hashtypes postgresql-$v-ip4r postgresql-$v-pg-duration postgresql-$v-pg-uri postgresql-$v-pg-emailaddr postgresql-$v-acl postgresql-$v-debversion postgresql-$v-pg-rrule postgresql-$v-timestamp9 postgresql-$v-chkpass"
pgsql-util:    "postgresql-$v-gzip postgresql-$v-bzip postgresql-$v-zstd postgresql-$v-http postgresql-$v-pg-net postgresql-$v-pg-curl postgresql-$v-pgjq postgresql-$v-pgjwt postgresql-$v-pg-smtp-client postgresql-$v-pg-html5-email-address postgresql-$v-url-encode postgresql-$v-pgsql-tweaks postgresql-$v-pg-extra-time postgresql-$v-pgpcre postgresql-$v-icu-ext postgresql-$v-pgqr postgresql-$v-pg-protobuf postgresql-$v-pg-envvar postgresql-$v-floatfile postgresql-$v-pg-readme postgresql-$v-ddl-historization postgresql-$v-data-historization postgresql-$v-pg-schedoc postgresql-$v-pg-hashlib postgresql-$v-pg-xxhash postgresql-$v-shacrypt postgresql-$v-cryptint postgresql-$v-pg-ecdsa postgresql-$v-pgsparql"
pgsql-func:    "postgresql-$v-pg-idkit postgresql-$v-pg-uuidv7 postgresql-$v-permuteseq postgresql-$v-pg-hashids postgresql-$v-sequential-uuids postgresql-$v-topn postgresql-$v-quantile postgresql-$v-lower-quantile postgresql-$v-count-distinct postgresql-$v-omnisketch postgresql-$v-ddsketch postgresql-$v-vasco postgresql-$v-pgxicor postgresql-$v-tdigest postgresql-$v-first-last-agg postgresql-$v-extra-window-functions postgresql-$v-floatvec postgresql-$v-aggs-for-vecs postgresql-$v-aggs-for-arrays postgresql-$v-pg-arraymath postgresql-$v-pg-math postgresql-$v-random postgresql-$v-base36 postgresql-$v-base62 postgresql-$v-pg-base58 postgresql-$v-pg-financial"
pgsql-admin:   "postgresql-$v-repack postgresql-$v-squeeze postgresql-$v-dirtyread postgresql-$v-pgfincore postgresql-$v-pg-cooldown postgresql-$v-ddlx postgresql-$v-prioritize postgresql-$v-pg-checksums postgresql-$v-pg-readonly postgresql-$v-pg-upless postgresql-$v-pg-permissions postgresql-$v-auto-failover postgresql-$v-pg-catcheck postgresql-$v-preprepare postgresql-$v-pgcozy postgresql-$v-pg-orphaned postgresql-$v-pg-crash postgresql-$v-pg-cheat-funcs postgresql-$v-pg-fio postgresql-$v-pg-savior postgresql-$v-pg-safeupdate postgresql-$v-pg-drop-events postgresql-$v-tablelog" #pgagent #postgresql-$v-pgpool2
pgsql-stat:    "postgresql-$v-pg-profile postgresql-$v-pg-tracing postgresql-$v-show-plans postgresql-$v-pg-stat-kcache postgresql-$v-pg-stat-monitor postgresql-$v-pg-qualstats postgresql-$v-pg-store-plan postgresql-$v-pg-track-settings postgresql-$v-pg-wait-sampling postgresql-$v-system-stats postgresql-$v-pg-meta postgresql-$v-pgnodemx postgresql-$v-pg-sqlog postgresql-$v-bgw-replstatus postgresql-$v-pgmeminfo postgresql-$v-toastinfo postgresql-$v-pg-explain-ui postgresql-$v-pg-relusage postgresql-$v-pagevis postgresql-$v-powa"
pgsql-sec:     "postgresql-$v-passwordcheck-cracklib postgresql-$v-supautils postgresql-$v-pgsodium postgresql-$v-vault postgresql-$v-pg-session-jwt postgresql-$v-pg-anon postgresql-$v-pgsmcrypto postgresql-$v-pgaudit postgresql-$v-pgauditlogtofile postgresql-$v-pg-auth-mon postgresql-$v-credcheck postgresql-$v-pgcryptokey postgresql-$v-pg-jobmon postgresql-$v-logerrors postgresql-$v-login-hook postgresql-$v-set-user postgresql-$v-snakeoil postgresql-$v-pgextwlist postgresql-$v-pg-auditor postgresql-$v-sslutils postgresql-$v-noset" #postgresql-$v-pg-tde
pgsql-fdw:     "postgresql-$v-wrappers postgresql-$v-mysql-fdw postgresql-$v-tds-fdw postgresql-$v-redis-fdw postgresql-$v-pg-redis-pubsub postgresql-$v-firebird-fdw postgresql-$v-aws-s3 postgresql-$v-log-fdw" # #postgresql-$v-oracle-fdw #postgresql-$v-sqlite-fdw #postgresql-$v-kafka-fdw
pgsql-sim:     "postgresql-$v-documentdb postgresql-$v-orafce postgresql-$v-pgtt postgresql-$v-session-variable postgresql-$v-pg-statement-rollback postgresql-$v-pgmemcache" # #wiltondb
pgsql-etl:     "postgresql-$v-pglogical postgresql-$v-pglogical-ticker postgresql-$v-pgl-ddl-deploy postgresql-$v-pg-failover-slots postgresql-$v-db-migrator postgresql-$v-wal2json postgresql-$v-decoderbufs postgresql-$v-decoder-raw postgresql-$v-mimeo postgresql-$v-pg-fact-loader postgresql-$v-pg-bulkload" #postgresql-$v-wal2mongo #postgresql-$v-repmgr

在使用这些别名下载 PostgreSQL 软件包时，请注意，这些软件包别名与包名中的 $v 占位符变量，会在使用时被替换为实际的 PostgreSQL 大版本号（由 pg_version 参数指定，默认为 17）。

如果您想要安装其他 PostgreSQL 大版本，只需要修改 pg_version 即可。当然您也可以直接使用指定大版本的别名与包名，例如这些带有 pgsql- 前缀的的别名可以直接替换为 pg17-， pg16-，pg15- 以显式下载其他大版本的软件包。

请注意，并非所有系统都支持所有扩展插件，一些不可用，的扩展插件默认会从扩展分类列表中移除，以注释项的形式出现在别名末尾。但并非所有在注释中的扩展都不可用，一些扩展只是较为不合时宜而未被默认列入（依赖过于庞大，比如 pl/R，或者依赖商业软件，比如 oracle_fdw），而另一些可能只是在当前 PG 17 大版本中不可用，而在更早的 13-16 中可用，您依然可以手工添加这些所需的扩展并下载安装。

3 - 安装扩展

如何从 Pigsty 本地软件源，或直接从上游互联网软件源安装 PostgreSQL 扩展插件？

Pigsty 使用操作系统标准的包管理器（yum/apt）来安装 PostgreSQL 扩展插件。

快速上手

在安装扩展时，Pigsty 使用与下载时相同的 别名映射 机制，你可以直接在这里指定扩展的名称，或者二进制包名。

all:
  children:
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_extensions: # extensions to be installed on this cluster
          - timescaledb timescaledb_toolkit pg_timeseries periods temporal_tables emaj table_version pg_cron pg_task pg_later pg_background
          - postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip pg_polyline pg_geohash #mobilitydb
          - pgvector vchord pgvectorscale pg_vectorize pg_similarity smlar pg_summarize pg_tiktoken pg4ml #pgml
          - pg_search pgroonga pg_bigm zhparser pg_bestmatch vchord_bm25 hunspell
          - citus hydra pg_analytics pg_duckdb pg_mooncake duckdb_fdw pg_parquet pg_fkpart pg_partman plproxy #pg_strom
          - age hll rum pg_graphql pg_jsonschema jsquery pg_hint_plan hypopg index_advisor pg_plan_filter imgsmlr pg_ivm pg_incremental pgmq pgq pg_cardano omnigres #rdkit
          - pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh pljava #plr #pgtap #faker #dbt2
          - pg_prefix pg_semver pgunit pgpdf pglite_fusion md5hash asn1oid roaringbitmap pgfaceting pgsphere pg_country pg_xenophile pg_currency pg_collection pgmp numeral pg_rational pguint pg_uint128 hashtypes ip4r pg_uri pgemailaddr pg_acl timestamp9 chkpass #pg_duration #debversion #pg_rrule
          - pg_gzip pg_bzip pg_zstd pg_http pg_net pg_curl pgjq pgjwt pg_smtp_client pg_html5_email_address url_encode pgsql_tweaks pg_extra_time pgpcre icu_ext pgqr pg_protobuf envvar floatfile pg_readme ddl_historization data_historization pg_schedoc pg_hashlib pg_xxhash shacrypt cryptint pg_ecdsa pgsparql
          - pg_idkit pg_uuidv7 permuteseq pg_hashids sequential_uuids topn quantile lower_quantile count_distinct omnisketch ddsketch vasco pgxicor tdigest first_last_agg extra_window_functions floatvec aggs_for_vecs aggs_for_arrays pg_arraymath pg_math pg_random pg_base36 pg_base62 pg_base58 pg_financial
          - pg_repack pg_squeeze pg_dirtyread pgfincore pg_cooldown pg_ddlx pg_prioritize pg_checksums pg_readonly pg_upless pg_permissions pgautofailover pg_catcheck preprepare pgcozy pg_orphaned pg_crash pg_cheat_funcs pg_fio pg_savior safeupdate pg_drop_events table_log #pgagent #pgpool
          - pg_profile pg_tracing pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats pg_meta pgnodemx pg_sqlog bgw_replstatus pgmeminfo toastinfo pg_explain_ui pg_relusage pagevis powa
          - passwordcheck supautils pgsodium pg_vault pg_session_jwt pg_anon pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user pg_snakeoil pgextwlist pg_auditor sslutils pg_noset
          - wrappers multicorn odbc_fdw jdbc_fdw mysql_fdw tds_fdw sqlite_fdw pgbouncer_fdw mongo_fdw redis_fdw pg_redis_pubsub kafka_fdw hdfs_fdw firebird_fdw aws_s3 log_fdw #oracle_fdw #db2_fdw
          - documentdb orafce pgtt session_variable pg_statement_rollback pg_dbms_metadata pg_dbms_lock pgmemcache #pg_dbms_job #wiltondb
          - pglogical pglogical_ticker pgl_ddl_deploy pg_failover_slots db_migrator wal2json wal2mongo decoderbufs decoder_raw mimeo pg_fact_loader pg_bulkload #repmgr

或者使用扩展分类别名，批量安装所有扩展。

all:
  vars:
    pg_version: 17   # default postgres version 17, so the pgsql-main is equivalent to pg17-main
    pg_extensions: [ pgsql-main ,pgsql-time ,pgsql-gis ,pgsql-rag ,pgsql-fts ,pgsql-feat ,pgsql-lang ,pgsql-type ,pgsql-util ,pgsql-func ,pgsql-admin ,pgsql-stat ,pgsql-sec ,pgsql-fdw ,pgsql-sim ,pgsql-etl] #,pgsql-olap]

你也可以显式指定 PG 大版本号，然后使用扩展分类别名，批量安装所有扩展。

all:
  vars:
    
    pg_extensions: [pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl ] #,pg17-olap]

同时安装所有扩展尽管是可行的（除了 olap 分类中的两对冲突特例），但并不推荐这么做，请尽可能只安装您需要的扩展。

配置扩展

在 PGSQL 集群初始化时，Pigsty 会自动安装 pg_packages 和 pg_extensions 中指定的扩展插件。

两个参数都可以用于安装 PostgreSQL 相关软件包，通常 pg_packages 用于在全局指定整个环境中所有 PostgreSQL 集群都需要统一安装的软件包：例如 PostgreSQL 内核，高可用组建 Patroni，连接池 pgBouncer，监控 pgExporter 等。 Pigsty 默认也会在这里指定安装三个重要扩展：pgvector, pg_repack 和 wal2json 用于膨胀治理和 CDC 变更抽取。

而 pg_extensions 则通常用于在特定集群中，指定本集群需要安装的扩展插件。默认为空列表，表示不安装任何额外的扩展插件。

pg_packages:                      # pg packages to be installed, alias can be used
  - postgresql`
  - wal2json pg_repack pgvector
  - patroni pgbouncer pgbackrest pg_exporter pgbadger vip-manager
pg_extensions: []                 # pg extensions to be installed, alias can be used

另一个重要区别是：pg_packages 安装的软件包只确保存在即可，而 pg_extensions 安装的软件包会默认 升级到最新可用版本。

当使用本地软件源时，这并不是一个问题。当您直接使用互联网上游软件源时，请充分考虑这一点，并将不希望升级的扩展插件转移到 pg_packages 中。

安装扩展

定义于 pg_extensions 中的扩展插件会在新集群初始化的时候自动安装。

对于一个已经完成部署的现有 PostgreSQL 集群，如果你想安装新的扩展插件：

首先将所需的扩展添加至 pg_extensions 中，然后通过以下命令执行子任务完成安装：

./pgsql.yml -t pg_extension  # 安装 pg_extensions 中指定的扩展插件

请注意，pg_extension 任务中指定的扩展插件会默认升级到当前环境中最新可用版本。

扩展仓库

想要安装扩展插件，您需要确保目标节点上已经配置了合适的软件仓库。

本地安装：您已经配置了 Pigsty 的本地软件源，并且扩展已经下载至至本地软件仓库。
在线安装：您已经在待安装的节点上直接配置上游互联网软件源，并且可以访问互联网。

通常来说，对于严肃的生产环境，您应该使用 Pigsty 的本地软件源来统一管理并安装扩展：首先下载到本地软件仓库中，再从本地软件仓库中安装扩展。这样可以确保扩展的版本全局一致，并避免让数据库节点直接访问互联网。但某些时候（例如在开发环境中为了方便）您也可以直接使用互联网上游软件源来安装扩展。

要使用本地安装，您首先需要确保目标扩展已经被下载到本地软件仓库中。如果要使用在线安装，请确保待安装的节点可以访问互联网，并且上游软件源可以正常访问。然后使用以下命令来直接在目标集群上添加仓库并安装扩展：

./node.yml  -l <cls> -t node_repo -e node_repo_modules=local,node,pgsql    # 在目标节点上启用互联网软件仓库
./pgsql.yml -l <cls> -t pg_extension                                                        # 使用本地+互联网上游仓库安装扩展

扩展别名

在安装扩展时，用户可以使用 扩展包名 来指定扩展插件。别名会根据 别名翻译机制 被翻译为当前活跃 PG 大版本与操作系统环境，翻译为对应的 RPM/DEB 包名。

注意事项

查看已知问题了解已知问题
存在两个已知的扩展冲突：
- citus 和 hydra 互斥，因为 hydra 是 citus 列存分支且未重命名
- 在 pg_duckdb, pg_mooncake, duckdb_fdw 中只能安装一个，因为它们都使用自己的 libduckdb
pgaudit 在 EL 系统上对于 PG 15 及以下版本有特殊的命名规则：pg16+ = pgaudit, pg15=pgaudit17, pg14=pgaudit16, pg13=pgaudit15, pg12=pgaudit14
postgis 在 EL 系统的包名中有自己的版本号：默认是 postgis35

4 - 加载扩展

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

除了纯 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过程中保留复制槽

5 - 启用扩展

如何通过 CREATE EXTENSION 在 PostgreSQL 数据库中真正启用扩展？

快速上手

PostgreSQL 扩展 安装完毕 后，用户可以通过 CREATE EXTENSION 命令启用扩展：

CREATE EXTENSION vector;      -- 安装向量数据库扩展（无需加载）
CREATE EXTENSION timescaledb; -- 安装时序数据库扩展（需要加载）

有的扩展插件有依赖的扩展，在这种情况下，您可以首先安装依赖的扩展，或者选择执行 CREATE EXTENSION CASCADE 命令，一次性安装所有依赖的扩展。

CREATE EXTENSION documentdb CASCADE; -- 安装 documentdb 扩展，并安装它所有依赖的扩展

您还可以在 CREATE EXTENSION 命令中指定安装扩展的模式与具体版本。

配置扩展

扩展（数据库逻辑对象）在逻辑上属于 PostgreSQL 数据库 的组成部分，因此在 Pigsty 中，您可以在 pg_databases 中指定要在数据库中启用/创建的扩展。

pg_databases:
  - name: postgres
    baseline: supabase.sql
    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 的轻量级消息队列

在这里，数据库对象中的 extensions 是一个列表，每个元素可能是：

一个扩展名，简单的字符串，例如 vector
一个字典，可能包含以下字段：
- name：唯一的 必选字段，指定扩展名，注意扩展名有可能不同于扩展包名。
- schema ：指定扩展安装的模式，默认是当前数据库超级用户搜索路径中的第一个模式，通常是默认的 public。
- version ：指定扩展的版本，默认是最新版本

如果数据库没有创建，在这里定义的扩展会在通过 Pigsty 创建集群 或 创建数据库 的时候被自动启用。

如果数据库已经启用并投产，我建议您通过标准的数据库模式变更流程（Schema Migration）来管理扩展的启用。您可以在 Pigsty 配置文件中记录相应的修改，便于日后迁移等用例。

默认启用的扩展

Pigsty 默认会为托管的 PostgreSQL 数据库安装一些默认扩展，这些扩展会被创建至默认的 template1 模板数据库与 postgres 数据库中。任何新建的数据库都会继承 template1 中的扩展配置，因此您无需额外配置，新建的数据库也会拥有这些扩展。

您可以通过修改 pg_default_extensions 参数，来修改全局默认安装启用的扩展，以及它们安装的位置。

所有在本参数重默认启用的扩展都是 PostgreSQL 自带的第一方 Contrib 扩展，唯一的例外是 pg_repack 扩展，它是一个来自 PGDG 的第三方扩展。 pg_repack 对于 PostgreSQL 表膨胀治理 非常重要，因此 Pigsty 默认会默认安装它并在所有数据库中默认启用。

pg_default_extensions:
  - { name: pg_stat_statements ,schema: monitor }
  - { name: pgstattuple        ,schema: monitor }
  - { name: pg_buffercache     ,schema: monitor }
  - { name: pageinspect        ,schema: monitor }
  - { name: pg_prewarm         ,schema: monitor }
  - { name: pg_visibility      ,schema: monitor }
  - { name: pg_freespacemap    ,schema: monitor }
  - { name: postgres_fdw       ,schema: public  }
  - { name: file_fdw           ,schema: public  }
  - { name: btree_gist         ,schema: public  }
  - { name: btree_gin          ,schema: public  }
  - { name: pg_trgm            ,schema: public  }
  - { name: intagg             ,schema: public  }
  - { name: intarray           ,schema: public  }
  - { name: pg_repack } # <-- 唯一默认启用的三方扩展

在 Pigsty 的设计中，与监控相关的扩展会被创建至 monitor 模式中，其他功能特性性质的扩展会被创建至 public 模式中。

此外，向量数据库扩展 pgvector 有着特殊地位，它在 Pigsty 中会默认安装，并在演示用的 meta 数据库中默认启用，作为演示之用。

最后，用于实现 CDC 变更数据捕获 的关键扩展 wal2json 扩展也会默认安装，但因为这是一个“无需启用”的逻辑解码插件，因此不会出现在 pg_default_extensions 中。

无需启用的扩展

并非所有扩展都需要通过 CREATE EXTENSION 命令启用。

从原理上来说：PostgreSQL 的扩展通常由以下三部分组成：

控制文件：包含关键元数据，必须
SQL文件：包含 SQL 语句，可选
库文件：包含二进制动态连接库（.so, .dylib, .dll），可选

对于扩展来说，SQL 文件是可选项，因此如果扩展没有提供 SQL 文件，则通常不需要执行 CREATE EXTENSION 命令。

LOAD \ DDL	需要 `CREATE EXTENSION`	不需要 `CREATE EXTENSION`
需要动态加载	使用 Hook 的扩展	无头扩展
不需要动态加载	不用 Hook 的扩展	逻辑解码输出插件

例如提供 CDC 抽取能力的 wal2json 扩展，提供慢查询统计能力的 pg_stat_statements 与 auto_explain 扩展。它们只有共享库文件和扩展 .control 文件，没有 SQL 文件，因此不需要/也无法通过 CREATE EXTENSION 命令启用。

请注意，没有 CREATE EXTENSION 命令，不影响扩展是否需要 LOAD 命令。一些扩展虽然没有 SQL/DDL，但仍然需要 显式加载 ，比如一些安全审计相关的扩展。

无需启用的扩展列表

以下是所有无需 DDL 的扩展列表：

扩展名	扩展包名	分类	说明
plan_filter	pg_plan_filter	FEAT	使用执行计划代价过滤阻止特定查询语句
pg_checksums	pg_checksums	ADMIN	在离线模式下激活/启用/禁用数据库集群的校验和功能
pg_crash	pg_crash	ADMIN	向数据库进程随机发送信号模拟故障
safeupdate	safeupdate	ADMIN	强制在 UPDATE 和 DELETE 时提供 Where 条件
basic_archive	basic_archive	ADMIN	归档模块样例
basebackup_to_shell	basebackup_to_shell	ADMIN	添加一种备份到Shell终端到基础备份方式
bgw_replstatus	bgw_replstatus	STAT	用于汇报本机主从状态的后台工作进程
pg_relusage	pg_relusage	STAT	打印查询引用的表与列
auto_explain	auto_explain	STAT	提供一种自动记录执行计划的手段
passwordcheck_cracklib	passwordcheck	SEC	使用cracklib加固PG用户密码
supautils	supautils	SEC	用于在云环境中确保数据库集群的安全
pg_snakeoil	pg_snakeoil	SEC	PostgreSQL动态链接库反病毒功能
pgextwlist	pgextwlist	SEC	PostgreSQL扩展白名单功能
sepgsql	sepgsql	SEC	基于SELinux标签的强制访问控制
auth_delay	auth_delay	SEC	在返回认证失败前暂停一会，避免爆破
passwordcheck	passwordcheck	SEC	用于强制拒绝修改弱密码的扩展
pg_statement_rollback	pg_statement_rollback	SIM	在服务端提供类似Oracle/DB2的语句级回滚能力
pg_failover_slots	pg_failover_slots	ETL	在Failover过程中保留复制槽
wal2json	wal2json	ETL	用逻辑解码捕获 JSON 格式的 CDC 变更
wal2mongo	wal2mongo	ETL	使用逻辑解码捕获MongoDB JSON格式的CDC变更
decoderbufs	decoderbufs	ETL	将WAL逻辑解码为ProtocolBuffer协议的消息
decoder_raw	decoder_raw	ETL	逻辑复制解码输出插件：RAW SQL格式
pgoutput	pgoutput	ETL	PG内置的逻辑解码输出插件
test_decoding	test_decoding	ETL	基于SQL的WAL逻辑解码样例

6 - 更新扩展

如何从安全地集群中移除扩展插件？

要更新一个现有的扩展，您需要首先更新操作系统的软件包管理器中的 RPM/DEB 包版本，然后在 PostgreSQL 中通过 ALTER EXTENSION ... UPDATE 命令将扩展更新到新版本。

升级扩展软件包

所有在 pg_extension 中指定的扩展，都可以使用 Pigsty 的 pgsql.yml 剧本进行升级。

./pgsql.yml -t pg_extension

Pigsty 的 pig 命令行工具也可以帮你完成这个任务，您无需了解操作系统的具体包名：

pig ext update  pgvector
pig ext install pgvector=0.8.0

你也可以使用操作系统的软件包管理器直接手动升级扩展软件包：

yum upgrade extname...
apt upgrade extname...

升级扩展软件包

然后执行数据库中的 ALTER EXTENSION ... UPDATE 命令，将扩展更新到新版本：

ALTER EXTENSION name UPDATE [ TO new_version ]

7 - 卸载扩展

如何从安全地集群中移除扩展插件？

移除扩展

要卸载某个扩展，通常需要执行 DROP EXTENSION 语句，例如：

DROP EXTENSION "<extname>";

请注意，如果有其他扩展，或者使用此扩展的数据库对象依赖，您需要首先卸载/删除这些依赖，然后再卸载此扩展；

或者，也可以使用以下语句一次性强制卸载扩展及其依赖：

DROP EXTENSION "<extname>" CASCADE;

注意：CASCADE 选项会删除依赖于此扩展的所有对象，包括数据库对象、函数、视图等，慎用！

并非所有扩展都是通过 CREATE EXTENSION 语句安装的，这些扩展不需要显式执行 DROP EXTENSION 语句，请参考 无需启用的扩展列表。

移除默认加载

如果您使用的扩展需要 动态加载（修改了 shared_preload_libraries 参数），您需要首先修改 shared_preload_libraries 参数。

将扩展名字符串从 shared_preload_libraries 中移除，并重启数据库集群生效后，您方可安全地卸载扩展包。

需要动态加载的扩展，请参考 需要加载的扩展 列表。

卸载扩展包

当你将扩展（逻辑对象）从集群中的 所有数据库 中移除后，您可以安全地卸载此扩展的软件包，Ansible 命令可以方便的帮您做到这一点：

ansible <cls> -m package -a "name=<extname> state=absent"

当然您也可以使用 pig ，或者 apt 或者 yum 的命令直接卸载。

如果您不知道扩展的名称，您可以参考 扩展列表 中的详情，或者参考 roles/node_id/vars 中定义的扩展包名映射。