agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedcorrection suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
9+ messages / 3 participants
[nested] [flat]
* correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
@ 2025-07-09 12:06 PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: PG Doc comments form @ 2025-07-09 12:06 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: alexey.shishkin@enterprisedb.com
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
@ 2025-07-09 15:15 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2025-07-09 15:15 UTC (permalink / raw)
To: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
On Wed, Jul 9, 2025 at 7:56 AM PG Doc comments form <noreply@postgresql.org>
wrote:
> 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
>
> What is written is factually correct. Your suggestion makes it
incorrect; and wouldn't be good English even if it was.
"to capture" involves (...) while using said capture involves \#
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
@ 2025-07-09 16:22 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2025-07-09 16:22 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
"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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
@ 2025-07-09 18:39 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2025-07-09 18:39 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
On Wed, Jul 9, 2025 at 9:22 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> "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:
>
> 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.
Attachments:
[text/x-patch] v1-0001-doc-Reword-pg_ident.conf-explanation-surrounding-reg.patch (4.5K, ../../CAKFQuwZu6kZ8ZPvJ3pWXig+6UX4nTVK-hdL_ZS3fSdps=RJQQQ@mail.gmail.com/3-v1-0001-doc-Reword-pg_ident.conf-explanation-surrounding-reg.patch)
download | inline diff:
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
@ 2025-07-09 19:30 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 22:05 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2025-07-09 19:30 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
"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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
@ 2025-07-09 22:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 18:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2025-07-09 22:05 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-diff] wip-allow-multiple-backslash-ones.patch (3.6K, ../../1409232.1752098746@sss.pgh.pa.us/2-wip-allow-multiple-backslash-ones.patch)
download | inline diff:
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',
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 22:05 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
@ 2025-07-13 18:30 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 19:27 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2025-07-13 18:30 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-diff] v2-0001-reword-pg_ident.conf-docs.patch (4.1K, ../../435403.1752431413@sss.pgh.pa.us/2-v2-0001-reword-pg_ident.conf-docs.patch)
download | inline diff:
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 22:05 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 18:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
@ 2025-07-13 19:27 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-13 19:49 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2025-07-13 19:27 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
On Sun, Jul 13, 2025 at 11:30 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 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.
>
>
Thanks. My goal of trying to be a bit more precise regarding the \1
reference is probably counter-productive. The existing wording makes me
ask "why" to which the answer is "because if database-username is a regexp
a reference to \1 resolves to any capturing groups it defines; and if there
are none the regexp will be malformed and break when you attempt to
reload pg_hba.conf". But that is a lot of words for something that is
unlikely to be encountered in practice and does distract the reader from
the main point.
(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.)
I'm good with this.
Thanks!
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 22:05 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 18:30 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 19:27 ` Re: correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html David G. Johnston <david.g.johnston@gmail.com>
@ 2025-07-13 19:49 ` Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 9+ messages in thread
From: Tom Lane @ 2025-07-13 19:49 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: alexey.shishkin@enterprisedb.com; pgsql-docs@lists.postgresql.org
"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
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2025-07-13 19:49 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-07-09 12:06 correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html PG Doc comments form <noreply@postgresql.org>
2025-07-09 15:15 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 16:22 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 18:39 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-09 19:30 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-09 22:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 18:30 ` Tom Lane <tgl@sss.pgh.pa.us>
2025-07-13 19:27 ` David G. Johnston <david.g.johnston@gmail.com>
2025-07-13 19:49 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox