Public APIs

Hi,

While I was looking at the Citus code base for a project at work, I
noticed a really ugly thing. It was a UDF called
alter_columnar_table_set(). It's clearly there because our current DDL
is a few bricks shy of a load, as others have phrased such things,
when it comes to accommodating the table AM API. A similar problem
exists when it comes to changing any GUC ending in "_libraries". There
is no way provided to change an existing value in place, only to
overwrite it. This is maybe OK if you'll only ever have between 0 and 1
.SOs loaded, but it gets to be a potentially serious problem if, for
example, you have two files in conf.d that set one. Then, we get
surprises caused by questions extension implementers really shouldn't
be saddled with, like "what order do such files get included in, and
what happens when a new one appears?"

The general issue, as I see it, is one that we can address by
providing reference implementations, however tiny, pointless, and
trivial, of each of our extension points
https://wiki.postgresql.org/wiki/PostgresServerExtensionPoints. I
learned about one, rendezvous variables, while writing this email.
Being public APIs, these all really need to be documented in our
official documentation, a thing I started on with the patch I'm
working on for the hooks system.

At a code level, this would be in the spirit of unit tests to ensure
that those extension points keep working by putting them in, say,
`make check-world` so as not to burden casual test runs.

Separately, it would be reasonable to make some efforts to ensure that
interactions among them are either safe or disallowed when attempted,
whichever seems reasonable to do. We can't cover the entire
combinatorial explosion, but adding a cross-check when someone has
reported a problem we can reasonably anticipate could recur would be a
big improvement.

We could start with "black hole" implementations, as Andrew Dunstan,
Michaël Paquier, and possibly others, have done, but actual working
systems would expose more weak points.

Would documenting these APIs be the right place to start?

Best,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate