Date: Mon, 7 Oct 2019 15:19:39 -0400
From: Bruce Momjian <bruce@momjian.us>
To: ivaylo.zlatanov@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: A Rant on lock_timeout
Message-ID: <20191007191939.GF4732@momjian.us>
References: <157019615723.25307.15449102262106437404@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <157019615723.25307.15449102262106437404@wrigleys.postgresql.org>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

On Fri, Oct  4, 2019 at 01:35:57PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/runtime-config-client.html
> Description:
> 
> Hello,
> 
> I was looking explicitly for information on the default value of
> lock_timeout and what it does. I got this paragraph:
> 
> "Abort any statement that waits longer than the specified number of
> milliseconds while attempting to acquire a lock on a table, index, row, or
> other database object. The time limit applies separately to each lock
> acquisition attempt. The limit applies both to explicit locking requests
> (such as LOCK TABLE, or SELECT FOR UPDATE without NOWAIT) and to
> implicitly-acquired locks. If log_min_error_statement is set to ERROR or
> lower, the statement that timed out will be logged. A value of zero (the
> default) turns this off."
> 
> Unfortunately, the crucial bit for me is in a sentence that hardly could be
> any more obscure: `A value of zero (the default) turns this off.` Before
> this sentence there are multiple statements; what exactly does `this` refers
> to? Does a value of zero turns of logging of timed out statements mentioned
> in the previous sentence? Would it be hard to put it like `A default value
> of zero means a statement will wait indefinitely to acquire a lock`.
> I believe the sole purpose of a technical document is to be precise. If I
> had to suggest setting this parameter as a solution to a critical issue of
> connections piling up waiting on locks and depleting connection pools, I can
> never be confident knowing that the current default value turns something
> off.

I completely agree. I have applied the attached patch to all supported
doc versions to move the mention of log_min_error_statement to a more
logical location.  Thanks for the report.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +