Thank you for contributing to the PostgreSQL community! Your support will not go unnoticed in this gathering of like-minded individuals who are all slightly smarter than each other. Your work will be seen by dozens of developers looking for community solutions to common problems. You have indeed made the open source world a better place.
Since we are talking about publication, you should consider the licensing model for your extension. The publication methods that we are about to describe assume that the extension will be made available to the general public. As such, please consider the PostgreSQL license for your extension. You can find the current one here:
http://www.postgresql.org/about/licence/
When you want to publish your module, you could start writing packaging scripts for each of the distribution systems for every operating system. This is the way the PostgreSQL extensions have been distributed in the past. That distribution system has not been very friendly to the open source community, or very well received. In an effort to make extension publication more palatable, a group of open source writers and backing companies got together and founded the PostgreSQL Extension Network (PGXN).
The PostgreSQL Extension Network http://pgxn.org/ provides a central repository for your open source extensions. By the kindness of the maintainers, it also provides installation scripts for your extensions that will work on most of the popular PostgreSQL deployment operating systems.
To sign up to publish your extension, perform the following steps:
- Start by requesting an account on the management page: http://manager.pgxn.org.
- Click on Request Account and fill in your personal information. The PostgreSQL Extension Network folks will get back to you via e-mail. Enrollment requests are currently processed by an actual human, so the e-mail response will not be immediate .
- Click on the provided link in the e-mail to confirm your account and set a new password on the PGXN website:
- You will then be prompted to create a password for your account:
- Set a password that you will remember, and confirm by typing it again. Click on Change and you will be welcomed to the site:
That is all there is to getting signed up. Once you have your new account set up, you can do a few things that will make PostgreSQL extension programming much more painless.
First, let's install some utility packages that will create a lot of boilerplate files that we have already described in earlier sections. The commands below are for a Debian/Ubuntu system:
apt-get install ruby apt-get install rubygems apt-get install ruby1.8-dev apt-get install libopenssl-ruby1.8 gem install rubygems-update /var/lib/gems/1.8/bin/update_rubygems gem install pgxn_utils
You will now find that you have a utility installed named pgxn-utils. This utility makes it super simple to create an extension project.
pgxn-utils skeleton myextension create myextension create myextension/myextension.control create myextension/META.json create myextension/Makefile create myextension/README.md create myextension/doc/myextension.md create myextension/sql/myextension.sql create myextension/sql/uninstall_myextension.sql create myextension/test/expected/base.out create myextension/test/sql/base.sql
Wow! All of the files that we have mentioned so far just got created in a single step. Several files also got created to support the old contrib style of deployment. The next few sections will show which ones are important to you for extension development.
This package management system has one notable restriction. In contrast to PostgreSQL, which allows version numbers to be any alphanumeric text, this package management requires version numbers to follow the rules of semantic versioning.
This version format includes major version, minor version, and release number in the format major.minor.release. This is to assist the package manager in installing your package on multiple operating system platforms. Just go with it, you'll thank us later.
There are three files used to provide data about the extension. The PostgreSQL Extension Network uses one of them on the website, META.json, for search criteria and description text for the extension. META.json will be located in myextension/META.json.
Here is an example:
{
"name": "myextension",
"abstract": "A short description",
"description": "A long description",
"version": "0.0.1",
"maintainer": "The maintainer's name",
"license": "postgresql",
"provides": {
"myextension": {
"abstract": "A short description",
"file": "sql/myextension.sql",
"docfile": "doc/myextension.md",
"version": "0.0.1"
}
},
"release_status": "unstable",
"generated_by": "The maintainer's name",
"meta-spec": {
"version": "1.0.0",
"url": "http://pgxn.org/meta/spec.txt"
}
}You should add some sections to it to describe your keywords and any additional resources that you make available to the user. These sections would look like this:
"tags": [
"cures cancer",
"myextension",
"creates world peace"
],
"resources": {
"bugtracker":
{"web": "https://github.com/myaccount/myextension/issues/"},
"repository": {
"type": "git",
"url": "git://github.com/myaccount/myextension.git",
"web": "https://github.com/myaccount/myextension/"
}
}The complete file would then look like this:
{
"name": "myextension",
"abstract": "A short description",
"description": "A long description",
"version": "0.0.1",
"maintainer": "The maintainer's name",
"license": "postgresql",
"provides": {
"myextension": {
"abstract": "A short description",
"file": "sql/myextension.sql",
"docfile": "doc/myextension.md",
"version": "0.0.1"
}
},
"release_status": "unstable",
"generated_by": "The maintainer's name",
"meta-spec": {
"version": "1.0.0",
"url": "http://pgxn.org/meta/spec.txt"
}
"tags": [
"cures cancer",
"myextension",
"creates world peace"
],
"resources": {
"bugtracker":
{"web": "https://github.com/myaccount/myextension/issues/"},
"repository": {
"type": "git",
"url": "git://github.com/myaccount/myextension.git",
"web": "https://github.com/myaccount/myextension/"
}
}
}The next file that you will need to modify is README.md. This file is located in myextension/README.md. An example is provided with the code that accompanies this book. Due to the length, it will not be reproduced here. This file is distributed along with your extension. It is a markdown syntax file that is meant for human consumption. Describe anything you like in it. Mine includes a recipe for Döner Kebabs. Quite tasty! But most importantly, put a nice long description of the benefits and ease of use of your extension. Finally, we come to doc/myextension.md. This file is used by the PostgreSQL Extension Network to provide a very nice landing page for your extension. It will look something like this:
This file is formatted with markdown. You may use several different markup syntaxes here. A discussion of wiki markup is beyond the scope of this description, but the formatting that is in the example is likely to be all you will ever need anyway.
Here is an example of the content of the file:
myextension =========== Synopsis -------- Show a brief synopsis of the extension. Description ----------- A long description Usage ----- Show usage. Support ------- There is issues tracker? Github? Put this information here. Author ------ [The maintainer's name] Copyright and License --------------------- Copyright (c) 2012 The maintainer's name.
Fill out the file with some descriptive narrative about your extension. Add anything that you think might be relevant to the user that is evaluating your extension before making a decision to install it. This is your chance to impress the masses of PostgreSQL developers. So don't be shy here.
Put your SQL code in the file that was provided for you in myextension/sql/myextension.sql. This file should contain all of the objects that make up your extension.
/* myextension.sql */ -- complain if script is sourced in psql, rather than via CREATE EXTENSION echo Use "CREATE EXTENSION myextension" to load this file. quit CREATE FUNCTION feed_the_hungry() ...
You can provide any additional SQL files in the same directory for maintaining versions as described in the Extension versions section. Anything named *.sql that is located in this directory will be included in the distribution.
To ultimately submit our extension to the PostgreSQL Extension Network, we need to package all the files into a single .zip file. Assuming we're following good practices, and we're keeping all of our source code in a handy Git repository, we can create the package through a simple Git command. Try this one on for size:
git archive --format zip --prefix=myextension-0.0.1/ --output ~/Desktop/myextension-0.0.1.zip master
This command will create a package for you that is suitable for submission to the PostgreSQL Extension Network. All we need to do now is submit it.
Now that you have a nice ZIP file in hand, you can go to the PostgreSQL Extension Network and make your accomplishment available to the community.
- Start by going to http://www.pgxn.org:
- At the bottom of the page is a link named Release It. Click on the link and you will be taken to the PGXN Manager where you should log in with the username and password that you created in the first section:
- Click on the link Upload a Distribution. This will bring you to the screen where you can upload the ZIP file that you created in the Creating the package section:
- Browse your computer for the ZIP file and upload it to the PostgreSQL Extension Network.
That's it. Thanks again for contributing to the PostgreSQL community.