On Wed, Jul 9, 2025 at 9:22 AM Tom Lane <t...@sss.pgh.pa.us> wrote:
> "David G. Johnston" <david.g.johns...@gmail.com> writes:
> > On Wed, Jul 9, 2025 at 7:56 AM PG Doc comments form <
> nore...@postgresql.org>
> > wrote:
> >> Pls. let me suggest the correction for the
> >> https://www.postgresql.org/docs/17/auth-username-maps.html page.
> >> It has the following sentence:
>
> The existing sentence is pretty mangled English, though.
>
Agreed.
> When the database-username field is a regular expression, it is
> not possible to use \1 within it to refer to a capture from
> the system-username field.
>
> Thoughts?
>
Its good as far a narrow fix goes.
But how about the attached? More invasive but covers the salient points
better, IMO, and less repetitive than having the two fields have their own
basically copy-pasted paragraphs.
I didn't add an example but felt the point "be referenced a single time
within" to be needed since, usefulness not withstanding, writing \1\1 for
database-username works but only the first instance of \1 is replaced.
Also, should we attempt to align this documentation and
pg_ident.conf.sample as pertains to pg-username vs. database-username?
David J.
From 093ba8ec49060501c3930c45d9b3c1ba0669a536 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@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
