Thread: WIP: document the hook system
Please find attached :) This could probably use a lot of filling in, but having it in the actual documentation beats needing to know folklore even to know that the capability is there. 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
Attachment
On 2020-12-31 04:28, David Fetter wrote: > This could probably use a lot of filling in, but having it in the > actual documentation beats needing to know folklore even to know > that the capability is there. This patch seems quite short of a state where one could begin to evaluate it. Documenting the hooks better seems a worthwhile goal. I think the question is whether we can develop documentation that is genuinely useful by itself without studying the relevant source code. This submission does not address that question.
On Fri, Jan 15, 2021 at 12:28 AM Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
On 2020-12-31 04:28, David Fetter wrote:
> This could probably use a lot of filling in, but having it in the
> actual documentation beats needing to know folklore even to know
> that the capability is there.
Typo - the entity definition hooks should be listed before infoschema, not after.
This patch seems quite short of a state where one could begin to
evaluate it. Documenting the hooks better seems a worthwhile goal. I
think the question is whether we can develop documentation that is
genuinely useful by itself without studying the relevant source code.
This submission does not address that question.
Yeah, there seems to be a point further along this path we want to reach. In particular, having a complete example would be nice. Also needing explaining is the whole hook swapping thing (I don't think "cache" is the right term to use here) - like "why" it is important and how its useful given that the "Foo_hook" is never assigned away from "prev_Foo" so the restoration in _PG_fini seems redundant (I see the full example does assign the various old values away - but why is the needed and why doesn't another module doing the same thing end up clobbering this one in a last-one-wins way?)
I would also be curious whether a static listing of hooks in the documentation could instead be accomplished by writing a query and having the build routine populate a "pg_hooks" catalog table which would be referenced, and ideally could be queried at runtime to enumerate installed hooks.
Pointing out the presence of src/test/modules/test_rls_hooks would be advised (in addition to a more minimal "hello world" like example in the documentation itself). Having the test module point to the documentation for more explanations would be good as well.
Coming in with fresh eyes the main thing I would care about is that these exist, a brief idea of how they operate without having to dig into the source code, and pointers on where to learn which ones exist (ideally without digging into source code) and how to go about writing one (which builds upon material already documented about extending the service using the C programming language - so links there). I'm good with running a catalog query to learn about which ones exist instead of reading them in the documentation - though the later has some appeal and if it can be maintained as a build artefact alongside the catalog entries that would be a bonus.
David J.
On Fri, Jan 15, 2021 at 8:28 AM Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote: > > On 2020-12-31 04:28, David Fetter wrote: > > This could probably use a lot of filling in, but having it in the > > actual documentation beats needing to know folklore even to know > > that the capability is there. > > This patch seems quite short of a state where one could begin to > evaluate it. Documenting the hooks better seems a worthwhile goal. I > think the question is whether we can develop documentation that is > genuinely useful by itself without studying the relevant source code. > This submission does not address that question. Even just having a list of available hooks would be a nice improvement though :) But maybe it's something that belongs better in a README file instead, since as you say it's unlikely to be properly useful without looking at the source anyway. But just a list of hooks and a *very* high overview of where each of them hooks in would definitely be useful to have somewhere, I think. Having to find with "grep" whether there may or may not exist a hook for approximately what it is you're looking for is definitely a process to improve on. -- Magnus Hagander Me: https://www.hagander.net/ Work: https://www.redpill-linpro.com/
On 17.01.2021 16:53, Magnus Hagander wrote: > On Fri, Jan 15, 2021 at 8:28 AM Peter Eisentraut > <peter.eisentraut@enterprisedb.com> wrote: >> On 2020-12-31 04:28, David Fetter wrote: >>> This could probably use a lot of filling in, but having it in the >>> actual documentation beats needing to know folklore even to know >>> that the capability is there. >> This patch seems quite short of a state where one could begin to >> evaluate it. Documenting the hooks better seems a worthwhile goal. I >> think the question is whether we can develop documentation that is >> genuinely useful by itself without studying the relevant source code. >> This submission does not address that question. > Even just having a list of available hooks would be a nice improvement though :) > > But maybe it's something that belongs better in a README file instead, > since as you say it's unlikely to be properly useful without looking > at the source anyway. But just a list of hooks and a *very* high > overview of where each of them hooks in would definitely be useful to > have somewhere, I think. Having to find with "grep" whether there may > or may not exist a hook for approximately what it is you're looking > for is definitely a process to improve on. > +1 for README. Hooks are intended for developers and can be quite dangerous without proper understanding of the internal code. I also want to remind about a readme gathered by mentees [1]. It was done under a PostgreSQL license, so we can use it. By the way, is there any agreement on the plain-text format of PostrgeSQL README files or we can use md? [1] https://github.com/AmatanHead/psql-hooks/blob/master/Detailed.md -- Anastasia Lubennikova Postgres Professional: http://www.postgrespro.com The Russian Postgres Company