# 上手 > 快速上手 pig，PostgreSQL 包管理器 --- LLMS index: [llms.txt](/llms.txt) --- 下面是一个简单的上手教程，带您体验 PIG 包管理器的核心能力。 ## 简短版本 ```bash curl -fsSL https://repo.pigsty.io/pig | bash # 从 Cloudflare 安装 PIG pig repo set # 一次性设置好 Linux, Pigsty + PGDG 仓库（覆盖式！） pig install -v 18 -y pg18 pg_duckdb vector # 安装 PG 18 内核，pg_duckdb, pgvector 扩展…… ``` ## 安装 您可以使用以下命令 [**一键安装**](/docs/pig/install/) `pig`： **中国大陆**： ```bash curl -fsSL https://repo.pigsty.cc/pig | bash ``` **全球网站**（Cloudflare CDN）： ```bash curl -fsSL https://repo.pigsty.io/pig | bash ``` PIG 二进制包大约 5 MB，在 Linux 上会自动使用 `rpm` 或 `dpkg` 安装所选镜像中的最新可用版本。下方示例输出中的 `X.Y.Z` 代表该镜像版本： ```bash $ curl -fsSL https://repo.pigsty.cc/pig | bash [INFO] kernel = Linux [INFO] machine = x86_64 [INFO] package = deb [INFO] pkg_url = https://repo.pigsty.cc/pkg/pig/vX.Y.Z/pig_X.Y.Z-1_amd64.deb [INFO] download = /tmp/pig_X.Y.Z-1_amd64.deb [INFO] downloading pig vX.Y.Z curl -fSL https://repo.pigsty.cc/pkg/pig/vX.Y.Z/pig_X.Y.Z-1_amd64.deb -o /tmp/pig_X.Y.Z-1_amd64.deb ######################################################################## 100.0% [INFO] installing: dpkg -i /tmp/pig_X.Y.Z-1_amd64.deb (Reading database ... 166001 files and directories currently installed.) Preparing to unpack /tmp/pig_X.Y.Z-1_amd64.deb ... Unpacking pig (X.Y.Z-1) ... Setting up pig (X.Y.Z-1) ... [INFO] pig vX.Y.Z installed successfully check https://pgext.cloud for details ``` ## 检查环境 PIG 是一个由 Go 编写的二进制程序，默认安装路径为 `/usr/bin/pig`，`pig version` 会打印版本信息： ```bash $ pig version pig version 1.7.0 linux/amd64 ``` 使用 `pig status` 命令，会打印当前环境的状态，操作系统代码，PG 的安装情况，仓库的可访问性与延迟。 ```bash $ pig status # [Configuration] ================================ Pig Version : 1.7.0 Pig Config : /home/vagrant/.pig/config.yml Log Level : info Log Path : stderr # [OS Environment] =============================== OS Distro Code : u26 OS OSArch : arm64 OS Package Type : deb OS Vendor ID : ubuntu OS Version : 26 OS Version Full : 26.04 OS Version Code : resolute # [PG Environment] =============================== Installed: * PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg26.04+1) 72 Extensions Active: PG Version : PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg26.04+1) Config Path : /usr/lib/postgresql/18/bin/pg_config Binary Path : /usr/lib/postgresql/18/bin Library Path : /usr/lib/postgresql/18/lib Extension Path : /usr/share/postgresql/18/extension # [Pigsty Environment] =========================== Inventory Path : Not Found Pigsty Home : Not Found # [Network Conditions] =========================== pigsty.cc ping ok: 376 ms pigsty.io ping ok: 1270 ms Internet Access : true Pigsty Repo : pigsty.io Inferred Region : china Latest Pigsty Ver : 4.5.0 ``` ## 自动化建议 对于生产环境恢复任务，建议先使用 `--plan` 预览 PITR 执行计划，再决定是否实际执行： ```bash pig pitr -d --plan # 仅预览恢复步骤，不执行 pig pitr -d -y # 跳过确认（自动化场景） ``` ## 列出扩展 先使用 `pig ext reload` 刷新在线目录，再使用 `pig ext list` 打印当前的 PG 扩展数据目录。 ```bash $ pig ext list ✓ Found 575 extensions Name Status Version Cate Flags License Repo PGVer Package Description ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── timescaledb available 2.29.1 TIME -dslt- Timescale PIGSTY 15-18 postgresql-18-timescaledb-tsl Enables scalable inserts and complex queries for time-series dat timescaledb_toolkit available 1.23.0 TIME -ds--- Timescale PIGSTY 15-18 postgresql-18-timescaledb-toolkit Library of analytical hyperfunctions, time-series pipelining, an timeseries available 0.2.1 TIME -d---- PostgreSQL PIGSTY 14-18 postgresql-18-pg-timeseries Convenience API for time series stack periods available 1.2.3 TIME -ds--- PostgreSQL PGDG 14-18 postgresql-18-periods Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO ........ pg_bulkload available 3.1.23 ETL bds--- BSD 3-Clause PIGSTY 14-18 postgresql-18-pg-bulkload pg_bulkload is a high speed data loading utility for PostgreSQL test_decoding available - ETL --s--x PostgreSQL CONTRIB 14-18 postgresql-18 SQL-based test/example module for WAL logical decoding pgoutput available - ETL --s--- PostgreSQL CONTRIB 14-18 postgresql-18 Logical Replication output plugin (575 Rows) ``` 所有的扩展元数据都在一份名为 [`extension.csv`](https://github.com/pgsty/pig/blob/main/cli/ext/assets/extension.csv) 的数据文件中定义， 这份文件会随着 pig 版本发布不断更新，您可以直接使用 [`pig ext reload`](/docs/pig/ext/#ext-reload) 命令更新这份数据文件。 更新后的文件会默认放置于 `~/.pig/extension.csv` 中，您可以查阅与更改；在线最新版目录可在 [**pigsty.io/ext/data/extension.csv**](https://pigsty.io/ext/data/extension.csv) 获取。 当前文档统一按 575 个已打包扩展表述；各扩展在不同 PostgreSQL 版本、操作系统与架构上的可用性，以实时支持矩阵为准。 ## 添加仓库 要想安装扩展，首先需要添加上游仓库。[`pig repo`](/docs/pig/repo/) 可用于管理 Linux APT/YUM/DNF 软件仓库配置。 您可以使用简单粗暴直接的版本 [`pig repo set`](/docs/pig/repo/#repo-set) 覆盖式写入现有仓库配置，该命令确保系统中只存在必须的仓库配置： ```bash pig repo set # 一次性配置好所有仓库，包括 Linux 系统仓库，PGDG，PIGSTY (PGSQL+INFRA) 仓库 ``` > **警告**：`pig repo set` 会备份并清理现有的仓库配置，然后添加所需的仓库，实现 Overwrite 语义，请务必注意！ 或者选择使用温和的 [`pig repo add`](/docs/pig/repo/#repo-add) 添加所需的仓库： ```bash pig repo add pgdg pigsty # 添加 PGDG 官方仓库 和 PIGSTY 补充仓库 pig repo add pgsql # 【可选】您也可以选择将 PGDG 和 PIGSTY 合在一起，当成一个 "pgsql" 模块整体添加 pig repo update # 更新缓存：apt update / yum makecache ``` PIG 会检测您的网络环境，并选择使用 Cloudflare 全球 CDN，或者中国境内云 CDN，但您可以通过 `--region` 参数强制指定区域。 在中国网络环境中，`-m|--mirror` 会明确选择内置的 `china` 仓库定义，包括 `pigsty.cc` 与维护中的国内镜像。 ```bash pig repo set --region=china # 使用中国区域镜像仓库加速下载 pig repo add pgdg --region=default --update # 强制指定使用 PGDG 上游仓库 pig repo set -m # 使用中国区域镜像覆盖式设置仓库 ``` PIG 本身不支持离线安装，您可以自行下载 RPM/DEB 包，拷贝到网络隔离的生产服务器安装。 相关项目 PIGSTY 提供本地软件仓库，支持可以使用 pig 从本地软件仓库安装已经下载好的扩展。 ## 安装 PG 添加仓库后，您可以使用 [`pig ext add`](/docs/pig/ext/#ext-add) 子命令安装扩展（以及相关软件包） ```bash pig ext add -v 18 -y pgsql timescaledb postgis vector pg_duckdb pg_mooncake # 安装 PG 18 内核与扩展，自动确认 # 该命令会自动执行翻译，将软件包翻译为 INFO[20:34:44] translate alias 'pgsql' to package: postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl INFO[20:34:44] translate extension 'timescaledb' to package: timescaledb-tsl_18 INFO[20:34:44] translate extension 'postgis' to package: postgis36_18 INFO[20:34:44] translate extension 'vector' to package: pgvector_18 INFO[20:34:44] translate extension 'pg_duckdb' to package: pg_duckdb_18 INFO[20:34:44] translate extension 'pg_mooncake' to package: pg_mooncake_18 INFO[20:34:44] installing packages: dnf install -y postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl timescaledb-tsl_18 postgis36_18 pgvector_18 pg_duckdb_18 pg_mooncake_18 ``` 这里使用了 "别名翻译" 机制，将清爽的 PG 内核/扩展 逻辑包名翻译为实际的 RPM/DEB 列表。如果您不需要别名翻译机制，可以直接使用 `apt/dnf` 安装， 或者使用变体 `pig install` 的 `-n|--no-translation` 参数： ```bash pig install vector # 带有翻译机制，安装当前 PG 18 对应的 pgvector_18 或 postgresql-18-pgvector pig install vector -n # 关闭翻译机制，安装名为 vector 的日志收集组件（来自 pigsty-infra 仓库） ``` ## 别名翻译 PostgreSQL 内核与扩展对应着一系列的 RPM/DEB 包，记住这些包是一件麻烦事，所以 pig 提供了许多常用的别名，帮助您简化安装过程： 例如在 EL 系统上， 下面的别名将会被翻译为右侧的对应 RPM 包列表： ```yaml pgsql: "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl" pg18: "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl" pg18-client: "postgresql18" pg18-server: "postgresql18-server postgresql18-libs postgresql18-contrib" pg18-devel: "postgresql18-devel" pg18-basic: "pg_repack_18 wal2json_18 pgvector_18" pg17-mini: "postgresql17 postgresql17-server postgresql17-libs postgresql17-contrib" pg16-full: "postgresql16 postgresql16-server postgresql16-libs postgresql16-contrib postgresql16-plperl postgresql16-plpython3 postgresql16-pltcl postgresql16-llvmjit postgresql16-test postgresql16-devel" pg15-main: "postgresql15 postgresql15-server postgresql15-libs postgresql15-contrib postgresql15-plperl postgresql15-plpython3 postgresql15-pltcl pg_repack_15 wal2json_15 pgvector_15" pg14-core: "postgresql14 postgresql14-server postgresql14-libs postgresql14-contrib postgresql14-plperl postgresql14-plpython3 postgresql14-pltcl" ``` 注意这里的 `$v` 占位符会被替换为 PG 大版本号，因此当您使用 `pgsql` 别名时，`$v` 会被实际替代为 18，17 这样的大版本号。 因此，当您安装 `pg18-server` 别名时，EL 上实际安装的是 `postgresql18-server`, `postgresql18-libs`, `postgresql18-contrib`，在 Debian / Ubuntu 上安装的是 `postgresql-18`，pig 会处理好所有细节。
常用 PostgreSQL 别名 [EL 使用的别名翻译列表](https://github.com/pgsty/pig/blob/main/cli/ext/catalog.go#L206) ```bash "pgsql": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl", "pgsql-mini": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib", "pgsql-core": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl", "pgsql-full": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit postgresql$v-test postgresql$v-devel", "pgsql-main": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl pg_repack_$v wal2json_$v pgvector_$v", "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", ``` [Debian / Ubuntu 系统使用的别名翻译](https://github.com/pgsty/pig/blob/main/cli/ext/catalog.go#L270) ```bash "pgsql": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v", "pgsql-mini": "postgresql-$v postgresql-client-$v", "pgsql-core": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v", "pgsql-full": "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-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector", "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` 替换为 `pg18`, `pg17`, `pgxx` 等具体大版本号。 当前活跃支持的 PostgreSQL 主版本范围为 **14-18**，例如对于 PostgreSQL 18，可以直接使用下面这些别名： | `pgsql` | `pg18` | `pg17` | `pg16` | `pg15` | `pg14` | |:---------------|:--------------|:--------------|:--------------|:--------------|:--------------| | `pgsql` | **`pg18`** | `pg17` | `pg16` | `pg15` | `pg14` | | `pgsql-mini` | `pg18-mini` | `pg17-mini` | `pg16-mini` | `pg15-mini` | `pg14-mini` | | `pgsql-core` | `pg18-core` | `pg17-core` | `pg16-core` | `pg15-core` | `pg14-core` | | `pgsql-full` | `pg18-full` | `pg17-full` | `pg16-full` | `pg15-full` | `pg14-full` | | `pgsql-main` | `pg18-main` | `pg17-main` | `pg16-main` | `pg15-main` | `pg14-main` | | `pgsql-client` | `pg18-client` | `pg17-client` | `pg16-client` | `pg15-client` | `pg14-client` | | `pgsql-server` | `pg18-server` | `pg17-server` | `pg16-server` | `pg15-server` | `pg14-server` | | `pgsql-devel` | `pg18-devel` | `pg17-devel` | `pg16-devel` | `pg15-devel` | `pg14-devel` | | `pgsql-basic` | `pg18-basic` | `pg17-basic` | `pg16-basic` | `pg15-basic` | `pg14-basic` | {.full-width}
## 安装扩展 pig 会检测当前系统环境中的 PostgreSQL 安装情况。如果检测到环境中（以 `PATH` 中的 `pg_config` 为准）有活跃的 PG 安装，那么 pig 会自动安装对应 PG 大版本所需的扩展，无需您显式指定 PG 大版本。 ```bash pig install pg_smtp_client # 更简单 pig install pg_smtp_client -v 18 # 显示指定大版本，更稳定可靠 pig install pg_smtp_client -p /usr/lib/postgresql/16/bin/pg_config # 另一种指定 PG 版本的方式 dnf install pg_smtp_client_18 # 最直接……，但并非所有扩展都这么简单…… ``` 提示：如需将特定大版本的 PostgreSQL 内核二进制加入 `PATH`，可用 `pig ext link` 命令： ```bash pig ext link pg18 # 创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh . /etc/profile.d/pgsql.sh # 立即生效，更新 PATH 环境变量 ``` 如果你想要安装特定版本的软件，可以使用 `name=ver` 的语法： ```bash pig ext add -v 18 pgvector=0.7.2 # install pgvector 0.7.2 for PG 18 pig ext add pg16=16.5 # install PostgreSQL 16 with a specific minor version ``` > **警告**：请注意，目前只有 PGDG YUM 仓库提供扩展历史版本，PIGSTY 仓库与 PGDG APT 仓库都只提供扩展的 **最新版本**。 ## 显示扩展 [`pig ext status`](/docs/pig/ext/#ext-status) 命令可以用于显示当前安装的扩展。 以下输出用于展示命令格式，是一次环境快照；PostgreSQL 小版本与扩展版本会随操作系统仓库更新，请以本机实时输出和当前软件包目录为准。 ```bash $ pig ext status ✓ PostgreSQL 18: 72 extensions installed (3 shown) PostgreSQL 18: PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg26.04+1) Binary: /usr/lib/postgresql/18/bin Extension: /usr/share/postgresql/18/extension Extension Stat: 3 Installed (PGDG 3, PIGSTY 0) + 69 CONTRIB = 72 Total Name Version Cate Flags License Repo Package Description ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── pg_repack 1.5.3 ADMIN bds--- PostgreSQL PGDG postgresql-18-repack Reorganize tables in PostgreSQL databases with minimal locks vector 0.8.4 RAG -ds--r PostgreSQL PGDG postgresql-18-pgvector vector data type and ivfflat and hnsw access methods wal2json 2.6 ETL --s--x BSD 3-Clause PGDG postgresql-18-wal2json Changing data capture in JSON format ``` 如果您的当前系统路径中找不到 PostgreSQL（以 `PATH` 中的 `pg_config` 为准），建议显式通过 `-v|-p` 指定 PG 大版本号或 `pg_config` 路径，以避免版本探测歧义。 ## 扫描扩展 [`pig ext scan`](/docs/pig/ext/#ext-scan) 提供更底层的扩展扫描功能，将扫描指定 PostgreSQL 目录下的共享库，从而发现安装了哪些扩展： 以下同样是历史环境快照，而不是 v4.5.0 候选软件包版本清单。 ```bash $ pig ext scan Installed: - PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2) 398 Extensions Active: PG Version : PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2) Config Path : /usr/bin/pg_config Binary Path : /usr/lib/postgresql/18/bin Library Path : /usr/lib/postgresql/18/lib Extension Path : /usr/share/postgresql/18/extension Name Version SharedLibs Description Meta ---- ------- ---------- --------------------- ------ timescaledb 2.25.1 Enables scalable inserts and complex queries... module_pathname=$libdir/timescaledb-2.24.0 relocatable=false trusted=true lib=... timescaledb_toolkit 1.22.0 Library of analytical hyperfunctions... relocatable=false superuser=false module_pathname=$libdir/timescaledb_toolkit lib=... periods 1.2 Provide Standard SQL functionality for PERIODs module_pathname=$libdir/periods relocatable=false requires=btree_gist lib=periods.so pg_cron 1.6 Job scheduler for PostgreSQL relocatable=false schema=pg_catalog module_pathname=$libdir/pg_cron lib=pg_cron.so postgis 3.6.1 PostGIS geometry and geography spatial types... module_pathname=$libdir/postgis-3 relocatable=false lib=postgis-3.so vector 0.8.1 vector data type and ivfflat and hnsw access... relocatable=true lib=vector.so pg_duckdb 1.1.0 DuckDB Embedded in Postgres module_pathname=$libdir/pg_duckdb relocatable=false schema=public lib=... ... ``` ## 容器实战 您可以创建一台全新的虚拟机，或者使用下面的 Docker 容器进行功能测试，创建一个 `d13` 目录，创建 `Dockerfile`： ```dockerfile FROM debian:13 USER root WORKDIR /root/ CMD ["/bin/bash"] RUN apt update && apt install -y ca-certificates curl && curl https://repo.pigsty.io/pig | bash ``` ```bash docker build -t d13:latest . docker run -it d13:latest /bin/bash pig repo set --region=china # 添加中国区域的仓库 pig install -y pg18 # 安装 PGDG 18 内核包 pig install -y postgis timescaledb pgvector pg_duckdb ```