pgxn/pgxn-tools Docker镜像文档

镜像概述

pgxn/pgxn-tools是一个用于自动化测试PostgreSQL扩展（针对多版本PostgreSQL）并发布到PGXN（PostgreSQL扩展网络）的Docker镜像。基于Debian Bookworm Slim构建，使用PostgreSQL Apt仓库安装PostgreSQL，支持8.2及以上版本（包括最新预发布版）。

核心功能与工具

镜像包含以下实用工具：

• pgxn: PGXN命令行客户端，用于从PGXN安装扩展依赖
• pg_prove: 运行pgTAP测试的工具
• pg-start: 安装指定主版本的PostgreSQL并启动集群
• pg-build-test: 构建并测试当前目录中的PGXS扩展
• pgrx-build-test: 构建并测试当前目录中的pgrx扩展
• pgxn-bundle: 验证PGXN META.json文件并打包发布版本
• pgxn-release: 将扩展发布到PGXN

使用场景

• 自动化测试PostgreSQL扩展在不同版本PostgreSQL上的兼容性
• 构建和验证PGXS或pgrx类型的PostgreSQL扩展
• 通过CI/CD流程（如GitHub Actions）自动发布扩展到PGXN
• 本地开发环境中快速测试扩展在多版本PostgreSQL上的表现

使用方法

基本容器运行

使用Docker CLI运行pgxn-tools容器，基本命令格式如下：

docker run -it --rm -w /repo --volume "$PWD:/repo" pgxn/pgxn-tools \
    sh -c 'pg-start 16 && pg-build-test'

此示例将当前目录挂载到容器的/repo目录，启动PostgreSQL 16，然后构建并测试该目录中的扩展。

非特权用户运行

注意：GitHub工作流容器作业必须以root运行，本节的非特权用户选项在此场景下不适用。

默认容器以root用户运行。如需以非特权用户运行，可通过AS_USER环境变量创建具有sudo权限的用户：

docker run -it --rm -w /repo -e AS_USER=worker \
    --volume "$PWD:/repo" pgxn/pgxn-tools \
    sh -c 'sudo pg-start 14 && pg-build-test'

创建的用户默认UID为1001，可通过LOCAL_UID指定本地UID以访问挂载卷中的文件：

docker run -it --rm -w /repo -e AS_USER=worker -e LOCAL_UID=$(id -u) \
    --volume "$PWD:/repo" pgxn/pgxn-tools \
    sh -c 'sudo pg-start 14 && pg-build-test'

容器中已包含nobody用户和pg-start创建的postgres用户，两者均具有无密码sudo权限。

GitHub工作流示例

测试PGXS扩展

以下工作流在每次推送和拉取请求时，针对多个PostgreSQL版本测试PGXS扩展：

name: CI
on: [push, pull_request]
jobs:
  test:
    strategy:
      matrix:
        pg: [17, 16, 15, 14, 13, 12, 11, 10, 9.6, 9.5, 9.4, 9.3, 9.2, 9.1, 9.0, 8.4, 8.3, 8.2]
    name: 🐘 PostgreSQL ${{ matrix.pg }}
    runs-on: ubuntu-latest
    container: pgxn/pgxn-tools
    steps:
      - name: 启动PostgreSQL ${{ matrix.pg }}
        run: pg-start ${{ matrix.pg }}
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 在PostgreSQL ${{ matrix.pg }}上测试
        run: pg-build-test

测试pgrx扩展

以下工作流测试pgrx扩展，使用缓存加速依赖安装：

name: CI
on: [push, pull_request]
jobs:
  test:
    strategy:
      matrix:
        pg: [16, 15, 14, 13, 12, 11]
    name: 🐘 PostgreSQL ${{ matrix.pg }}
    runs-on: ubuntu-latest
    container: pgxn/pgxn-tools
    steps:
      - name: 启动PostgreSQL ${{ matrix.pg }}
        run: pg-start ${{ matrix.pg }}
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 设置Rust缓存
        uses: Swatinem/rust-cache@v2
      - name: 在PostgreSQL ${{ matrix.pg }}上测试
        run: pgrx-build-test

发布到PGXN和GitHub

以下工作流在推送匹配v*标签时，自动发布到PGXN和GitHub：

name: Release
on:
  push:
    tags: ['v[0-9]+.[0-9]+.[0-9]+']
jobs:
  release:
    name: 发布到GitHub和PGXN
    runs-on: ubuntu-latest
    container: pgxn/pgxn-tools
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
    - name: 检出代码
      uses: actions/checkout@v4
    - name: 打包发布版本
      id: bundle
      run: pgxn-bundle
    - name: 发布到PGXN
      env:
        PGXN_USERNAME: ${{ secrets.PGXN_USERNAME }}
        PGXN_PASSWORD: ${{ secrets.PGXN_PASSWORD }}
      run: pgxn-release
    - name: 创建GitHub发布
      id: release
      uses: actions/create-release@v1
      with:
        tag_name: ${{ github.ref }}
        release_name: Release ${{ github.ref }}
        body: |
          本次发布变更
          - 变更1
          - 变更2
    - name: 上传发布资产
      uses: actions/upload-release-asset@v1
      with:
        upload_url: ${{ steps.release.outputs.upload_url }}
        asset_path: ./${{ steps.bundle.outputs.bundle }}
        asset_name: ${{ steps.bundle.outputs.bundle }}
        asset_content_type: application/zip

非特权用户工作流

GitHub工作流需要root用户操作工作区，可通过以下方式以非特权用户执行命令：

container: pgxn/pgxn-tools
steps:
  - uses: actions/checkout@v4
  - run: pg-start 16
  - run: chown -R postgres:postgres .
  - run: gosu postgres pg-build-test

或直接运行Docker镜像并指定用户：

steps:
  - uses: actions/checkout@v4
  - run: >-
      docker run -w /repo --rm --volume "$(pwd):/repo"
             -e AS_USER=pgxn_worker -e LOCAL_UID=$(id -u)
             pgxn/pgxn-tools sh -c 'pg-start && pg-build-test'

工具详情

pg-start

安装并启动指定版本的PostgreSQL集群：

pg-start 12                  # 安装并启动PostgreSQL 12
pg-start 11 libsodium-dev    # 安装PostgreSQL 11及额外依赖

• 支持版本：8.2及以上，包括预发布版
• 环境变量：
  • PGPORT: 指定端口（默认5432）
  • LANG: 设置集群区域（默认C.UTF-8）
  • NO_CLUSTER: 仅安装不启动集群（需手动使用pg_createcluster）

示例：修改配置文件并重启集群

# 获取配置文件路径
CONFIG_FILE=$(psql --no-psqlrc -U postgres -Atqc 'SHOW config_file')
# 添加配置
echo "shared_preload_libraries = '$libdir/plperl'" >> $CONFIG_FILE
# 重启集群
pg_ctlcluster 12 test restart

pg-build-test

构建并测试当前目录的PGXS扩展：

pg-build-test  # 构建并运行测试

• 等效于执行make && make install && make installcheck
• 环境变量PROFILE可自定义构建参数（默认--Werror）：

  export PROFILE=--Wall && pg-build-test
  

pgrx-build-test

构建并测试当前目录的pgrx扩展（需Cargo.toml中指定pgrx版本≥0.11.4）：

pgrx-build-test  # 构建并运行测试

• 自动安装指定版本的cargo-pgrx
• 支持运行make installcheck（如Makefile定义该目标）

pgxn-bundle

验证META.json并打包发布版本：

pgxn-bundle  # 从META.json读取名称和版本并打包
# 或手动指定
PGXN_DIST_NAME=widget PGXN_DIST_VERSION=1.0.0 pgxn-bundle

• 优先使用Git仓库打包，无Git时使用zip
• 环境变量：
  • GIT_ARCHIVE_CMD=archive-all: 包含Git子模块
  • GIT_BUNDLE_OPTS: 传递给git archive的参数
  • ZIP_BUNDLE_OPTS: 传递给zip的参数

pgxn-release

发布打包文件到PGXN：

export PGXN_USERNAME=用户名
export PGXN_PASSWORD=密码
pgxn-release  # 发布当前打包文件
pgxn-release widget-1.0.0.zip  # 发布指定文件

• 依赖环境变量PGXN_USERNAME和PGXN_PASSWORD
• 未指定文件时，自动从META.json或环境变量获取名称和版本

pgxn

PGXN命令行客户端，用于安装扩展依赖：

pgxn install semver  # 安装semver扩展

pg_prove

运行pgTAP测试：

pg_prove -r --ext .sql test/  # 递归运行test目录下的.sql测试文件

已安装组件

Debian包

• 构建工具：build-essential, clang, llvm, cmake
• PostgreSQL工具：pgxnclient, libtap-parser-sourcehandler-pgtap-perl
• 系统工具：sudo, gosu, ca-certificates, gnupg2, zip, unzip, curl, git
• 开发库：libicu-dev, libipc-run-perl, libtest-simple-perl, libxml2

Rust组件

• rustup (minimal配置)
• rustfmt, clippy

版权信息

• 作者：David E. Wheeler
• 版权：2020-2024 The PGXN Maintainers
• 许可：PostgreSQL License（详见LICENSE）