Re: Wiki link for max_connections? (Fwd: Re: [ADMIN] PostgreSQL oom_adj postmaster process to -17)

On Thu, Aug 9, 2012 at 11:27 AM, Kevin Grittner
<Kevin(dot)Grittner(at)wicourts(dot)gov> wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)gov> wrote:
>>> I see that we currently have five links to wiki.postgresql.org in
>>> release notes and four more in the rest of the docs. Are people
>>> OK with adding this link to the docs on max_connections? (Feel
>>> free to improve it before answering if you have qualms about the
>>> specifics on that page.)
>>
>> I'm generally not in favor of linking to the wiki unless there's
>> some reason that it wouldn't be appropriate to include the
>> material in the documentation in some form. I don't see that
>> that's the case here.
>
> All right, but we *really* need to actually get *something* into the
> docs on this, preferably back-patched. In the -admin thread which
> prompted Craig to plead for a link to the Wiki page, the OP thought
> it was reasonable to worry about how to configure the oom killer to
> deal with the situation that his 600 connections used all 32GB of
> RAM *plus* the 32GB of swap space he has configured. Imagine what
> performance must be like by the time it gets to *that* point!

Sure, I'm not opposed to documenting it. Putting it in the actual
documentation is not a demotion relative to putting a link to it in
the documentation! As for back-patching, we do that regularly with
documentation patches, as the situation seems to warrant.

> The OP clearly has read the docs, because he was attempting to take
> advice from the section on Linux Memory Overcommit. But as far as I
> have seen, there is nothing in the docs to suggest connection
> pooling. It is far better to avoid the oom killer by connection
> pooling than to tweak the oom killer configuration, yet you wouldn't
> have a clue about that from the docs.

Sounds easily fixable. Let's add a <note> to that section right after
the first paragraph.

> I actually think that the issue merits space in the docs roughly
> matchnig the Wiki page. Perhaps we could find a place in the Server
> Setup and Operation chapter to more-or-less include the current Wiki
> page contents, and reference *that* from the max_connections docs?

I think the page as it exists today needs some rewriting for tone, but
I think the contents are mostly OK. Also, I am a bit doubtful about
the advice on sizing the connection pool as applied to small servers:
surely it's not sane to recommend that a single-processor system with
one disk should have max_connections = 3. At least, *I* don't think
that's sane.

At least in HEAD/9.2, I like the idea of adding a section to Server
Setup and Operation to address this. Perhaps something like "Managing
Server Load" or "Preventing Server Overload". I think there's quite a
bit we could say in such a chapter apart from the stuff on maximum
connections, and I think it would be valuable to have that stuff in
our documentation rather than scattered around the Internet in wiki
articles and random Greg Smith web pages. I'm not sure we want to
back-patch an entire new chapter but let's put something together
first and then we'll figure out what makes sense.

A systemic problem with our documentation is that it tells you how to
do X, rather than what you ought to do. This is a good example of
that, but not the only one. We need to be careful of putting advice
in the docs that is one person's opinion rather than an actual best
practice, but I think there is plenty of stuff upon which enough
consensus exists that it really ought to be in the docs. Like, who
really uses REINDEX on a production system, rather than CREATE INDEX
CONCURRENTLY + DROP INDEX? Yet, you won't find that suggested in our
documentation anywhere, AFAIK.

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