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

"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

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.

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

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.

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

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

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

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.

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

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.

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?

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