Thread: doc: Fix description of how the default user name is chosen
Hi.
Reposting this on its own thread.
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
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.
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 indicated user name was not found.
The other changes simply try to avoid the issue altogether.
David J.
Attachment
"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:
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 justfinished 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.
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.
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>
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>
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?
Attachment
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