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.
git subtree add -P pgxntool --squash firstname.lastname@example.org:decibel/pgxntool.git 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 base.mk:
These are the make targets that are provided by base.mk
|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
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 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
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
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