Re: Documentation Suggestion
On 2022-Apr-28, David G. Johnston wrote: > But we don't go out of our way anywhere else to be so explicit about this > kind of requirement and don't see a point of making this instance an > exception. Maybe we could add a in the Options section before the item list, along the lines of "be mindful that arguments to options --auth, --auth-local, --encoding, --locale (and all --lc-* options) are case-sensitive". (The point here, I suppose, is that LDAP being an acronym is typically spelled uppercase, so our use of lowercase is a bit odd.) Maybe there are other places where this is relevant as well? > The page could use a hyperlink/cross-reference to the pg_hba.conf > documentation. That's easily fixed. How about the attached patch? -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "El destino baraja y nosotros jugamos" (A. Schopenhauer) >From ad7baac914aa306ac419d3b76495b45958df0e85 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Fri, 29 Apr 2022 10:55:43 +0200 Subject: [PATCH] case-sensitivity note in initdb --- doc/src/sgml/ref/initdb.sgml | 18 -- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index c9ffaaecfb..0d75f7e0ec 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -137,6 +137,13 @@ PostgreSQL documentation Options + +Be mindful that arguments to options --auth, +--auth-local, --encoding, +--locale (and all --lc-* options) are +case-sensitive. + + @@ -146,7 +153,12 @@ PostgreSQL documentation This option specifies the default authentication method for local users used in pg_hba.conf (host -and local lines). initdb will +and local lines). See +for an overview of valid values. + + + +initdb will prepopulate pg_hba.conf entries using the specified authentication method for non-replication as well as replication connections. @@ -176,7 +188,8 @@ PostgreSQL documentation This option specifies the authentication method for local users via Unix-domain socket connections used in pg_hba.conf -(local lines). +(local lines). See +for an overview of valid values. @@ -575,6 +588,7 @@ PostgreSQL documentation + -- 2.30.2
Re: Documentation Suggestion
On 29.04.22 11:09, Alvaro Herrera wrote: + +Be mindful that arguments to options --auth, +--auth-local, --encoding, +--locale (and all --lc-* options) are +case-sensitive. + Almost all arguments of command-line options of all PostgreSQL tools are case-sensitive. Consider the initdb -U option for example. By pointing out a couple of specific cases, wouldn't we also create more confusion about options not mentioned? (I'm not sure about the case-sensitivity of the locale options. That could be OS-dependent.)
Re: Documentation Suggestion
Alvaro Herrera writes: > On 2022-Apr-28, David G. Johnston wrote: >> But we don't go out of our way anywhere else to be so explicit about this >> kind of requirement and don't see a point of making this instance an >> exception. > Maybe we could add a in the Options section before the item list, > along the lines of "be mindful that arguments to options --auth, > --auth-local, --encoding, --locale (and all --lc-* options) are > case-sensitive". I don't think this is an improvement, mainly for the reason David mentions: why wouldn't you need a similar statement on every single one of our program man pages? >> The page could use a hyperlink/cross-reference to the pg_hba.conf >> documentation. > That's easily fixed. How about the attached patch? That part's OK, but personally I'd only have cited the link once. regards, tom lane
Re: Documentation Suggestion
On Fri, Apr 29, 2022 at 7:07 AM Tom Lane wrote: > Alvaro Herrera writes: > > On 2022-Apr-28, David G. Johnston wrote: > > >> The page could use a hyperlink/cross-reference to the pg_hba.conf > >> documentation. > > > That's easily fixed. How about the attached patch? > > That part's OK, but personally I'd only have cited the link once. > > Agreed, one or three, including the local-only option but ignoring the host-only one seems like a mistake. I would just document the -A/--auth-method option, the other two are close enough in space to borrow it just fine. Shall we do a return link from the pg_hba.conf to initdb? The first paragraph already has: "A default pg_hba.conf file is installed when the data directory is initialized by initdb." David J.
