Обсуждение: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/17/auth-username-maps.html
Description:

Dear all,
Pls. let me suggest the correction for the
https://www.postgresql.org/docs/17/auth-username-maps.html page.
It has the following sentence:
'
If the database-username field starts with a slash (/), the remainder of the
field is treated as a regular expression (see Section 9.7.3.1 for details of
PostgreSQL's regular expression syntax). It is not possible to use \1 to use
a capture from regular expression on system-username for a regular
expression on database-username.
'
It looks like 'to use a capture' has to be replaced by 'to capture'.
best regards
Alexey Shishkin

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Wed, Jul 9, 2025 at 7:56 AM PG Doc comments form <noreply@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:
>> '
>> If the database-username field starts with a slash (/), the remainder of
>> the
>> field is treated as a regular expression (see Section 9.7.3.1 for details
>> of
>> PostgreSQL's regular expression syntax). It is not possible to use \1 to
>> use
>> a capture from regular expression on system-username for a regular
>> expression on database-username.
>> '
>> It looks like 'to use a capture' has to be replaced by 'to capture'.
>> best regards

> What is written is factually correct.  Your suggestion makes it
> incorrect; and wouldn't be good English even if it was.

The existing sentence is pretty mangled English, though.  I think
it would be clearer as

  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?

            regards, tom lane

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> 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.

Meh... I initially thought that merging the two paras sounded like a
good idea, but I'm not finding that this formulation reads any better.
Notably, as things stand we have parallel constructions 
"If the <field> starts with an <x> character" in the preceding para as
well as these two, and I think it's good to keep that parallelism.
I do agree that it's overly repetitive, but we could improve that by
dropping the second instance of the parenthetical link to
posix-syntax-details.

> 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.

Hmm, I wonder if that isn't a bug we should fix.  It's hard to believe
anyone is relying on the second \1 *not* getting replaced, and perhaps
there are use-cases for multiple replacements.

> Also, should we attempt to align this documentation and
> pg_ident.conf.sample as pertains to pg-username vs. database-username?

Agreed that making pg_ident.conf.sample match would be an improvement.

            regards, tom lane

I wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
>> 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.

> Hmm, I wonder if that isn't a bug we should fix.  It's hard to believe
> anyone is relying on the second \1 *not* getting replaced, and perhaps
> there are use-cases for multiple replacements.

Here's a quick patch for that.  I hacked up 003_peer.pl enough to
prove that multiple replacement works, but that test change is not
committable as-is because it assumes that the "system user" name
is "postgres".  I don't like the existing test much either, since it
only tests the case of the substituted string being empty, which
means the substitution code could be quite broken and it wouldn't
notice.  But I don't offhand see a way to improve that without
making assumptions about the incoming name...

            regards, tom lane

diff --git a/src/backend/libpq/hba.c b/src/backend/libpq/hba.c
index 332fad27835..fecee8224d0 100644
--- a/src/backend/libpq/hba.c
+++ b/src/backend/libpq/hba.c
@@ -2873,8 +2873,11 @@ check_ident_usermap(IdentLine *identLine, const char *usermap_name,
             !token_has_regexp(identLine->pg_user) &&
             (ofs = strstr(identLine->pg_user->string, "\\1")) != NULL)
         {
+            const char *repl_str;
+            size_t        repl_len;
+            char       *old_pg_user;
             char       *expanded_pg_user;
-            int            offset;
+            size_t        offset;

             /* substitution of the first argument requested */
             if (matches[1].rm_so < 0)
@@ -2886,18 +2889,33 @@ check_ident_usermap(IdentLine *identLine, const char *usermap_name,
                 *error_p = true;
                 return;
             }
+            repl_str = system_user + matches[1].rm_so;
+            repl_len = matches[1].rm_eo - matches[1].rm_so;

             /*
-             * length: original length minus length of \1 plus length of match
-             * plus null terminator
+             * It's allowed to have more than one \1 in the string, and we'll
+             * replace them all.  But that's pretty unusual so we optimize on
+             * the assumption of only one occurrence, which motivates doing
+             * repeated replacements instead of making two passes over the
+             * string to determine the final length right away.
              */
-            expanded_pg_user = palloc0(strlen(identLine->pg_user->string) - 2 + (matches[1].rm_eo - matches[1].rm_so)
+1); 
-            offset = ofs - identLine->pg_user->string;
-            memcpy(expanded_pg_user, identLine->pg_user->string, offset);
-            memcpy(expanded_pg_user + offset,
-                   system_user + matches[1].rm_so,
-                   matches[1].rm_eo - matches[1].rm_so);
-            strcat(expanded_pg_user, ofs + 2);
+            old_pg_user = identLine->pg_user->string;
+            do
+            {
+                /*
+                 * length: current length minus length of \1 plus length of
+                 * replacement plus null terminator
+                 */
+                expanded_pg_user = palloc(strlen(old_pg_user) - 2 + repl_len + 1);
+                /* ofs points into the old_pg_user string at this point */
+                offset = ofs - old_pg_user;
+                memcpy(expanded_pg_user, old_pg_user, offset);
+                memcpy(expanded_pg_user + offset, repl_str, repl_len);
+                strcpy(expanded_pg_user + offset + repl_len, ofs + 2);
+                if (old_pg_user != identLine->pg_user->string)
+                    pfree(old_pg_user);
+                old_pg_user = expanded_pg_user;
+            } while ((ofs = strstr(old_pg_user + offset + repl_len, "\\1")) != NULL);

             /*
              * Mark the token as quoted, so it will only be compared literally
diff --git a/src/test/authentication/t/003_peer.pl b/src/test/authentication/t/003_peer.pl
index f2320b62c87..8a9431e5594 100644
--- a/src/test/authentication/t/003_peer.pl
+++ b/src/test/authentication/t/003_peer.pl
@@ -93,6 +93,8 @@ if ($node->log_contains(
 $node->safe_psql('postgres', qq{CREATE ROLE testmapuser LOGIN});
 $node->safe_psql('postgres', "CREATE ROLE testmapgroup NOLOGIN");
 $node->safe_psql('postgres', "GRANT testmapgroup TO testmapuser");
+# This role is for testing \1 substitution.
+$node->safe_psql('postgres', qq{CREATE ROLE testgresgresmapuser LOGIN});
 # Note the double quotes here.
 $node->safe_psql('postgres', 'CREATE ROLE "testmapgroupliteral\\1" LOGIN');
 $node->safe_psql('postgres', 'GRANT "testmapgroupliteral\\1" TO testmapuser');
@@ -212,10 +214,10 @@ test_role(

 # Success as the regular expression matches and \1 is replaced in the given
 # subexpression.
-reset_pg_ident($node, 'mypeermap', qq{/^$system_user(.*)\$}, 'test\1mapuser');
+reset_pg_ident($node, 'mypeermap', qq{/^post(.*)\$}, 'test\1\1mapuser');
 test_role(
     $node,
-    qq{testmapuser},
+    qq{testgresgresmapuser},
     'peer',
     0,
     'with regular expression in user name map with \1 replaced',

I figured out how to make the 003_peer.pl tests for \1 less
hacky, and pushed that.  Here's a proposed patch for the
documentation side of things, including your suggestion to
make pg_ident.conf.sample match up better.

            regards, tom lane

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 832b616a7bb..51b95ed04f3 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1003,8 +1003,9 @@ local   db1,db2,@demodbs  all                                   md5
    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>
+   expression can include a single capture, or parenthesized subexpression.
+   The portion of the system user name that matched the capture 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
@@ -1022,12 +1023,11 @@ mymap   /^(.*)@otherdomain\.com$   guest
   <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>.
+   as a regular expression.
+   When the <replaceable>database-username</replaceable> field is a regular
+   expression, it is not possible to use <literal>\1</literal> within it to
+   refer to a capture from the <replaceable>system-username</replaceable>
+   field.
   </para>

   <tip>
diff --git a/src/backend/libpq/pg_ident.conf.sample b/src/backend/libpq/pg_ident.conf.sample
index f5225f26cdf..8ee6c0ba315 100644
--- a/src/backend/libpq/pg_ident.conf.sample
+++ b/src/backend/libpq/pg_ident.conf.sample
@@ -13,25 +13,25 @@
 # user names to their corresponding PostgreSQL user names.  Records
 # are of the form:
 #
-# MAPNAME  SYSTEM-USERNAME  PG-USERNAME
+# MAPNAME  SYSTEM-USERNAME  DATABASE-USERNAME
 #
 # (The uppercase quantities must be replaced by actual values.)
 #
 # MAPNAME is the (otherwise freely chosen) map name that was used in
 # pg_hba.conf.  SYSTEM-USERNAME is the detected user name of the
-# client.  PG-USERNAME is the requested PostgreSQL user name.  The
-# existence of a record specifies that SYSTEM-USERNAME may connect as
-# PG-USERNAME.
+# client.  DATABASE-USERNAME is the requested PostgreSQL user name.
+# The existence of a record specifies that SYSTEM-USERNAME may connect
+# as DATABASE-USERNAME.
 #
-# If SYSTEM-USERNAME starts with a slash (/), it will be treated as a
-# regular expression.  Optionally this can contain a capture (a
-# parenthesized subexpression).  The substring matching the capture
-# will be substituted for \1 (backslash-one) if present in
-# PG-USERNAME.
+# If SYSTEM-USERNAME starts with a slash (/), the rest of it will be
+# treated as a regular expression.  Optionally this can contain a capture
+# (a parenthesized subexpression).  The substring matching the capture
+# will be substituted for \1 (backslash-one) if that appears in
+# DATABASE-USERNAME.
 #
-# PG-USERNAME can be "all", a user name, a group name prefixed with "+", or
-# a regular expression (if it starts with a slash (/)).  If it is a regular
-# expression, the substring matching with \1 has no effect.
+# DATABASE-USERNAME can be "all", a user name, a group name prefixed with "+",
+# or a regular expression (if it starts with a slash (/)).  If it is a regular
+# expression, no substitution for \1 will occur.
 #
 # Multiple maps may be specified in this file and used by pg_hba.conf.
 #
@@ -69,4 +69,4 @@
 # Put your actual configuration here
 # ----------------------------------

-# MAPNAME       SYSTEM-USERNAME         PG-USERNAME
+# MAPNAME       SYSTEM-USERNAME         DATABASE-USERNAME

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> (Likewise, the system-username regexp can contain more than one capture -
> which are only available later in the system-username regexp - though again
> it seems unlikely anyone is going to use that feature in this context.)

Yeah, I was thinking about that while working on the multiple-\1
patch.  Sooner or later somebody is going to ask why they can't
use \2, \3, etc in the database-username.  I think it would be a
pretty minor finger exercise to make the new code do that, but
I refrained for now.

> I'm good with this.

Cool.  I'll push after the beta2 release freeze lifts.

            regards, tom lane