PGXN replaces Docker with native GitHub Actions for PostgreSQL extensions

- Reading
- 6 min
- Code
- 3
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:
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:
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
resultsIt'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:
# 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 testsFor 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-actionsuccessfully 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
Invalid input syntax for type json in PostgreSQL: how to find the real cause
A detailed benchmark shows that the most common error with json and jsonb columns in PostgreSQL hides different behaviors across drivers, versions, and even between json and jsonb in the same instance.





