v1-0001-doc-Reword-pg_ident.conf-explanation-surrounding-reg.patch

From 093ba8ec49060501c3930c45d9b3c1ba0669a536 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <David.G.Johnston@Gmail.com>
Date: Wed, 9 Jul 2025 11:30:07 -0700
Subject: [PATCH] doc: Reword pg_ident.conf explanation surrounding regexp

Remove redundancy introduced by giving system-username and
database-username their own paragraphs.  This also allows a clean
way to state that our behavior pertaining to capturing the first
group in system-username regexp and referring to it in a non-regexp
database-username.  Emphasize this later requirement with an example
and a warning.
---
 doc/src/sgml/client-auth.sgml | 44 ++++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 832b616a7bb..53bb2ef7ed3 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -999,37 +999,39 @@ local   db1,db2,@demodbs  all                                   md5
    <literal>+</literal> lose its special meaning.
   </para>
   <para>
-   If the <replaceable>system-username</replaceable> field starts with a slash (<literal>/</literal>),
-   the remainder of the field is treated as a regular expression.
-   (See <xref linkend="posix-syntax-details"/> for details of
-   <productname>PostgreSQL</productname>'s regular expression syntax.)  The regular
-   expression can include a single capture, or parenthesized subexpression,
-   which can then be referenced in the <replaceable>database-username</replaceable>
-   field as <literal>\1</literal> (backslash-one).  This allows the mapping of
-   multiple user names in a single line, which is particularly useful for
-   simple syntax substitutions.  For example, these entries
+   Both <replaceable>system-username</replaceable> and <replaceable>database-username</replaceable>
+   can be specified using regular expressions by beginning the value with a slash
+   <literal>/</literal> (See <xref linkend="posix-syntax-details"/> for details of
+   <productname>PostgreSQL</productname>'s regular expression syntax).
+   Of particular note is the capturing group and back reference feature; where
+   parentheses capture actual matched text and can be referred to using \m.
+   In the special case where the <replaceable>system-username</replaceable>
+   field is a regular expression with at least one capturing group, and, importantly,
+   the <replaceable>database-username</replaceable> field is not a regular expression,
+   the first capturing group in <replaceable>system-username</replaceable> can
+   be referenced a single time within the <replaceable>database-username</replaceable>
+   field using <literal>\1</literal>. For example, these first two entries
 <programlisting>
 mymap   /^(.*)@mydomain\.com$      \1
 mymap   /^(.*)@otherdomain\.com$   guest
+# mymap /^(.*)@example\.com$       /^\1-(example|other)$  # Invalid RegExp!
 </programlisting>
    will remove the domain part for users with system user names that end with
    <literal>@mydomain.com</literal>, and allow any user whose system name ends with
    <literal>@otherdomain.com</literal> to log in as <literal>guest</literal>.
-   Quoting a <replaceable>database-username</replaceable> containing
+   Note that quoting a <replaceable>database-username</replaceable> containing
    <literal>\1</literal> <emphasis>does not</emphasis> make
    <literal>\1</literal> lose its special meaning.
   </para>
-  <para>
-   If the <replaceable>database-username</replaceable> field starts with
-   a slash (<literal>/</literal>), the remainder of the field is treated
-   as a regular expression (see <xref linkend="posix-syntax-details"/>
-   for details of <productname>PostgreSQL</productname>'s regular
-   expression syntax). It is not possible to use <literal>\1</literal>
-   to use a capture from regular expression on
-   <replaceable>system-username</replaceable> for a regular expression
-   on <replaceable>database-username</replaceable>.
-  </para>
-
+  <warning>
+   <para>
+    The commented-out third example above has an invalid regular expression which
+    will cause the pg_ident.conf file to fail to load.  The problem is that within
+    a regular expression the <literal>\1</literal> reference will always refer to
+    the context of the expression itself, and in this case at the point
+    <literal>\1</literal> is used no capturing groups have been matched.
+   </para>
+  </warning>
   <tip>
    <para>
     Keep in mind that by default, a regular expression can match just part of
-- 
2.34.1