From 4363f34fc9c37993c24b9214896826d21fa97119 Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@postgresql.org>
Date: Thu, 24 Apr 2025 19:11:43 +0900
Subject: [PATCH] Doc: enhance the description on connection_life_time

connection_life_time is a config value to determine the life time of
cached connections to PostgreSQL backend. Current document lacks a
description that the expiration calculation is actually done at the
time when the client disconnects to the process which holds the cached
connections.

Discussion: [pgpool-hackers: 4577] Doc: enhance the description on connection_life_time
https://www.pgpool.net/pipermail/pgpool-hackers/2025-April/004578.html
Backpatch-through: v4.2
---
 doc.ja/src/sgml/connection-pooling.sgml |  5 +++++
 doc/src/sgml/connection-pooling.sgml    | 14 ++++++++++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/doc.ja/src/sgml/connection-pooling.sgml b/doc.ja/src/sgml/connection-pooling.sgml
index 3335e85ae..7f50d5679 100644
--- a/doc.ja/src/sgml/connection-pooling.sgml
+++ b/doc.ja/src/sgml/connection-pooling.sgml
@@ -444,6 +444,11 @@ pgbench -n -S -p 9999 -c 32 -C -S -T 300 test
       キャッシュされた<productname>PostgreSQL</>への接続を切断するまでの時間を秒単位で指定します。
       これはキャッシュされた接続の有効期間として働きます。
      </para>
+     <para>
+      このキャッシュを保持するプロセスに接続中のクライアントがある場合は、その接続が終了するまで<varname>connection_life_time</varname>の有効期間が来たかどうかの計算は行われません。
+      したがって、このパラメータの設定値よりも長時間キャッシュされたコネクションが保持されることがあり得ます。
+      これを避けたい場合は、<xref linkend="guc-client-idle-limit">を短めに設定することをお勧めします。
+     </para>
      <para>
       <!--
       The default is 0, which means the cached connections will not be disconnected.
diff --git a/doc/src/sgml/connection-pooling.sgml b/doc/src/sgml/connection-pooling.sgml
index daa84c3f7..3301bd4a9 100644
--- a/doc/src/sgml/connection-pooling.sgml
+++ b/doc/src/sgml/connection-pooling.sgml
@@ -281,10 +281,20 @@
     <listitem>
      <para>
       Specifies the time in seconds to terminate the cached connections
-      to the PostgreSQL backend. This serves as the cached connection expiration time.
+      to the <productname>PostgreSQL</> backend. This serves as the cached connection expiration time.
      </para>
      <para>
-      The default is 0, which means the cached connections will not be disconnected.
+      If a client connects to the process which holds the cached
+      connections, a calculation on
+      the <varname>connection_life_time</varname> is not performed
+      until the client disconnects. Thus it is possible that the cached
+      connections are kept for longer time than this value. To avoid
+      this, it is recommended to set shorter value
+      to <xref linkend="guc-client-idle-limit">.
+     </para>
+     <para>
+      The default is 0, which means the cached connections will not be
+      disconnected.
      </para>
      <para>
       This parameter can only be set at server start.
-- 
2.39.5