Thread: Documentation Suggestion
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/11/app-initdb.html Description: Reference: https://www.postgresql.org/docs/11/app-initdb.html When installing recently I found the "-A " option of the initdb command only accepts lowercase argument. For example "-A LDAP" is not valid and must be "-A ldap" otherwise the following error is returned: initdb: invalid authentication method "LDAP" for "local" connections It may be worth adding a note to the above documentation that states all option values must be specified in lowercase.
On Thu, Apr 28, 2022 at 12:36 PM PG Doc comments form <noreply@postgresql.org> wrote:
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/11/app-initdb.html
Description:
Reference: https://www.postgresql.org/docs/11/app-initdb.html
When installing recently I found the "-A " option of the initdb command only
accepts lowercase argument. For example "-A LDAP" is not valid and must be
"-A ldap" otherwise the following error is returned:
initdb: invalid authentication method "LDAP" for "local" connections
It may be worth adding a note to the above documentation that states all
option values must be specified in lowercase.
The -A option will accept any of the option names that are specified in the documentation for pg_hba.conf
It just so happens that all of those names, at present, consist of all lower-case characters.
That matching is case-sensitive is not specifically stated but is the default unless otherwise stated.
The page could use a hyperlink/cross-reference to the pg_hba.conf documentation.
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.
David J.
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 <para> 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)
Attachment
On 29.04.22 11:09, Alvaro Herrera wrote: > + <para> > + Be mindful that arguments to options <option>--auth</option>, > + <option>--auth-local</option>, <option>--encoding</option>, > + <option>--locale</option> (and all <option>--lc-*</option> options) are > + case-sensitive. > + </para> 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.)
Alvaro Herrera <alvherre@alvh.no-ip.org> 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 <para> 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
On Fri, Apr 29, 2022 at 7:07 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Alvaro Herrera <alvherre@alvh.no-ip.org> 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.
On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote:
> Alvaro Herrera <alvherre@alvh.no-ip.org> 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 <para> 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?
I think the confusion is that while the option arguments are
case-sensitive, many of the values are typically used as all upper-case,
and I think any doc mention would have to include that:
Note that valid --auth option values are all lower case, even
for authentication types that typically appear as all upper case,
e.g., "LDAP".
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
I pushed the other suggested bits. On 2022-May-13, Bruce Momjian wrote: > On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote: > > 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? > > I think the confusion is that while the option arguments are > case-sensitive, many of the values are typically used as all upper-case, > and I think any doc mention would have to include that: > > Note that valid --auth option values are all lower case, even > for authentication types that typically appear as all upper case, > e.g., "LDAP". Yeah, that was my initial thought too. The case-sensitivity is a consideration for other things too (such as locale or encoding names), but for those we do match the operating system name exactly, rather than using our own lower-case version of it, which nobody else uses. So really the point is not about the fact that it is case sensitive as that the case of our name doesn't match the usual one. Maybe the note should be "Note that authentication types are all lower case, [even for ...]" or something like that. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "I can see support will not be a problem. 10 out of 10." (Simon Wittber) (http://archives.postgresql.org/pgsql-general/2004-12/msg00159.php)
fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote: > I pushed the other suggested bits. > > On 2022-May-13, Bruce Momjian wrote: > > > On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote: > > > > 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? > > > > I think the confusion is that while the option arguments are > > case-sensitive, many of the values are typically used as all upper-case, > > and I think any doc mention would have to include that: > > > > Note that valid --auth option values are all lower case, even > > for authentication types that typically appear as all upper case, > > e.g., "LDAP". > > Yeah, that was my initial thought too. The case-sensitivity is a > consideration for other things too (such as locale or encoding names), > but for those we do match the operating system name exactly, rather than > using our own lower-case version of it, which nobody else uses. > > So really the point is not about the fact that it is case sensitive as > that the case of our name doesn't match the usual one. Maybe the note > should be "Note that authentication types are all lower case, [even for > ...]" or something like that. Agreed. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
On Tue, May 24, 2022 at 08:36:18AM -0400, Bruce Momjian wrote: > fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote: > > On 2022-May-13, Bruce Momjian wrote: > > > Note that valid --auth option values are all lower case, even > > > for authentication types that typically appear as all upper case, > > > e.g., "LDAP". > > > > Yeah, that was my initial thought too. The case-sensitivity is a > > consideration for other things too (such as locale or encoding names), > > but for those we do match the operating system name exactly, rather than > > using our own lower-case version of it, which nobody else uses. > > > > So really the point is not about the fact that it is case sensitive as > > that the case of our name doesn't match the usual one. Maybe the note > > should be "Note that authentication types are all lower case, [even for > > ...]" or something like that. Here is a patch that implements this. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
Attachment
On Thu, Jul 14, 2022 at 06:23:43PM -0400, Bruce Momjian wrote: > On Tue, May 24, 2022 at 08:36:18AM -0400, Bruce Momjian wrote: > > fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote: > > > On 2022-May-13, Bruce Momjian wrote: > > > > Note that valid --auth option values are all lower case, even > > > > for authentication types that typically appear as all upper case, > > > > e.g., "LDAP". > > > > > > Yeah, that was my initial thought too. The case-sensitivity is a > > > consideration for other things too (such as locale or encoding names), > > > but for those we do match the operating system name exactly, rather than > > > using our own lower-case version of it, which nobody else uses. > > > > > > So really the point is not about the fact that it is case sensitive as > > > that the case of our name doesn't match the usual one. Maybe the note > > > should be "Note that authentication types are all lower case, [even for > > > ...]" or something like that. > > Here is a patch that implements this. Patch applied to all supported branches. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
On 2022-Jul-21, Bruce Momjian wrote: > Patch applied to all supported branches. Thanks, looks good. I notice you credited me as the reporter, but actually the reporter is jhebert@micron.com. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
On Thu, Jul 21, 2022 at 08:05:49PM +0200, Álvaro Herrera wrote: > On 2022-Jul-21, Bruce Momjian wrote: > > > Patch applied to all supported branches. > > Thanks, looks good. > > I notice you credited me as the reporter, but actually the reporter is > jhebert@micron.com. Oh, my apologies. I had not kept the first email and didn't notice the "Re:". -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson