Re: Documentation of server configuration - Mailing list pgsql-docs

Peter,

> I have made an attempt and reformatted the whole section into one big
> alphabetical list, and while that has obvious drawbacks, I feel that
> it's already much more usable than what we have now.

I disagree, absolutely and completely.   "one big alphabetical list" doesn't
help at all in figuring out what you need to work with if you're running out
of memory of if your queries have bad plans.   "effective_cache_size", for
example, is nowhere near "random_page_cost", even though both parameters
affect planner choice of index scans.

I did the grouping for 7.4, and numerous people on the performance list felt
it was an enormous improvement over the "one big list" we had before.
Further, the ordering in runtime-config matches the ordering in
postgresql.conf, which matches the ordering in the big spreadsheet of options
I prepared for 7.4 (and will again for 8.0) and the groups match the
categorization created in pg_settings view.

Further, I remember suggesting a couple months back that the runtime-config
page was too large and ought to be broken up for readability.   You
pooh-poohed the idea then, telling me there was nothing wrong with
runtime-config the way it was.  Apparently you changed your mind?

> - There are too many sections.

I disagree.   In fact, I was thinking of creating some more sections.

> - The sections don't have any obvious order.

The current order is based loosely on the original postgresql.conf order, with
connections, then memory, then wal, then logs, etc.    There's no particular
reason for that section order other than familiarity.  I can see
re-organizing the sections.

> - The subsections don't have any obvious order.
> - The lists of individual parameters inside the sections don't have any
> order.

Actually, there's ordered according to the frequency with which people monkey
with that particular setting.   For example, lots of people change
effective_cache_size and random_page_cost, but very few touch index_cpu_cost,
for example.   In the postgresql.conf file, which is relatively compact, this
isn't much of a problem; it's only in runtime-config where lots of scrolling
is necessary that it makes stuff hard to find.

> - If a parameter has a list of possible values, the values are not
> listed in a consistent order.

Agreed.    I didn't touch the descriptions or reorder the parameters.

I can see that reordering the sections and subsections alphabetically might
help.   However, I can also see a pretty strong argument against; that is,
people are used to the current order and I don't see changing it just because
the runtime-config file is unusable.   If you want to fix runtime-config, how
about an *index*?

--
Josh Berkus
Aglio Database Solutions
San Francisco