by Dickson S. Guedes

Hi everybody!

I’m proud to tell you that a new version of PGXN Utils was released with this new features:

• Git support
• Templates and custom templates
• PGXN Client integration

Git support

You can start a new extension with or without version control. By default pgxn-utils supports git but it will not create a repository unless you use --git option in the skeleton task.

You can try:

$ pgxn-utils skeleton my_cool_versioned_extension --git

When you create a new extension with git support in addition to creating the skeleton, pgxn-utils will initialize a git repository and create the initial commit.

Once you have your extension in a git repository your bundle will use only the committed files to create the archive, but if your repository is dirty then pgxn-utils will suggest that you to commit or stash your changes before bundling.

You must be careful with new files not added to repository, because they will not be archived.

Default templates

There are three default templates: sql, c and fdw. If you call skeleton without specifying a template, sql is the default. But if your extension will supply some C modules or you will create a FDW, you can create the extension calling skeleton with a --template option.

Try:

$ pgxn-utils skeleton my_cool_c_extension --template=c
$ pgxn-utils skeleton my_cool_fdw_extension --template=fdw

The templates contain example code and some links to PostgreSQL documentation that will try to help you to start coding. SQL and C templates contains some test examples, and the example code will compile and pass make installcheck. However, this code is intended to be an example, and you must write your own tests and code.

Custom templates

If you don’t like the templates provided by pgxn-utils you can create you own. Just create a directory with at least a META.json or META.json.tt file and then use your directory as argument to the --template option.

To know how create your own template, see the examples in the templates directory.

PGXN Client integration

If you have PGXN client installed you can change the command line from pgxn-utils some_task to pgxn some_task and this will save you some typing.

See:

$ cd /tmp
$ pgxn skeleton --help
PGXN Utils version: 0.1.4
Usage:
  pgxn skeleton extension_name

Options:
      [--git]                            # Initialize a git repository after create the extension
  -a, [--abstract=ABSTRACT]              # Defines a short description to abstract
  -p, [--target=TARGET]                  # Define the target directory
                                         # Default: .
      [--template=TEMPLATE]              # The template that will be used to create the extension. Expected values are: sql, c, fdw
                                         # Default: sql
  -r, [--release-status=RELEASE_STATUS]  # Initial extension's release status
  -d, [--description=DESCRIPTION]        # A long text that contains more information about extension
  -b, [--generated-by=GENERATED_BY]      # Name of extension's generator
  -l, [--license=LICENSE]                # The extension license
  -t, [--tags=one two three]             # Defines extension's tags
  -v, [--version=VERSION]                # Initial version
  -m, [--maintainer=MAINTAINER]          # Maintainer's name <maintainer@email>

Creates an extension skeleton in current directory

$ pgxn skeleton test
      create  test
      create  test/test.control
      create  test/.gitignore
      create  test/.template
      create  test/META.json
      create  test/Makefile
      create  test/README.md
      create  test/doc/test.md
      create  test/sql/test.sql
      create  test/sql/uninstall_test.sql
      create  test/test/expected/base.out
      create  test/test/sql/base.sql

$ cd test/
$ pgxn bundle
         run  make distclean from "."
      create  /tmp/test-0.0.1.zip

I hope you enjoy this version. “:)

I’ve had a few reports over the last few months that folks uploaded new extensions to PGXN but they failed to show up in search results. For example, as of right now, if you search for “distinct”, you get two results, OmniPITR and pgTAP. This despite the fact that the recently-released adaptive_estimator extension is tagged “distinct”. Author Tomas Vondra reported this issue, and it took me a couple of days to realize why it wasn’t showing up.

Here’s the reason: Only “stable” releases are indexed. The first and second adaptive_estimator releases both have their release status set to “testing”. The PGXN API only indexes stable releases. The idea behind that is that you want most folks to continue using stable releases while you work on testing new versions. So when users search the site, only the latest stable release will appear in search results. Similarly, installing an extension via the PGXN client, prefers the latest stable release by default. If you want the most recent, you have to specify the --unstable or --testing option.

So, the upshot is, if you want your extension to appear in the full text search results on the PGXN, site, release a stable version.

That said, I first noticed this issue a while ago, and filed an issue with the idea that, if an extension is uploaded that is not stable, but there are no stable versions, then the extension should be indexed, anyway. The idea here is that, when you first upload it, you don’t have any existing users to keep on a stable release anyway, because there is no stable release. So perhaps we should go ahead and index it. A non-stable release would only be omitted from the index if there was an existing stable release.

Thoughts?

By Daniele Varrazzo

Finally, here it is. Well tested, documented, and pampered. With the PGXN Client installing extensions from the PGXN Network is a breeze:

$ pgxn install semver
$ pgxn load semver
$ psql
=# select 'foo'::semver;
ERROR:  bad semver value 'foo': expected number at foo
LINE 1: select 'foo'::semver;

Error! Meaning: success!

The number of extensions on PGXN is steadily increasing, so we hope the client will make their adoption even easier.

The client is now extensible: either writing in Python to reuse some of the other commands implementation or writing new self-contained scripts in any language to be invoked by the pgxn commands dispatcher. The first client extensions are already available: PGXN Utils and PGXN:Meta:Validator are targeted for easier development of new extensions.

The client is released on PyPI, so installing is just:

$ sudo easy_install pgxnclient

Complete documentation and further links are available from the project homepage.

Any feedback is welcome; you can contact me and all the other people behind PGXN on the PGXN User Group. See you there!

by Dickson S. Guedes

Hello everyone!

I’m proud to tell you that a new version of pgxn_utils was released!

Now you can release a distribution to PGXN in five steps!

First, install it:

gem install pgxn_utils

Second, create your extension, optionally overwrite some defaults:

mkdir $HOME/extensions
cd $HOME/extensions
pgxn_utils skeleton my_extension --maintainer "Dickson S. Guedes"

Third, code!

Fourth, bundle it:

pgxn_utils bundle my_extension
Extension generated at: /home/guedes/extensions/my_extension-0.0.1.zip

Fifth, release it:

pgxn_utils release my_extension-0.0.1.zip
Enter your PGXN username: guedes
Enter your PGXN password: ******
Trying to release my_cool_extension-0.0.1.zip ... released successfully!
Visit: http://manager.pgxn.org/distributions/my_cool_extension/0.0.1

Ah, you can export PGXN_USER and PGXN_PASSWORD if you are tired to type your username and password everytime.

Check this out!.

By Daniele Varrazzo

During the last days I’ve done some lightweight hacking on the PGXN client, and I’ve just released the last package on PyPI, with the still very shy version number of 0.1a4.

First change: the package name. The package is now called pgxnclient, without the point. As Marti has commented, the point in the name could create problems to some distributions which may have needed to munge it into a shape fitting their naming constraints. So, in order to install the last release you will need the command:

$ easy_install pgxnclient

The name of the entry point script is still pgxn and it shouldn’t change.

One of the new features in this release is the addition of commands drop, to remove the the extensions of a distribution from a database (opposite of the load command) and uninstall, to remove installed files from the system (opposite of install).

Another change is the ability to work on a local zip or directory instead of using the API to get metadata and package from PGXN. The main goal of this feature is to help the packagers to test their packages with the client before submission, verifying that the data uploaded can be used in an automatized way.

A third change is in the install command: it previously required to be run as root if, as likely, the PostgreSQL directories are system ones. I was feeling this need slightly scary as download and build phases would have been run as root too, so now sudo is invoked by the script only when installing, with command line options allowing its customization.

What I feel mostly missing now is documentation: I know that adding it will force a big review of the code, adding missing comments, add tests to enforce what documented… so it’s something I will start tomorrow. Once documentation and code have converged there will also be a more sound basis to discuss about the client features. And dare version 0.2, maybe :)

Thanks everybody for the feedback. If you want to have a chat about the client or PGXN in general, the best place is the PGXN group. See you there!