https://blog.pgxn.org/tags/documentation/Documentation2011-05-13T20:34:46ZThe PGXN MaintainersHugohttps://blog.pgxn.org/post/5458118596New HOWTO2026-10-07T16:13:48Z2011-05-13T20:34:46ZDavid E. WheelerI updated the howto yesterday. This document explains how to create a PGXN distribution. If you’re interested in releasing PostgreSQL extensions on PGXN, this document is worth a read.

In essence, it’s really simple: Just create a META.json and upload. But to get the full benefit, there are quite a few other recommendations. Already familiar with it? Here’s the checklist:

  • Create a META.json
  • Create a control file
  • Create a Makefile
  • Implement the code in the sql and src directories
  • Write tests in the test directory
  • Write a Text::Markup-recognizable README
  • Write Text::Markup-recognizable documentation in the doc directory
  • Consider including other files: Changes, LICENSE, INSTALL, COPYING, AUTHORS
  • Release it!

Be sure to read the howto for details. Got feedback or suggestions? Leave a comment!

]]>I updated the howto yesterday. This document explains how to create a PGXN distribution. If you’re interested in releasing PostgreSQL extensions on PGXN, this document is worth a read.

In essence, it’s really simple: Just create a META.json and upload. But to get the full benefit, there are quite a few other recommendations. Already familiar with it? Here’s the checklist:

  • Create a META.json
  • Create a control file
  • Create a Makefile
  • Implement the code in the sql and src directories
  • Write tests in the test directory
  • Write a Text::Markup-recognizable README
  • Write Text::Markup-recognizable documentation in the doc directory
  • Consider including other files: Changes, LICENSE, INSTALL, COPYING, AUTHORS
  • Release it!

Be sure to read the howto for details. Got feedback or suggestions? Leave a comment!

Oh, and check out pgxn-utils and simplify your extension-development life.

]]>https://blog.pgxn.org/post/4970682941PGXN API Docs Published2026-10-07T16:13:48Z2011-04-27T00:27:55ZDavid E. WheelerThe PGXN API Documentation is up! I’ve just finished writing the docs for the lightweight REST API provided by all PGXN mirrors. It also documents how the same APIs differ when provided by the API server. Their are four more documents to write still, APIs provided by the API server but not the mirrors (including full-text search); I should be able to get those done tomorrow.

So if you’re interested in use the API for various things, please have a look! I’d appreciate any feedback or corrections.

]]>The PGXN API Documentation is up! I’ve just finished writing the docs for the lightweight REST API provided by all PGXN mirrors. It also documents how the same APIs differ when provided by the API server. Their are four more documents to write still, APIs provided by the API server but not the mirrors (including full-text search); I should be able to get those done tomorrow.

So if you’re interested in use the API for various things, please have a look! I’d appreciate any feedback or corrections.

Speaking of users of the API, Daniele Varrazzo has started writing a PGXN client app in Python. This is so awesome! It makes me happy that people are able to just get going on this. And Daniele did it before I’d written the docs, just from reading the PGXN source code. Nice!

Anyway, getting these docs written was the last barrier I had to releasing various pieces of PGXN on CPAN and generally being able to get on with my life. I wanted to write these docs first so that I would have a little more freedom to change things if something struct me as especially stupid. Fortunately, as I’ve written the main site as a thin client for the API, most of the lameness has already been excised. I think the only change I’d like to make is to change the {char} URI template variable for the userlist API to {letter}, because only lowercased ASCII letters a-z are allowed. It’s more accurate.

Another thing I think I’ll change is the file name suffix used for the distribution download files. Currently it’s .pgz, but after Daniele complained about it, I asked around and the concensus seems to be to change it to .zip. I’ll likely do that tomorrow, too. Fortunately it’s pretty easy: Just edit the configuration file and rename the files on the master mirror. At least it should be that easy!

There was one other thing in the APIs the felt a bit silly, but I don’t remember what it was, so screw it.

Anyway, feedback on the API docs would be greatly appreciated. And – get hacking!.

]]>https://blog.pgxn.org/post/4018670551Thoughts on Indexing and Documentation2026-10-07T16:13:48Z2011-03-22T05:13:00ZDavid E. WheelerSo I’m designing the full text indexing for the PGXN search site. I’m modeling it on CPAN Search, which has been great. There are four search options:

  • Full documentation search. This is the most common. Includes doc title and body.
  • User search. Search on names, nicknames, email addresses, URIs, etc.
  • Distribution search. Search on distribution name, abstract, description, tags, and the README.
  • Extension search. Search on extension name and abstract.
  • Tag search. Search on tag name only.

The documentation search is the one I’m perhaps least sure about. It assumes that each extension in a distribution will have documentation. But so far that has not really been the practice for PostgreSQL extensions. Most folks seem to stick the documentation in the README. And even then it can be almost nothing. So a search for “count nulls” probably would not find “countnulls” extension, because there is no documentation. What should I do about this? I’m thinking one of:

]]>So I’m designing the full text indexing for the PGXN search site. I’m modeling it on CPAN Search, which has been great. There are four search options:

  • Full documentation search. This is the most common. Includes doc title and body.
  • User search. Search on names, nicknames, email addresses, URIs, etc.
  • Distribution search. Search on distribution name, abstract, description, tags, and the README.
  • Extension search. Search on extension name and abstract.
  • Tag search. Search on tag name only.

The documentation search is the one I’m perhaps least sure about. It assumes that each extension in a distribution will have documentation. But so far that has not really been the practice for PostgreSQL extensions. Most folks seem to stick the documentation in the README. And even then it can be almost nothing. So a search for “count nulls” probably would not find “countnulls” extension, because there is no documentation. What should I do about this? I’m thinking one of:

  • Encourage folks to write documentation. I’m going to do this anyway, because the docs will really help the visibility of an extension on the site. It looks like this. If you have no docs for an extension, your extension will not appear in the search results (or perhaps it might, but link to the distribution).

  • If there is no documentation for an extension in a distribution, index the README as the documentation. I’m not really keen on this idea, because the README should describe the distribution, how to install it, etc. I’m planning to use it in the distribution-specific index. Documentation of the extension should be more about how the extension works, what it’s interface is, etc. Or so it seems to me, at least (I’m admittedly biased to this practice among CPAN modules). But at least with this approach there would be a link to “documentation” for an extension on the search site.

Erm, not really thinking of any other options. I feel pretty strongly that folks should write docs for their extensions, as much as possible, and I’ve set things up so that, from PGXN’s point of view, at least, you can write documentation in whatever format you like (assuming the format is supported by or added to Text::Markup), as long as they’re in a doc/ or docs directory. I want it to be as easy as possible. But I also want there to be decent search results ASAP.

Comments?

]]>https://blog.pgxn.org/post/1082188310Status Update: DB API, Extension Versions RFC2026-10-07T16:13:48Z2010-09-07T18:46:38ZDavid E. WheelerPGXN Manager. I had estimated 24 hours of work to design the database. So far I’ve logged 34 hours. But I think that will come out in the wash, really, because I did a lot of work to generate JSON from database functions. This is code I had originally expected to do in the app layer. I’m starting work on that this week, with an estimated 40 hours. Hope I can do it in 30. :-)]]>I spent most of the time I had to work on PGXN the last two weeks creating the database for PGXN Manager. I had estimated 24 hours of work to design the database. So far I’ve logged 34 hours. But I think that will come out in the wash, really, because I did a lot of work to generate JSON from database functions. This is code I had originally expected to do in the app layer. I’m starting work on that this week, with an estimated 40 hours. Hope I can do it in 30. :-)

I’m pretty happy with how the database API is turning out. See the nifty database API documentation I whipped up using gendoc and embedded MultiMarkdown. There are still a few tweaks I need to make. I just checked in a change to eliminate all the ALIASes I blogged about last week. Turns out that one can just function-name-qualify the function parameter names. Who knew? I sure didn’t.

But I do have a question for you, dear readers. Right now, the database requires that extensions have unique version numbers in every distribution. So if, for example, you uploaded the distribution foo 1.2.2 with the extension bar 1.2.2, when you next uploaded foo 1.2.3, bar could not be 1.2.2. I designed this this way by following my own practice of always incrementing the version numbers of all modules included in my CPAN distributions. So all modules have unique version numbers, with never a duplicate.

However, CPAN itself only cares that distributions have unique version numbers. It doesn’t care about the version numbers of included modules. See, for example, HTML::Mason. Note that the various included modules have all sorts of different version numbers, and many have no version numbers at all. So while the core module has a version number (1.45 at the time of this writing), if you click to look at older versions, say Mason 1.44, you’ll see that no other modules have their version numbers changed.

I don’t think I want to allow extensions without version numbers on PGXN. That’s been a recipe for many annoyances with CPAN. But maybe I should allow extension version numbers to repeat? The upside is less maintenance for multi-extension distribution authors. The downside is potentially less accuracy in the determination of prerequisites.

For example, say that we have two versions of distribution foo:

  -----------------------------------------------------------------------------
  Distribution                           Extensions
  -------------------------------------- --------------------------------------
  foo 1.2.2                              foo 1.2.2\
                                         bar 1.2.2

foo 1.2.3                              foo 1.2.3

bar 1.2.2

Note how the version number of extension bar has not changed between releases. But if I was a user of both foo and bar, and I specified that I required bar 1.2.2 but was actually using stuff in foo 1.2.3, I could end up with errors because I would only have foo 1.2.3.

This is an issue periodically faced by Perl hackers. I might require HTML::Mason::ApacheHandler 1.69 but really what I need is HTML::Mason 1.44. Of course, as a Perl hacker, it’s my responsibility to make sure I require exactly what I need, but sometimes it’s not clear what’s the primary module in a distribution. And if I don’t realize that the version number of HTML::Mason::ApacheHandler doesn’t change with every release, I might make mistakes.

Maybe that’s okay. Maybe PGXN should be less rigid like this. But I’m leaning toward keeping things as they are and requiring new versions of every extension in every upload of a distribution. It’s a bit tougher for those (few?) hackers who will create multi-extension distributions, but probably more reliable for everyone else.

What do you think?

Anyway, I’m getting to work on the Web app this week while this issue percolates. Been studying up on Plack. So nice!

]]>