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.

Install

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

Note
 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 git@github.com:decibel/pgxntool.git release

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

Usage

Typically, you can just create a simple Makefile that does nothing but include base.mk:

include pgxntool/base.mk

make targets

These are the make targets that are provided by base.mk

Note
 all the targets normally provided by Postgres PGXS still work.

test

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.

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
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.

Warning
 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.

results

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.

tag

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.

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

dist

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.

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

pgxntool-sync

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

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

Copyright (c) 2015 Jim Nasby <Jim.Nasby@BlueTreble.com>

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