correction suggestion for https://www.postgresql.org/docs/17/auth-username-maps.html

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.

"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

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.

"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

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

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.

"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