Re: WAL consistency check facility

On Tue, Sep 13, 2016 at 9:04 PM, Michael Paquier
<michael(dot)paquier(at)gmail(dot)com> wrote:
> It seems to me that you need to think about the way to document things
> properly first, with for example:
> - Have a first documentation patch that explains what is a resource
> manager for WAL, and what are the types available with a nice table.
> - Add in your patch documentation to explain what are the benefits of
> using this facility, the main purpose is testing, but there are also
> mention upthread about users that would like to get that into
> production, assuming that the overhead is minimal.

So, I don't think that this patch should be required to document all
of the currently-undocumented stuff that somebody might want to know
that it is related to this patch. It should be enough to documented
the patch itself. One paragraph in config.sgml in the usual format
should be fine. Maybe two paragraphs. We do need to list the
resource managers, but that can just be something like this:

The default value of for this setting is <literal>off</>. To check
all records written to the write-ahead log, set this parameter to
<literal>all</literal>. To check only same records, specify a
comma-separated list of resource managers. The resource managers
which are currently supported are <literal>heap</>, <literal>btree</>,
<literal>hash</>, BLAH, and BLAH.

If somebody wants to write some user-facing documentation of the
write-ahead log format, great. That could certainly be very helpful
for people who are running pg_xlogdump. But I don't think that stuff
goes in this patch.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company