Horton

Thread

Commits

  1. doc: Fix description of how the default user name is chosen

  1. doc: Fix description of how the default user name is chosen

    David G. Johnston <david.g.johnston@gmail.com> — 2022-06-09T15:55:07Z

    Hi.

Reposting this on its own thread.

https://www.postgresql.org/message-id/flat/CAKFQuwby1aMsJDMeibaBaohgoaZhivAo4WcqHC1%3D9-GDZ3TSng%40mail.gmail.com

    The default database name is just the user name, not the
    operating-system user name.

    In passing, the authentication error examples use the phrase
    "database user name" in a couple of locations.  The word
    database in both cases is both unusual and unnecessary for
    understanding.  The reference to user name means the one in/for the
    database unless otherwise specified.

    Furthermore, it seems better to tell the reader the likely
    reason why the displayed database name happens to be a user name.

This change is probably optional but I think it makes sense:
-    The indicated database user name was not found.
+    The indicated user name was not found.

The other changes simply try to avoid the issue altogether.

David J.

  2. Re: doc: Fix description of how the default user name is chosen

    Tom Lane <tgl@sss.pgh.pa.us> — 2022-07-06T00:20:25Z

    "David G. Johnston" <david.g.johnston@gmail.com> writes:
>     In passing, the authentication error examples use the phrase
>     "database user name" in a couple of locations.  The word
>     database in both cases is both unusual and unnecessary for
>     understanding.  The reference to user name means the one in/for the
>     database unless otherwise specified.

I'm not convinced that just saying "user name" is an improvement.
The thing that we are trying to clarify in much of this section
is the relationship between your operating-system-assigned user
name and your database-cluster-assigned user name.  So just saying
"user name" adds an undesirable element of ambiguity.

Maybe we could change "database user name" to "Postgres user name"?

-    if you do not specify a database name, it defaults to the database
-    user name, which might or might not be the right thing.
+    if the database name shown matches the user name you are connecting
+    as it is not by accident: the default database name is the
+    user name.

This does absolutely not seem like an improvement.

     Since the database server uses the same default, you will not have
     to specify the port in most cases. The default user name is your
-    operating-system user name, as is the default database name.
+    operating-system user name. The default database name is the resolved user name.

I agree this phrasing needs some work, but "resolved" doesn't seem
helpful, since it's not defined here or nearby.  Maybe "The default
database name is the specified (or defaulted) user name." ?

			regards, tom lane

  3. Re: doc: Fix description of how the default user name is chosen

    David G. Johnston <david.g.johnston@gmail.com> — 2022-07-06T00:43:19Z

    On Tue, Jul 5, 2022 at 5:20 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> >     In passing, the authentication error examples use the phrase
> >     "database user name" in a couple of locations.  The word
> >     database in both cases is both unusual and unnecessary for
> >     understanding.  The reference to user name means the one in/for the
> >     database unless otherwise specified.
>
> I'm not convinced that just saying "user name" is an improvement.
> The thing that we are trying to clarify in much of this section
> is the relationship between your operating-system-assigned user
> name and your database-cluster-assigned user name.  So just saying
> "user name" adds an undesirable element of ambiguity.


> Maybe we could change "database user name" to "Postgres user name"?
>

I'm fine with just leaving "database user name" as no one seems to have the
same qualm with it that I do.  Besides, I just finished reading:

https://www.postgresql.org/docs/current/client-authentication.html

and it seems pointless to leave that written as-is and gripe about the
specific change I was recommending.

>
> -    if you do not specify a database name, it defaults to the database
> -    user name, which might or might not be the right thing.
> +    if the database name shown matches the user name you are connecting
> +    as it is not by accident: the default database name is the
> +    user name.
>
> This does absolutely not seem like an improvement.
>

In that case I don't see the need for any form of commentary beyond:

"If you do not specify a database name it defaults to the database user
name."


>      Since the database server uses the same default, you will not have
>      to specify the port in most cases. The default user name is your
> -    operating-system user name, as is the default database name.
> +    operating-system user name. The default database name is the resolved
> user name.
>
> I agree this phrasing needs some work, but "resolved" doesn't seem
> helpful, since it's not defined here or nearby.  Maybe "The default
> database name is the specified (or defaulted) user name." ?
>
>
"The default database name is the specified (or defaulted) database user
name."

I'll accept that "specified (or defaulted)" is simply another way to write
what I understand to be the common meaning of "resolved" in this situation.

David J.

  4. Re: doc: Fix description of how the default user name is chosen

    Matthias van de Meent <boekewurm+postgres@gmail.com> — 2022-07-06T12:30:57Z

    On Wed, 6 Jul 2022 at 02:43, David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Tue, Jul 5, 2022 at 5:20 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>> "David G. Johnston" <david.g.johnston@gmail.com> writes:
>> >     In passing, the authentication error examples use the phrase
>> >     "database user name" in a couple of locations.  The word
>> >     database in both cases is both unusual and unnecessary for
>> >     understanding.  The reference to user name means the one in/for the
>> >     database unless otherwise specified.
>>
>> I'm not convinced that just saying "user name" is an improvement.
>> The thing that we are trying to clarify in much of this section
>> is the relationship between your operating-system-assigned user
>> name and your database-cluster-assigned user name.  So just saying
>> "user name" adds an undesirable element of ambiguity.
>>
>>
>> Maybe we could change "database user name" to "Postgres user name"?
>
>
> I'm fine with just leaving "database user name" as no one seems to have the same qualm with it that I do.  Besides, I just finished reading:
>
> https://www.postgresql.org/docs/current/client-authentication.html
>
> and it seems pointless to leave that written as-is and gripe about the specific change I was recommending.

If we're going to change this anyway, could we replace 'user name'
with 'username' in the connection documentation? It irks me to see so
much 'user name' while our connection parameter is 'username', and we
use the username of the OS user, not the OS user's (display) name - or
at least, that's how it behaved under Linux last time I checked.

>>
>>
>> -    if you do not specify a database name, it defaults to the database
>> -    user name, which might or might not be the right thing.
>> +    if the database name shown matches the user name you are connecting
>> +    as it is not by accident: the default database name is the
>> +    user name.
>>
>> This does absolutely not seem like an improvement.
>
>
> In that case I don't see the need for any form of commentary beyond:
>
> "If you do not specify a database name it defaults to the database user name."

Agreed to both.
The right-ness of the default can either be systematic ("we should or
should not default to connection username instead of some other
default") or in context of connection establishment ("this connection
should or should not connect to the database named after the user's
username").
The right-ness of the systematic default doesn't matter in this
context (that's something to put in the comments of that code or
discuss on -hackers), and the right-ness of the contextual default was
already proven to be wrong in this configuration of server and client,
by the context of failing to connect to that defaulted database.

Kind regards,

Matthias van de Meent

  5. Re: doc: Fix description of how the default user name is chosen

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-07-06T12:37:05Z

    On 06.07.22 14:30, Matthias van de Meent wrote:
> If we're going to change this anyway, could we replace 'user name'
> with 'username' in the connection documentation? It irks me to see so
> much 'user name' while our connection parameter is 'username', and we
> use the username of the OS user, not the OS user's (display) name - or
> at least, that's how it behaved under Linux last time I checked.

This might make sense if you are referring specifically to the value of 
that connection option, and you mark it up accordingly.  Otherwise, the 
subtlety might get lost.

  6. Re: doc: Fix description of how the default user name is chosen

    Bruce Momjian <bruce@momjian.us> — 2022-07-09T01:54:35Z

    On Tue, Jul  5, 2022 at 08:20:25PM -0400, Tom Lane wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> >     In passing, the authentication error examples use the phrase
> >     "database user name" in a couple of locations.  The word
> >     database in both cases is both unusual and unnecessary for
> >     understanding.  The reference to user name means the one in/for the
> >     database unless otherwise specified.
> 
> I'm not convinced that just saying "user name" is an improvement.
> The thing that we are trying to clarify in much of this section
> is the relationship between your operating-system-assigned user
> name and your database-cluster-assigned user name.  So just saying
> "user name" adds an undesirable element of ambiguity.
> 
> Maybe we could change "database user name" to "Postgres user name"?
> 
> -    if you do not specify a database name, it defaults to the database
> -    user name, which might or might not be the right thing.
> +    if the database name shown matches the user name you are connecting
> +    as it is not by accident: the default database name is the
> +    user name.
> 
> This does absolutely not seem like an improvement.
> 
>      Since the database server uses the same default, you will not have
>      to specify the port in most cases. The default user name is your
> -    operating-system user name, as is the default database name.
> +    operating-system user name. The default database name is the resolved user name.
> 
> I agree this phrasing needs some work, but "resolved" doesn't seem
> helpful, since it's not defined here or nearby.  Maybe "The default
> database name is the specified (or defaulted) user name." ?

I am not seeing much improvement in the proposed patch either.  I wonder
if we should be calling this the "session" or "connection" user name. 
When the docs say "if you do not specify a database name, it defaults to
the database user name", there is so much "database in there that the
meaing is unclear, and in this context, the user name is a property of
the connection or session, not of the database.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

  7. Re: doc: Fix description of how the default user name is chosen

    Tom Lane <tgl@sss.pgh.pa.us> — 2022-07-09T02:17:11Z

    Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Jul  5, 2022 at 08:20:25PM -0400, Tom Lane wrote:
>> I agree this phrasing needs some work, but "resolved" doesn't seem
>> helpful, since it's not defined here or nearby.  Maybe "The default
>> database name is the specified (or defaulted) user name." ?

> I am not seeing much improvement in the proposed patch either.  I wonder
> if we should be calling this the "session" or "connection" user name. 
> When the docs say "if you do not specify a database name, it defaults to
> the database user name", there is so much "database in there that the
> meaing is unclear, and in this context, the user name is a property of
> the connection or session, not of the database.

Umm ... you could make the exact same statement with respect to the
user's operating-system login session, so I doubt that "session" or
"connection" adds any clarity.

			regards, tom lane

  8. Re: doc: Fix description of how the default user name is chosen

    Bruce Momjian <bruce@momjian.us> — 2022-07-09T02:42:58Z

    On Fri, Jul  8, 2022 at 10:17:11PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Tue, Jul  5, 2022 at 08:20:25PM -0400, Tom Lane wrote:
> >> I agree this phrasing needs some work, but "resolved" doesn't seem
> >> helpful, since it's not defined here or nearby.  Maybe "The default
> >> database name is the specified (or defaulted) user name." ?
> 
> > I am not seeing much improvement in the proposed patch either.  I wonder
> > if we should be calling this the "session" or "connection" user name. 
> > When the docs say "if you do not specify a database name, it defaults to
> > the database user name", there is so much "database in there that the
> > meaing is unclear, and in this context, the user name is a property of
> > the connection or session, not of the database.
> 
> Umm ... you could make the exact same statement with respect to the
> user's operating-system login session, so I doubt that "session" or
> "connection" adds any clarity.

Well, one confusion is that there is a database name and a database user
name.  We don't have different operating system names that users can
connect to, usually.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

  9. Re: doc: Fix description of how the default user name is chosen

    David G. Johnston <david.g.johnston@gmail.com> — 2022-07-09T15:06:21Z

    On Friday, July 8, 2022, Bruce Momjian <bruce@momjian.us> wrote:

> On Fri, Jul  8, 2022 at 10:17:11PM -0400, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > On Tue, Jul  5, 2022 at 08:20:25PM -0400, Tom Lane wrote:
> > >> I agree this phrasing needs some work, but "resolved" doesn't seem
> > >> helpful, since it's not defined here or nearby.  Maybe "The default
> > >> database name is the specified (or defaulted) user name." ?
> >
> > > I am not seeing much improvement in the proposed patch either.  I
> wonder
> > > if we should be calling this the "session" or "connection" user name.
> > > When the docs say "if you do not specify a database name, it defaults
> to
> > > the database user name", there is so much "database in there that the
> > > meaing is unclear, and in this context, the user name is a property of
> > > the connection or session, not of the database.
> >
> > Umm ... you could make the exact same statement with respect to the
> > user's operating-system login session, so I doubt that "session" or
> > "connection" adds any clarity.
>
> Well, one confusion is that there is a database name and a database user
> name.  We don't have different operating system names that users can
> connect to, usually.
>
>
Maybe invoke the wording from the libpq docs and say:

The default database name is the same as the user connection parameter.

https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS

That page doesn’t feel the need to qualify user name and I don’t think it
hurts comprehension; and the  writing “user parameter” there, instead of
“user name”, since the parameter is simply “user”, not “username”.

David J.

  10. Re: doc: Fix description of how the default user name is chosen

    Bruce Momjian <bruce@momjian.us> — 2022-07-09T15:15:58Z

    On Sat, Jul  9, 2022 at 08:06:21AM -0700, David G. Johnston wrote:
> Maybe invoke the wording from the libpq docs and say:
> 
> The default database name is the same as the user connection parameter.
> 
> https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
> 
> That page doesn’t feel the need to qualify user name and I don’t think it hurts
> comprehension; and the  writing “user parameter” there, instead of “user name”,
> since the parameter is simply “user”, not “username”.

Well, it could be the login OS name if the user connection parameter is
unspecified, right?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

  11. Re: doc: Fix description of how the default user name is chosen

    David G. Johnston <david.g.johnston@gmail.com> — 2022-07-09T15:52:46Z

    On Sat, Jul 9, 2022, 08:16 Bruce Momjian <bruce@momjian.us> wrote:

> On Sat, Jul  9, 2022 at 08:06:21AM -0700, David G. Johnston wrote:
> > Maybe invoke the wording from the libpq docs and say:
> >
> > The default database name is the same as the user connection parameter.
> >
> >
> https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
> >
> > That page doesn’t feel the need to qualify user name and I don’t think
> it hurts
> > comprehension; and the  writing “user parameter” there, instead of “user
> name”,
> > since the parameter is simply “user”, not “username”.
>
> Well, it could be the login OS name if the user connection parameter is
> unspecified, right?
>
>
No.  It is always the user parameter.  It just so happens that parameter
also has a default.  And so while there is a transitive aspect the
resolution of the user parameter happens first, using the OS user if
needed, then the dbname parameter is resolved using the user parameter if
needed to supply the default.

David J.

  12. Re: doc: Fix description of how the default user name is chosen

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-10-31T13:41:45Z

    On 09.07.22 17:52, David G. Johnston wrote:
> No.  It is always the user parameter.  It just so happens that parameter 
> also has a default.  And so while there is a transitive aspect the 
> resolution of the user parameter happens first, using the OS user if 
> needed, then the dbname parameter is resolved using the user parameter 
> if needed to supply the default.

Will there be an updated patch here?  The original patch contained three 
hunks; I'm not sure which one of those was intending to fix a real bug 
and which ones were cosmetic.  Is anything in the current documentation 
actually wrong?

  13. Re: doc: Fix description of how the default user name is chosen

    David G. Johnston <david.g.johnston@gmail.com> — 2022-11-01T21:31:04Z

    This is the only sentence I claim is factually incorrect, with a suggested
re-wording.

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 9494f28063..f375a0fc11 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -660,7 +660,8 @@ EOF
     determined at compile time.
     Since the database server uses the same default, you will not have
     to specify the port in most cases. The default user name is your
-    operating-system user name, as is the default database name.
+    operating-system user name. Once the user name is determined it is
+    used as the default database name.
     Note that you cannot
     just connect to any database under any user name. Your database
     administrator should have informed you about your access rights.

Oddly, this section is the only one where I'd want to say "database user
name" but it doesn't do that.  For consistency on that point, the following
chunk can be used instead (the attached diff does this):

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 9494f28063..38d12933ca 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -646,23 +646,23 @@ EOF
     <application>psql</application> is a regular
     <productname>PostgreSQL</productname> client application. In order
     to connect to a database you need to know the name of your target
-    database, the host name and port number of the server, and what user
-    name you want to connect as. <application>psql</application> can be
-    told about those parameters via command line options, namely
+    database, the host name and port number of the server, and what
+    database user name you want to connect as.
<application>psql</application>
+    can be told about those parameters via command line options, namely
     <option>-d</option>, <option>-h</option>, <option>-p</option>, and
     <option>-U</option> respectively. If an argument is found that does
     not belong to any option it will be interpreted as the database name
-    (or the user name, if the database name is already given). Not all
+    (or the database user name, if the database name is already given).
Not all
     of these options are required; there are useful defaults. If you omit
the host
     name, <application>psql</application> will connect via a Unix-domain
socket
     to a server on the local host, or via TCP/IP to
<literal>localhost</literal> on
-    Windows. The default port number is
-    determined at compile time.
+    Windows. The default port number is determined at compile time.
     Since the database server uses the same default, you will not have
-    to specify the port in most cases. The default user name is your
-    operating-system user name, as is the default database name.
+    to specify the port in most cases. The default database user name is
your
+    operating-system user name. Once the database user name is determined
it is
+    used as the default database name.
     Note that you cannot
-    just connect to any database under any user name. Your database
+    just connect to any database under any database user name. Your
database
     administrator should have informed you about your access rights.
     </para>

And removing the unnecessary commentary in client-auth.sgml

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 32d5d45863..5c6211809b 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -2255,7 +2255,7 @@ FATAL:  database "testdb" does not exist
 </programlisting>
     The database you are trying to connect to does not exist. Note that
     if you do not specify a database name, it defaults to the database
-    user name, which might or might not be the right thing.
+    user name.
    </para>

    <tip>

David J.




On Mon, Oct 31, 2022 at 6:41 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:

> On 09.07.22 17:52, David G. Johnston wrote:
> > No.  It is always the user parameter.  It just so happens that parameter
> > also has a default.  And so while there is a transitive aspect the
> > resolution of the user parameter happens first, using the OS user if
> > needed, then the dbname parameter is resolved using the user parameter
> > if needed to supply the default.
>
> Will there be an updated patch here?  The original patch contained three
> hunks; I'm not sure which one of those was intending to fix a real bug
> and which ones were cosmetic.  Is anything in the current documentation
> actually wrong?
>
>

  14. Re: doc: Fix description of how the default user name is chosen

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-11-24T08:11:31Z

    On 01.11.22 22:31, David G. Johnston wrote:
> This is the only sentence I claim is factually incorrect, with a 
> suggested re-wording.

committed