Greetings,
* Tom Lane (tgl@sss.pgh.pa.us) wrote:
> Ian Barwick <ian.barwick@2ndquadrant.com> writes:
> >>> I dislike the special-casing of ALTER SYSTEM here, where we're basically
> >>> saying that only ALTER SYSTEM is allowed to do this cleanup and that if
> >>> such cleanup is wanted then ALTER SYSTEM must be run.
>
> > This is just saying what ALTER SYSTEM will do, which IMHO we should describe
> > somewhere. Initially when I stated working with pg.auto.conf I had
> > my application append a comment line to show where the entries came from,
> > but not having any idea how pg.auto.conf was modified at that point, I was
> > wondering why the comment subsequently disappeared. Perusing the source code has
> > explained that for me, but would be mighty useful to document that.
>
> I feel fairly resistant to making the config.sgml explanation much longer
> than what I wrote. That chapter is material that every Postgres DBA has
> to absorb, so we should *not* be burdening it with stuff that few people
> need to know.
Sure, I agree with that.
> Perhaps we could put some of these details into the Notes section of the
> ALTER SYSTEM ref page. But I wonder how much of this is needed at all.
I'd be alright with that too, but I'd be just as fine with even a README
or something that we feel other hackers and external tool developers
would be likely to find. I agree that all of this isn't something that
your run-of-the-mill DBA needs to know, but they are things that I'm
sure external tool authors will care about (including myself, David S,
probably the other backup/restore tool maintainers, and at least the
author of pg_conftool, presumably).
Of course, for my 2c anyway, the "low level backup API" is in the same
realm as this stuff (though it's missing important things like "what
magic exit code do you return from archive command to make PG give up
instead of retry"...) and we've got a whole ton of text in our docs
about that.
Thanks,
Stephen
