Re: PostgreSQL extension API? Documentation?

On 02/27/16 13:51, Álvaro Hernández Tortosa wrote:

> ... I still lack a list of functions that might be callable (I
> understand not even those labeled with PGDLLIMPORT are all good candidates
> and some good candidates might not be labeled as such) from an extension
> point of view. Have you come across such a list over any of these threads?

On my best understanding, there isn't really such a thing exactly.
If the formulation by Andres is persuasive ("We have a (mostly) proper API.
Just not an internal/external API split"), then the good references for
hacking an extension will be essentially the same as the good references
for hacking PostgreSQL, such as the "Hacking PostgreSQL Resources" found
on the "So, you want to be a developer?" wiki page:

https://wiki.postgresql.org/wiki/So,_you_want_to_be_a_developer%3F

Also, the PostgreSQL code repository has a lot of README files in
subdirectories where important pieces of the architecture happen,
and they are very informative and worth reading, and also the comments
are often quite comprehensive in the .h or .c files pertaining to the
parts of the system you need to interact with.

The extra ingredients for being an *extension* author, in the absence
of any formalized "this is the extension API" documentation, seem to be
those unformalized qualities like taste or restraint, in looking over
the available interfaces and judging which ones seem to be fundamental,
useful, stable, less likely to be whacked around later, etc. Those
qualities also can be called "enlightened self-interest" because you
are not looking forward to fixing your busted extension when something
you have relied on changes.

Another piece of the puzzle seems to be participating on -hackers
so that you may see what changes are coming, or possibly advocate
for why a particular interface really is useful to your extension
and is worth committing to.

If there is some subspace of possible extensions where you are
interested in working, taking on some maintenance of an existing
extension in that space, thereby getting familiar with what interfaces
it relies on and why, seems to be an effective baptism-by-fire. :)
The danger to avoid would be then drawing overbroad conclusions about
what should or shouldn't be extension API, based on what is useful
for the subspace of imaginable extensions in which you are working.

-Chap