Horton

Thread

Commits

  1. Add link to HBA docs in initdb --auth documentation

  2. Add link to initdb in pg_hba.conf docs

  1. Documentation Suggestion

    The Post Office <noreply@postgresql.org> — 2022-04-28T19:11:18Z

    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.

  2. Re: Documentation Suggestion

    David G. Johnston <david.g.johnston@gmail.com> — 2022-04-28T20:15:34Z

    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.

  3. Re: Documentation Suggestion

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2022-04-29T09:09:14Z

    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)

  4. Re: Documentation Suggestion

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-04-29T09:52:45Z

    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.)

  5. Re: Documentation Suggestion

    Tom Lane <tgl@sss.pgh.pa.us> — 2022-04-29T14:06:57Z

    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

  6. Re: Documentation Suggestion

    David G. Johnston <david.g.johnston@gmail.com> — 2022-04-29T15:05:36Z

    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.

  7. Re: Documentation Suggestion

    Bruce Momjian <bruce@momjian.us> — 2022-05-13T18:41:39Z

    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

  8. Re: Documentation Suggestion

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2022-05-14T15:21:58Z

    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)

  9. Re: Documentation Suggestion

    Bruce Momjian <bruce@momjian.us> — 2022-05-24T12:36:18Z

    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

  10. Re: Documentation Suggestion

    Bruce Momjian <bruce@momjian.us> — 2022-07-14T22:23:43Z

    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

  11. Re: Documentation Suggestion

    Bruce Momjian <bruce@momjian.us> — 2022-07-21T17:58:54Z

    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

  12. Re: Documentation Suggestion

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2022-07-21T18:05:49Z

    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/

  13. Re: Documentation Suggestion

    Bruce Momjian <bruce@momjian.us> — 2022-07-21T18:43:31Z

    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