快速上手
Module:
Pigsty 让您可以直接在 PGSQL 集群中，通过声明式的方式启用 PostgreSQL 插件。
概览
通常想要在一套 PostgreSQL 集群中使用插件，涉及到 下载、安装、加载、启用 四个核心问题：
-
怎样下载扩展：
repo_upstream&repo_packages在 Pigsty 默认在线安装时，已经默认下载了当前首要PG大版本（16）可用的所有扩展，如果不需要添加额外或者冷门扩展，通常都不需要您操心
repo_upstream与repo_packages以及扩展下载相关的问题。 -
安装哪些扩展：
pg_extensions&pg_packages在 Pigsty 配置模板中的样例集群中，已经提供了完整可用的扩展清单，您只需要将想要 安装 的扩展，添加到
pg_packages与pg_extensions中即可。 -
一小部分使用了 PostgreSQL HOOK 的扩展需要动态加载并重启数据库后才可以使用，您需要将这些扩展添加到
pg_libs中，并在重启加载后生效。 -
启用哪些扩展：
pg_databases.extensions绝大多数扩展在安装之后，都需要执行
CREATE EXTENSIONDDL 语句，才会真实在具体的数据库中被创建并启用。您可以手工执行此 DDL，或者在pg_datbasese.extensions中显式指定，则数据库会在初始化的时候自动启用这些扩展。
开箱即用
Pigsty 为用户封装了扩展管理的复杂度，您不需要知道这些扩展的 RPM 包名，也不需要知道如何下载，安装，加载，启用这些扩展，只需要在配置文件中声明您需要的扩展即可。
例如，下面的配置文件片段声明了一个 PostgreSQL 集群，安装 了所有可用的扩展插件，动态 加载 了三个扩展，并 启用 了三个扩展。
pg-meta:
hosts:
10.10.10.10: { pg_seq: 1, pg_role: primary }
vars:
pg_cluster: pg-meta
pg_databases:
- name: meta
extensions:
- { name: postgis }
- { name: timescaledb }
- { name: vector }
pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
pg_extensions:
- timescaledb periods temporal_tables emaj table_version pg_cron pg_later pg_background pg_timetable #[TIME]#
- postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip #[GIS]#
- pgvector pgvectorscale pg_vectorize pg_similarity pg_tiktoken pgml #[RAG]#
- pg_search pg_bigm zhparser hunspell #[FTS]#
- hydra pg_lakehouse duckdb_fdw pg_fkpart pg_partman plproxy #citus pg_strom #[OLAP]#
- age hll rum pg_graphql pg_jsonschema jsquery pg_hint_plan hypopg imgsmlr pg_ivm pgmq pgq #[FEAT]#
- pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh pljava #plr faker pgtap #[LANG]#
- prefix semver pgmp pguint pgunit roaringbitmap md5hash asn1oid numeral pg_rational ip4r pgsphere pgfaceting timestamp9 #[TYPE]# #[FUNC]# #[ADMIN]# #[STAT]# #[SEC]#
- pg_gzip pg_http topn pg_net pgjwt shacrypt pgsql_tweaks pg_extra_time count_distinct extra_window_functions first_last_agg tdigest pgpcre icu_ext pg_idkit pg_hashids pg_uuidv7 permuteseq sequential_uuids
- pg_repack pg_squeeze pg_dirtyread pgfincore pgdd ddlx pg_prioritize pg_checksums pg_readonly safeupdate pg_permissions pg_auto_failover preprepare pg_catcheck
- pg_profile pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats bgw_replstatus pg_sqlog powa pgmeminfo toastinfo
- passwordcheck supautils pgsodium pg_vault anonymizer pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user tablelog pg_snakeoil pgextwlist
- wrappers multicorn mongo_fdw mysql_fdw tds_fdw sqlite_fdw hdfs_fdw pgbouncer_fdw firebird_fdw #oracle_fdw db2_fdw #[FDW]#
- mysqlcompat pgmemcache pgtt orafce pg_statement_rollback pg_dbms_lock pg_dbms_metadata #pg_dbms_job babelfish #[SIM]#
- pglogical pgl_ddl_deploy decoderbufs wal2json wal2mongo pg_failover_slots mimeo pg_fact_loader pg_bulkload #repmgr slony #[ETL]#
- gis-stack rag-stack fdw-stack fts-stack etl-stack feat-stack olap-stack supa-stack stat-stack json-stack #[STACK]#
您可能注意到这里的扩展名称既非 RPM / DEB 包名，而是由 Pigsty 封装简化过的 标准扩展名（Alias）。
在不同的操作系统发行版中，Pigsty 将标准扩展名翻译为对应 PG 大版本的 RPM / DEB 包名，这样您就无需关心不同操作系统发行版的扩展包名差异了。
在 Pigsty configure 过程中，针对特定操作系统发行版生成的默认配置里已经带有上述清单。
要安装这些扩展，您只需要根据自己的需求，在配置文件中将需要的扩展取消注释即可。
请注意，您依然可以在这里直接使用操作系统特定的 RPM/DEB 包名称。
预定义的扩展集合
如果您不清楚应该安装哪些扩展，Pigsty 为您提供了一些预定义的扩展集合（Stack），您可以根据自己的需求场景，选择其中一个集合与任意组合，将其添加到 pg_extensions 中即可。
gis-stack: 地理空间扩展集合，包括：postgis,pgrouting,pointcloud,h3,q3c,ogr_fdwrag-stack: 向量检索扩展集合，包括：pgvector,pgvectorscale,pg_vectorize,pg_similarity,pg_tiktoken,pgmlfts-stack: 全文检索扩展集合，包括：pg_search,pg_bigm,zhparser,hunspellfdw-stack: 外部数据扩展集合，包括：wrappers,mysql_fdw,tds_fdw,sqlite_fdwetl-stack: 数据ETL/CDC集合，包括：pglogical,pgl_ddl_deploy,wal2json,wal2mongo,decoderbufs,pg_fact_loader,pg_bulkload,pgloader,pgcopydbfeat-stack: 类型函数扩展集合，包括：age,hll,rum,pg_graphql,pg_jsonschema,jsquery,pg_ivm,pgq3,gzip,http,topn,pgjwtolap-stack: 数据仓库OLAP集合，包括：duckdb,duckdb_fdw,pg-lakehouse,hydra,timescaledb,pg-fkpart,pg-partman,plproxysupa-stack: Supabase扩展集合，包括：pg-graphql,pg-jsonschema,wrappers,pgvector,cron,supautils,pgsodium,vault,pgjwt,http,pg-netstat-stack: 统计监控扩展集合，包括：show-plans,pg-stat-kcache,pg-qualstats,pg-track-settings,pg-wait-sampling,pg-sqlogjson-stack: JSON处理扩展集合，包括：plv8,pg-jsonschema,pgjwt,jsquery,pg-graphql,ferretdb
当您在 pg_extensions 或 pg_packages 中指定了这些扩展集合时，Pigsty 会自动翻译，展开并安装其中的所有扩展插件。
安装、加载与启用
Pigsty 不仅允许您在配置文件中声明需要安装的扩展，还允许您在配置文件中直接声明需要加载的扩展，以及需要启用的扩展。
下面是一个具体的例子：Supabase。 Supabase 是一个封装 PostgreSQL 作为底层存储的“上层抽象数据库”，它深度使用了 PostgreSQL 的扩展机制。 以下是使用 Pigsty 创建一套 Supabase 所需 PostgreSQL 集群的样例配置文件：
# supabase example cluster: pg-meta
# this cluster needs to be migrated with app/supabase/migration.sql :
# psql postgres://supabase_admin:[email protected]:5432/supa -v ON_ERROR_STOP=1 --no-psqlrc -f ~pigsty/app/supabase/migration.sql
pg-meta:
hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
vars:
pg_cluster: pg-meta
pg_users:
- { name: supabase_admin ,password: 'DBUser.Supa' ,pgbouncer: true ,inherit: true ,superuser: true ,replication: true ,createdb: true ,createrole: true ,bypassrls: true }
pg_databases:
- name: supa
baseline: supa.sql # the init-scripts: https://github.com/supabase/postgres/tree/develop/migrations/db/init-scripts
owner: supabase_admin
comment: supabase postgres database
schemas: [ extensions ,auth ,realtime ,storage ,graphql_public ,supabase_functions ,_analytics ,_realtime ]
extensions:
- { name: pgcrypto ,schema: extensions } # 1.3 : cryptographic functions
- { name: pg_net ,schema: extensions } # 0.9.2 : async HTTP
- { name: pgjwt ,schema: extensions } # 0.2.0 : json web token API for postgres
- { name: uuid-ossp ,schema: extensions } # 1.1 : generate universally unique identifiers (UUIDs)
- { name: pgsodium } # 3.1.9 : pgsodium is a modern cryptography library for Postgres.
- { name: supabase_vault } # 0.2.8 : Supabase Vault Extension
- { name: pg_graphql } # 1.5.7 : pg_graphql: GraphQL support
- { name: pg_jsonschema } # 0.3.1 : pg_jsonschema: Validate json schema
- { name: wrappers } # 0.4.1 : wrappers: FDW collections
- { name: http } # 1.6 : http: allows web page retrieval inside the database.
- { name: pg_cron }
# supabase required extensions
pg_libs: 'pg_net, pg_cron, pg_stat_statements, auto_explain' # add pg_net to shared_preload_libraries
pg_extensions:
- wal2json pg_repack
- supa-stack # pgvector pg_cron pgsodium pg_graphql pg_jsonschema wrappers pgjwt pgsql_http pg_net supautils
pg_parameters:
cron.database_name: supa
pgsodium.enable_event_trigger: off
pg_hba_rules: # supabase hba rules, require access from docker network
- { user: all ,db: supa ,addr: intra ,auth: pwd ,title: 'allow supa database access from intranet' }
- { user: all ,db: supa ,addr: 172.0.0.0/8 ,auth: pwd ,title: 'allow supa database access from docker network'}
- { user: all ,db: supa ,addr: all ,auth: pwd ,title: 'allow supa database access from entire world' } # not safe!
在这里，我们声明了一个名为 pg-meta 的 PostgreSQL 集群，它包含了一个名为 supa 的数据库，以及一系列的扩展插件。
在 pg_extensions 中定义的 supa-stack 被翻译为 pgvector pg_cron pgsodium pg_graphql pg_jsonschema wrappers pgjwt pgsql_http pg_net supautils，并自动安装。
与此同时，pg_libs 指定了两个需要动态加载的扩展： pg_net 与 pg_cron；此外，pgsodium 与 pg_cron 扩展所必须的配置参数，也通过 pg_parameters 预先指定；
接下来，这些扩展在 pg_databases.extensions 中被依次创建到指定的/或默认的 Schema 中，正式启用。
最后，这样一个开箱即用，可以直接供无状态 Supabase 容器使用的高可用 PostgreSQL 集群，就能在一行 ./pgsql.yml 命令中被完整拉起，开箱即用。
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.