PGXNtool is meant to make developing new Postgres extensions for PGXN easier.

Currently, it consists a base Makefile that you can include instead of writing your own, a template META.json, and some test framework. More features will be added over time.

If you find any bugs or have ideas for improvements, please open an issue.


This assumes that you’ve already initialized your extension in git.

The --squash is important! Otherwise you’ll clutter your repo with a bunch of commits you probably don’t want.
git subtree add -P pgxntool --squash release

TODO: Create a nice script that will init a new project for you.


Typically, you can just create a simple Makefile that does nothing but include

include pgxntool/

make targets

These are the make targets that are provided by

all the targets normally provided by Postgres PGXS still work.


Runs unit tests via the PGXS installcheck target. Unlike a simple make installcheck though, the test rule has the following prerequisites: clean testdeps install installcheck. All of those are PGXS rules, except for testdeps.


This rule allows you to ensure certain actions have taken place before running tests. By default it has a single prerequisite, pgtap, which will attempt to install pgtap from PGXN. This depneds on having the pgxn client installed.

You can add any other dependencies you want by simply adding another testdeps rule. For example:

testdeps expmale from test_factory

testdeps: check_control

.PHONY: check_control
        grep -q "requires = 'pgtap, test_factory'" test_factory_pgtap.control

If you want to over-ride the default dependency on pgtap you should be able to do that with a makefile override. If you need help with that, please open an issue.

It will probably cause problems if you try to create a testdeps rule that has a recipe. Instead of doing that, put the recipe in a separate rule and make that rule a prerequisite of testdeps as show in the example.


Because make test ultimately runs installcheck, it’s using the Postgres test suite. Unfortunately, that suite is based on running diff between a raw output file and expected results. I STRONGLY recommend you use pgTap instead! The extra effort of learning pgTap will quickly pay for itself. This example might help get you started.

No matter what method you use, once you know that all your tests are passing correctly, you need to create or update the test output expected files. make results does that for you.


make tag will create a git branch for the current version of your extension, as determined by the META.json file. The reason to do this is so you can always refer to the exact code that went into a released version.

If there’s already a tag for the current version that probably means you forgot to update META.json, so you’ll get an error. If you’re certain you want to over-write the tag, you can do make forcetag, which removes the existing tag (via make rmtag) and creates a new one.

You will be very unhappy if you forget to update the .control file for your extension! There is an open issue to improve this.


make dist will create a .zip file for your current version that you can upload to PGXN. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json). The .zip file is placed in the parent directory so as not to clutter up your git repo.

Part of the clean recipe is cleaning up these .zip files. If you accidentally clean before uploading, just run make dist-only.


This rule will pull down the latest released version of PGXNtool via git subtree pull.

Your repository must be clean (no modified files) in order to run this. Running this command will produce a git commit of the merge.
There is also a pgxntool-sync-% rule if you need to do more advanced things.

Copyright (c) 2015 Jim Nasby <>

PGXNtool is released under a BSD license. Note that it includes, which is released under a MIT license.