From 093ba8ec49060501c3930c45d9b3c1ba0669a536 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" 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 + lose its special meaning. - If the system-username field starts with a slash (/), - the remainder of the field is treated as a regular expression. - (See for details of - PostgreSQL's regular expression syntax.) The regular - expression can include a single capture, or parenthesized subexpression, - which can then be referenced in the database-username - field as \1 (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 system-username and database-username + can be specified using regular expressions by beginning the value with a slash + / (See for details of + PostgreSQL'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 system-username + field is a regular expression with at least one capturing group, and, importantly, + the database-username field is not a regular expression, + the first capturing group in system-username can + be referenced a single time within the database-username + field using \1. For example, these first two entries mymap /^(.*)@mydomain\.com$ \1 mymap /^(.*)@otherdomain\.com$ guest +# mymap /^(.*)@example\.com$ /^\1-(example|other)$ # Invalid RegExp! will remove the domain part for users with system user names that end with @mydomain.com, and allow any user whose system name ends with @otherdomain.com to log in as guest. - Quoting a database-username containing + Note that quoting a database-username containing \1 does not make \1 lose its special meaning. - - If the database-username field starts with - a slash (/), the remainder of the field is treated - as a regular expression (see - 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. - - + + + 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 \1 reference will always refer to + the context of the expression itself, and in this case at the point + \1 is used no capturing groups have been matched. + + Keep in mind that by default, a regular expression can match just part of -- 2.34.1