Dev & EngARTICLE

PGXN replaces Docker with native GitHub Actions for PostgreSQL extensions

PGXN replaces Docker with native GitHub Actions for PostgreSQL extensions
Image: Roberto Diniz
Article · Dev & Eng
Reading
6 min
Code
3
In short

David Wheeler, maintainer of PGXN, retired the pgxn-tools Docker container and released three GitHub Actions that build, test across multiple Postgres versions, and publish extensions directly to the registry.

Anyone who maintains a PostgreSQL extension and publishes it on PGXN (PostgreSQL Extension Network) knows pgxn/pgxn-tools: a Docker image that, for years, was the standard way to run CI for this type of project. David Wheeler, maintainer of PGXN, has just retired that approach in favor of three native GitHub Actions, lighter and maintained separately: pgxn/postgres-action, pgxn/matrix-action, and pgxn/release-action.

The reason for the switch is straightforward. According to Wheeler himself:

I've made three new GitHub actions in the past few months to replace the venerable Docker-based pgxn/pgxn-tools, which has become bloated and requires more work to maintain than I'd like.

David Wheeler, maintainer of PGXN

The new actions require less maintenance, run on every operating system and architecture supported by GitHub's runners, and execute faster than the previous container. For anyone maintaining an extension in C, PL/pgSQL, or any language that compiles against Postgres, this means less CI queue time and a workflow that's easier to debug when something breaks.

Publishing to PGXN in a Few Lines

The simplest case is the release. With pgxn/release-action, the publishing workflow fits in a few lines:

yaml
name: 🚀 Release
on:
 push:
jobs:
 release:
 name: Release on PGXN
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v7
 - uses: pgxn/release-action@v0
 with:
 username: ${{ secrets.PGXN_USERNAME }}
 password: ${{ secrets.PGXN_PASSWORD }}
 dry-run: ${{ !startsWith(github.ref, 'refs/tags/v') }}

The action uses git archive to assemble the PGXN package and publish it. The dry-run option is the detail that prevents accidents: it only allows the actual publication when the push is from a tag that starts with v; on any other push, the workflow runs in test mode. Want to exclude files from the final package, such as the GitHub workflows themselves? Just configure that in .gitattributes.

The action also exposes the name of the generated file as output, which makes it possible to chain a GitHub release right afterward, using the softprops/action-gh-release action and passing the archive as an attachment. For anyone who wants an automatic changelog in the release body, Wheeler suggests keeping a file in the Keep a Changelog format and generating the corresponding excerpt with theory/changelog-version-notes-action, passed to the body_path option of the GitHub release.

Testing Against Multiple Postgres Versions, Without a Container

The most substantial part of the change lies in how the extension is tested against multiple Postgres versions. The pg-hostname project, cited by Wheeler as a real-world example, combines pgxn/matrix-action to generate the version matrix and pgxn/postgres-action to spin up each Postgres instance directly on the runner, without Docker:

yaml
name: ✅ CI
on: [push, pull_request]
jobs:
 matrix:
 name: 📋 Generate Matrix
 runs-on: ubuntu-latest
 outputs:
 matrix: ${{ steps.matrix.outputs.matrix }}
 steps:
 - name: Generate Matrix
 id: matrix
 uses: pgxn/matrix-action@v0
 with:
 min-version: 9.0
 beta: true
 deprecated: true
 no-os: windows

 build:
 needs: matrix
 strategy:
 fail-fast: false
 matrix:
 pg: ${{ fromJson(needs.matrix.outputs.matrix) }}
 name: ${{ matrix.pg.emoji }} ${{ matrix.pg.os }}/${{ matrix.pg.arch }} 🐘 v${{ matrix.pg.version }}
 runs-on: ${{ matrix.pg.runner }}
 steps:
 - uses: actions/checkout@v7
 - uses: pgxn/postgres-action@v0
 with: { version: \"${{ matrix.pg.version }}\" }
 - run: make -j $(nproc)
 - run: sudo make install
 - run: make installcheck
 id: test
 - name: Show Diffs
 if: failure() && steps.test.outcome == 'failure'
 run: find . -name regression.diffs -exec cat {} +
 - uses: actions/upload-artifact@v7
 if: failure()
 with:
 name: regression-${{ matrix.pg.os }}-${{ matrix.pg.arch }}-pg${{ matrix.pg.version }}
 path: |
 regression.diffs
 results

It's worth understanding each part. The matrix job calls pgxn/matrix-action with min-version: 9.0, including beta and deprecated versions, and excluding Windows (no-os: windows) because support for that system is still partial. The build job consumes that output with fromJson() and triggers one runner per combination of operating system, architecture, and Postgres version. The Postgres instance is spun up with pgxn/postgres-action, without needing a container; the sudo in make install is necessary because, on Linux runners, the process running the workflow doesn't own the Postgres installation (on other systems, sudo is harmless and can be ignored).

One relevant operational detail: pgxn/matrix-action runs a daily workflow that updates the list of candidate configurations. In practice, this means an extension starts being tested against the next Postgres version within a day of its first beta release, unless the maintainer sets a max-version to cap the ceiling.

The shared_preload_libraries Case

Extensions that need to be in shared_preload_libraries have an ordering problem: Postgres must be installed before the module can be compiled, but the module only works once Postgres has been restarted with it loaded. The solution documented by Wheeler is to call pgxn/postgres-action twice, the first time with no-start: true:

yaml
# Install but don't start Postgres
- uses: pgxn/postgres-action@v0
 with:
 version: ${{ matrix.pg.version }}
 no-start: true
# Build and install the extension
- run: make -j $(nproc) && sudo make install
# Now start Postgres with the module already in shared_preload_libraries
- uses: pgxn/postgres-action@v0
 with:
 config: |
 shared_preload_libraries = 'my_module'
# Continue with tests

For anyone maintaining a C extension that depends on preloading, this is the pattern to copy: it solves a problem that, with the old pgxn-tools, required workarounds inside the Docker image.

What Already Works and What's Still Missing

Wheeler says he has used the three actions for a few months on real extensions, including semver, pg_clickhouse, chdb, and hostname (the pg-hostname cited above). This gives the set some production track record, but he himself lists open issues:

  • Windows support is still incomplete: pgxn/postgres-action successfully tests a SQL-only extension on Postgres versions 17 and 18, but fails on earlier versions due to a path issue; C extensions simply don't work on Windows yet. Wheeler doesn't know whether the fix lies in the EDB binaries for Windows installed via Chocolatey or in additional action configuration, and has asked the community for help.
  • There's no action for pgrx yet: the framework that lets you write Postgres extensions in Rust still doesn't have a dedicated action; Wheeler plans to create one, separate from the others, in the coming months.

What Changes for Extension Maintainers

For those who already had a workflow based on pgxn/pgxn-tools, migration pays off mainly on three fronts: execution time (no overhead from spinning up a Docker container for every job), platform coverage (the runner's native architectures and operating systems, not just what fit in the image), and automatic updates to the matrix of supported versions. The cost is rewriting existing workflows in this new declarative format, and accepting, for now, that Windows with C extensions and pgrx are left out.

Anyone who wants to try it out can start from the pg-hostname repository itself, used as an example in Wheeler's original post, or follow the pgxn/postgres-action, pgxn/matrix-action, and pgxn/release-action repositories on GitHub to see the full documentation for each option, including beta, deprecated, no-os, and max-version in the matrix.

Translated from the Brazilian Portuguese original · Read the original