内核版本

在 Pigsty 中选择"内核"意味着确定 PostgreSQL 大版本、模式/发行版、需要安装的包以及要加载的调优模板。

Pigsty v4.5 当前源码支持 PostgreSQL 14 - 18，默认使用 18。下方内容展示如何通过配置文件完成这些选择。

大版本与软件包

• pg_version：指定 PostgreSQL 主版本（默认 18）。Pigsty 会根据版本自动映射到正确的包名前缀。
• pg_packages：定义需要安装的核心包集合，支持使用 包别名（默认 pgsql-main pgsql-common，包含内核 + patroni/pgbouncer/pgbackrest 等常用工具）。
• pg_extensions：额外需要安装的扩展包列表，同样支持别名；缺省为空表示只装核心依赖。

all:
  vars:
    pg_version: 18
    pg_packages: [ pgsql-main, pgsql-common ]
    pg_extensions: [ postgis, timescaledb, pgvector, pgml ]

效果：Ansible 在安装阶段会拉取与 pg_version=18 对应的包，将扩展预装到系统中，随后数据库初始化脚本即可直接 CREATE EXTENSION。

Pigsty 的离线仓库中不同版本的扩展支持范围不同：14 可用扩展相对较少，17/18 覆盖最广。若某扩展未预打包，可通过 repo_extra_packages 追加。

内核模式（pg_mode）

pg_mode 控制要部署的内核“风味”，默认 pgsql 表示标准 PostgreSQL。Pigsty 目前支持以下模式：

pg_mode 决定二进制路径、Patroni 集成方式及部分内核特定逻辑；它本身不会自动替你补齐所有软件包、扩展与业务数据库。实际部署时应使用匹配的 conf/*.yml 配置模板，或显式配置 pg_packages、pg_extensions、pg_libs 与 pg_databases。以下是一个精简的 Citus 示例：

all:
  children:
    pg-citus1:
      hosts: { 10.10.10.11: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus1, pg_group: 0 }
    pg-citus2:
      hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus2, pg_group: 1 }
  vars:
    pg_mode: citus
    pg_shard: pg-citus
    pg_primary_db: citus
    pg_extensions: [ citus ]
    pg_libs: 'citus, pg_stat_statements'
    pg_databases:
      - { name: citus, extensions: [ citus ] }

conf/ha/citus.yml 提供了当前完整样例；上面的精简配置显式安装 Citus 包，并在 citus 数据库中创建扩展。

扩展与预置对象

除了系统包，你还可以通过以下参数控制数据库启动后自动加载的组件：

• pg_libs：写入 shared_preload_libraries 的列表。例如 pg_libs: 'timescaledb, pg_stat_statements, auto_explain'。
• pg_default_extensions / pg_default_schemas：控制初始化脚本对 template1 与 postgres 预创建的 schema、扩展。
• pg_parameters：由 Pigsty 在配置阶段渲染进 postgresql.auto.conf；不要再手工执行 ALTER SYSTEM 管理同一批参数。

示例：启用 TimescaleDB、pgvector 并自定义一些系统参数。

pg-analytics:
  vars:
    pg_cluster: pg-analytics
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
    pg_default_extensions:
      - { name: timescaledb }
      - { name: vector }
    pg_parameters:
      timescaledb.max_background_workers: 8

效果：初始化时 template1 与 postgres 会创建默认扩展；新建且使用 template1 的业务库会继承这些对象。pg_parameters 则直接写入 postgresql.auto.conf。

调优模板 (pg_conf)

pg_conf 指向 roles/pgsql/templates/*.yml 中的 Patroni 模板。Pigsty 内置四套通用模板：

你可以直接替换模板或自定义一个 YAML 文件放在 templates/ 下，然后在集群 vars 里指定。

pg-ledger:
  hosts: { 10.10.10.21: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-ledger
    pg_conf: crit.yml
    pg_parameters:
      synchronous_commit: 'remote_apply'
      max_wal_senders: 16
      wal_keep_size: '2GB'

效果：拷贝 crit.yml 作为 Patroni 配置，叠加 pg_parameters 写入 postgresql.auto.conf，使实例立即以同步提交模式运行。

组合实例：一个完整示例

pg-rag:
  hosts:
    10.10.10.31: { pg_seq: 1, pg_role: primary }
    10.10.10.32: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-rag
    pg_version: 18
    pg_mode: pgsql
    pg_conf: olap.yml
    pg_packages: [ pgsql-main, pgsql-common ]
    pg_extensions: [ pgvector, pgml, postgis ]
    pg_libs: 'pg_stat_statements, auto_explain'
    pg_parameters:
      max_parallel_workers: 8
      shared_buffers: '32GB'

• 第一台主库 + 一台 replica，使用 olap.yml 调优。
• 安装 PG18 + RAG 常用扩展；只有需要预加载的库才应写入 pg_libs。
• Patroni/pgbouncer/pgbackrest 由 Pigsty 生成，无需手工干预。

根据业务需要替换上述参数即可完成内核层的全部定制。