安装扩展

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

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 包名。

注意事项

  • 查看 已知问题 了解已知问题
  • 存在两个已知的扩展冲突：
  • pgaudit 在 EL 系统上对于 PG 15 及以下版本有特殊的命名规则：pg16+ = pgaudit, pg15=pgaudit17, pg14=pgaudit16, pg13=pgaudit15, pg12=pgaudit14
  • postgis 在 EL 系统的包名中有自己的版本号：默认是 postgis35



最后修改 2025-03-07: routine update (2106723)