# 扩展插件

> 定义，创建，安装，启用 PostgreSQL 插件。
---

> 扩展是 PostgreSQL 的灵魂所在

Pigsty 收录了255 个预先编译打包、开箱即用的 PostgreSQL 强力扩展插件，其中包括一些强力扩展：

- [**PostGIS**](https://postgis.net/)：提供地理空间数据类型与索引支持，GIS 事实标准 （& [**pgPointCloud**](https://pgpointcloud.github.io/pointcloud/) 点云，[**pgRouting**](https://pgrouting.org/) 寻路）
- [**TimescaleDB**](https://www.timescale.com/)：添加时间序列/持续聚合/分布式/列存储/自动压缩的能力
- [**PGVector**](https://github.com/pgvector/pgvector)：添加 AI 向量/嵌入数据类型支持，以及 ivfflat 与 hnsw 向量索引。（& [**pg_sparse**](https://github.com/paradedb/paradedb/tree/dev/pg_sparse) 稀疏向量支持）
- [**Citus**](https://www.citusdata.com/)：将经典的主从PG集群原地改造为水平分片的分布式数据库集群。
- [**Hydra**](https://www.hydra.so/)：添加列式存储与分析能力，提供比肩 ClickHouse 的强力分析能力。
- [**ParadeDB**](https://www.paradedb.com/)：添加 ElasticSearch 水准的全文搜索能力与混合检索的能力。（& [**zhparser**](https://github.com/amutu/zhparser) 中文分词）
- [**Apache AGE**](https://age.apache.org/)：图数据库扩展，为 PostgreSQL 添加类 Neo4J 的 OpenCypher 查询支持，
- [**PG GraphQL**](https://github.com/supabase/pg_graphql)：为 PostgreSQL 添加原生内建的 GraphQL 查询语言支持。
- [**DuckDB FDW**](https://github.com/alitrack/duckdb_fdw)：允许您通过 PostgreSQL 直接读写强力的嵌入式分析数据库 [**DuckDB**](https://github.com/Vonng/pigsty/tree/v2.7.0/app/duckdb) 文件 （& DuckDB CLI 本体）。
- [**Supabase**](https://github.com/Vonng/pigsty/tree/v2.7.0/app/supabase)：基于 PostgreSQL 的开源的 Firebase 替代，提供完整的应用开发存储解决方案。
- [**FerretDB**](https://github.com/Vonng/pigsty/tree/v2.7.0/app/ferretdb)：基于 PostgreSQL 的开源 MongoDB 替代，兼容 MongoDB API / 驱动协议。
- [**PostgresML**](https://github.com/Vonng/pigsty/tree/v2.7.0/app/pgml)：使用SQL完成经典机器学习算法，调用、部署、训练 AI 模型。

[![pigsty-extension.jpg](/img/pigsty/extension.png)](#扩展列表)

绝大部分扩展都是可以并存甚至组合使用的，妙用扩展可以产生 1+1 远大于 2 的协同增幅效应（例外：hydra 与 citus 互斥），实现 PostgreSQL for Everything！

绝大多数插件插件都已经收录放置在基础设施节点上的本地软件源中，可以直接通过 `yum`/`apt` 命令安装。您可以通过 Pigsty 配置文件指定需要下载、安装、启用的扩展，并自动完成安装与配置。

此外，有一些“数据库”其实并不是 PostgreSQL 扩展插件，但是基于 PostgreSQL，或与其密切相关。因此也收录在 Pigsty 中提供原生支持，
比如基于 PostgreSQL 提供开源 MongoDB 替代的 [FerretDB](https://github.com/Vonng/pigsty/tree/v2.7.0/app/ferretdb)，提供开源 Airtable 替代的 [NocoDB](https://github.com/Vonng/pigsty/tree/v2.7.0/app/nocodb)，提供交互式分析检视的 [Metabase](https://github.com/Vonng/pigsty/tree/v2.7.0/app/metabase) 等。



----------------

## 默认扩展

当您初始化 PostgreSQL 集群时，列于 [`pg_packages`](/zh/docs/reference/param#pg_packages) 与 [`pg_extensions`](/zh/docs/reference/param#pg_extension) 中列出的扩展插件将会被安装。

在 EL 系列系统（默认）和 Ubuntu/Debian 系列系统中，包的名称略有不同。但通常包含 `pg` (el) / `postgres` (deb)，和 PG 大版本号（目前默认为 16）。

Pigsty 允许在这两个变量中使用 `${pg_version}` 占位符，它将被自动替换成集群安装的 PG 大版本号。

在 EL / RPM （默认）系统中，默认安装的扩展为：

```yaml
pg_packages:     # 这三个扩展插件总是随主干大版本一起安装： pg_repack, wal2json, passwordcheck_cracklib
  - pg_repack_${pg_version}* wal2json_${pg_version}* passwordcheck_cracklib_${pg_version}*
pg_extensions:   # 待安装的 pg 扩展列表，默认安装 postgis，timescaledb，pgvector
  - postgis34_${pg_version}* timescaledb-2-postgresql-${pg_version}* pgvector_${pg_version}*
```

在 Ubuntu / Debian 系统中，默认安装的扩展为：

```yaml
pg_packages:    # 这两个扩展插件总是随主干大版本一起安装： pg_repack, wal2json
  - postgresql-${pg_version}-repack postgresql-${pg_version}-wal2json
pg_extensions:  # 待安装的 pg 扩展列表，默认安装 postgis，timescaledb，pgvector，citus
  - postgresql-${pg_version}-postgis* timescaledb-2-postgresql-${pg_version} postgresql-${pg_version}-pgvector postgresql-${pg_version}-citus-12.1
```

因此，Pigsty 默认安装的扩展为：

- `postgis`：地理空间数据库扩展（注意：EL7 的版本为 3.3，Ubuntu20 需要在线安装）
- `timescaledb`：时序数据库扩展插件（从 TimescaleDB 独立的仓库下载安装，特殊的包名）
- `pgvector`：向量数据类型与IVFFLAT/HNSW索引，向量数据库替代。
- `pg_repack`：在线处理表膨胀的维护性扩展：对于维护数据库健康非常重要，默认启用。
- `wal2json`：通过逻辑解码抽取JSON格式的变更：对于抽取数据库变更非常实用，无需显式启用。
- `passwordcheck_cracklib`：强制用户密码强度/过期策略，此扩展默认安装但可选，仅在EL中可用。
- `citus`：默认在 Debian/Ubuntu 中安装，EL系因为与 Fork 出来的列存插件 `hydra`冲突，用户可以二者择一安装。

您也可以在集群初始化完成后再安装新扩展插件，如下一节所示。


----------------

## 扩展安装

当集群已经完成初始化后，如果您需要向集群中安装新扩展，可以向 [`pg_extensions`](/zh/docs/reference/param#pg_extensions) 中添加扩展名称，并通过剧本完成安装。

例如，如果您想在 `pg-meta` 集群中安装用于分析的 `hydra` 与 `pg_analytics` 扩展，可以在集群配置文件中添加：

```yaml
pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1 ,pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - name: test
        extensions:  # <----- 在数据库中启用这些扩展 (`CREATE EXTENSION`)
          - { name: postgis, schema: public }
          - { name: timescaledb  }
          - { name: pg_analytics } # <---- 新增扩展
          - { name: duckdb_fdw   } # <---- 新增扩展
          - { name: hydra        } # <---- 新增扩展

    pg_libs: 'timescaledb, pg_cron, pg_stat_statements, auto_explain' # <- 个别扩展需要加载动态库方可运行
    pg_extensions:   # 安装到集群中的扩展列表 (yum/apt install)
      - postgis34_${pg_version}* timescaledb-2-postgresql-${pg_version}* pgvector_${pg_version}*          # 默认安装的三个扩展，如果需要，不要忘记保留
      - pg_analytics_${pg_version}* duckdb_fdw_${pg_version}* hydra_${pg_version}* #citus_${pg_version}*  # <-----+ 新增扩展

      #- pg_bm25_${pg_version}* pg_sparse_${pg_version}* zhparser_${pg_version}*                          # 其他备选扩展
      #- pg_graphql_${pg_version} pg_net_${pg_version}* pgsql-http_${pg_version}* vault_${pg_version} pgjwt_${pg_version} pg_tle_${pg_version}*
      #- pgml_${pg_version}* apache-age_${pg_version}* pg_roaringbitmap_${pg_version}* pointcloud_${pg_version}* pgsql-gzip_${pg_version}* pglogical_${pg_version}* pg_cron_${pg_version}*
      #- orafce_${pg_version}* mongo_fdw_${pg_version}* tds_fdw_${pg_version}* mysql_fdw_${pg_version} hdfs_fdw_${pg_version} sqlite_fdw_${pg_version} pgbouncer_fdw_${pg_version} powa_${pg_version}* pg_stat_kcache_${pg_version}* pg_stat_monitor_${pg_version}* pg_qualstats_${pg_version} pg_track_settings_${pg_version} pg_wait_sampling_${pg_version} hll_${pg_version} pgaudit_${pg_version}
      #- plprofiler_${pg_version}* plsh_${pg_version}* pldebugger_${pg_version} plpgsql_check_${pg_version}* pgtt_${pg_version} pgq_${pg_version}* pgsql_tweaks_${pg_version} count_distinct_${pg_version} hypopg_${pg_version} timestamp9_${pg_version}* semver_${pg_version}* prefix_${pg_version}* periods_${pg_version} ip4r_${pg_version} tdigest_${pg_version} pgmp_${pg_version} extra_window_functions_${pg_version} topn_${pg_version}
      #- pg_background_${pg_version} e-maj_${pg_version} pg_prioritize_${pg_version} pgcryptokey_${pg_version} logerrors_${pg_version} pg_top_${pg_version} pg_comparator_${pg_version} pg_ivm_${pg_version}* pgsodium_${pg_version}* pgfincore_${pg_version}* ddlx_${pg_version} credcheck_${pg_version} safeupdate_${pg_version} pg_squeeze_${pg_version}* pg_fkpart_${pg_version} pg_jobmon_${pg_version}
      #- pg_partman_${pg_version} pg_permissions_${pg_version} pgexportdoc_${pg_version} pgimportdoc_${pg_version} pg_statement_rollback_${pg_version}* pg_hint_plan_${pg_version}* pg_auth_mon_${pg_version} pg_checksums_${pg_version} pg_failover_slots_${pg_version} pg_readonly_${pg_version}* pg_uuidv7_${pg_version}* set_user_${pg_version}* rum_${pg_version}
```

使用 [`pgsql.yml`](/zh/docs/pgsql/playbook#pgsqlyml) 的 `pg_extension` 子任务，为已经创建好的集群添加扩展：

```bash
./pgsql.yml -l pg-meta -t pg_extension    # 为集群安装指定的扩展插件
```

您也可以在数据库服务器上使用 `yum` | `apt` 命令直接安装扩展软件包，或者使用 Ansible 模块来批量完成安装，但是这样您必须显式指明扩展的大版本号（目前为 16）：

```bash
cd ~/pigsty;               # 在管理节点上进入 pigsty 源码目录，为 pg-test 集群安装 pg_analytics 与 hydra 扩展
ansible pg-meta -m package -b -a 'name=pg_analytics_16'     # 扩展的名称通常后缀以 `_<pgmajorversion>`
ansible pg-meta -m package -b -a 'name=hydra_16*'           # 例如，您的数据库大版本为16，那么就应该在扩展yum包之后添加 `_16`
```

请注意，Pigsty 默认只下载 PG 主版本（PG16）上的主流扩展插件，当您使用其他大版本的 PostgreSQL 时，应当调整 [`repo_packages`](/zh/docs/reference/param#repo_packages) 中下载的插件名称。


----------------

## 扩展启用

安装 PostgreSQL 扩展后，您可以在 PostgreSQL 的 `pg_available_extensions` 视图中看到它们。但想要实际启用扩展，通常还需要额外的步骤：

1. 一部分扩展要求被添加到 `shared_preload_libraries` 中动态加载，例如 `timescaledb`，`citus` 等。
2. 大部分扩展都需要通过 SQL 语句：`CREATE EXTENSION <name>;` 启用，极少量扩展不需要，例如 `wal2json`。

* 修改 `shared_preload_libraries`：
  * 在数据库集群初始化前，可以通过 [`pg_libs`](/zh/docs/reference/param#pg_libs) 参数手工预先指定；
  * 当数据库已经初始化完毕后，您可以修改[集群配置](/zh/docs/pgsql/admin#配置集群)，直接修改 `shared_preload_libraries` 参数并应用（无需重启）。
  * 需要动态加载的典型插件：`citus`, `timescaledb`, `pg_cron`, `pg_net`, `pg_tle`
* 执行 `CREATE EXTENSION`：
    * 在数据库集群初始化前，可以在 [`pg_databases`](/zh/docs/reference/param#pg_databases).`extensions` 列表中指定。
    * 当数据库已经初始化完毕后，您可以直接连接数据库执行此 SQL 命令，或使用其他模式变更工具管理扩展。

> 从原理上讲：PostgreSQL 的扩展通常由 Control文件（元数据，一定存在），SQL文件（SQL语句，可选），So文件（二进制动态连接库，可选）三部分组成。
> 提供 `.so` 文件的扩展有可能需要添加到 `shared_preload_libraries` 才能生效，例如 `citus` 与 `timescaledb`，但也有许多扩展不用，例如 `postgis`，`pgvector`。
> 不通过 SQL 接口对外服务的扩展不需要执行 `CREATE EXTENSION`，例如提供 CDC 抽取能力的 `wal2json` 扩展。

在您希望启用扩展的数据库中执行 `CREATE EXTENSION` SQL 语句，即可完成扩展的创建：

```sql
CREATE EXTENSION vector;  -- 安装向量数据库扩展
CREATE EXTENSION hydra;   -- 安装列存数据库扩展
```


----------------

## 扩展下载

Pigsty 默认从 PostgreSQL 官方软件源下载扩展插件，如果您希望使用 Pigsty 没有收录的扩展，可以选择直接编译安装，
或者下载 RPM/DEB 包放置于管理节点上的本地软件源中（`/www/pigsty`），供所有节点使用，详情参考管理SOP-[添加软件](/zh/docs/pgsql/admin#添加软件)。

- YUM: https://download.postgresql.org/pub/repos/yum/16/redhat/
- APT: http://apt.postgresql.org/pub/repos/apt/