Обсуждение: Bug in psql
In psql 17.2, if I do \? it says...
\dE[S+] [PATTERN] list foreign tables
\des[+] [PATTERN] list foreign servers
\det[+] [PATTERN] list foreign tables
\des[+] [PATTERN] list foreign servers
\det[+] [PATTERN] list foreign tables
notice the duplicate.
If I do \dES+, it is titled "list of relations"... whatever that means. It seems to be another list of foreign tables but with a different format. None of the other options have the same name in the help text, but different output. I'm not sure what the aim was here.
I also kind of feel like the name in the help text should always be the name you actually get. So for example, \ddS is described in help as "show object descriptions not displayed elsewhere" (BTW, why is this one "show" and the others are "list"), whereas the output is merely "object descriptions".
Most things in help are described as "list of... " and are titled on output "List of... " but it's not consistent. e.g. \dl is in help "list large objects", but on output is merely "large objects",
Some are just wildly different, like \dp has help of "list table, view and sequence access privileges" but on output is just "access privileges" (and no "list of" again). And if I do \di "list indexes" the output is titled "List of relations". \dL is "list procedural languages" but on output is "list of languages". \dv in help is "list views" but on output is "List of relations".
Chris
On Thu, 2025-01-30 at 06:56 +0800, Chris BSomething wrote: > [description of various inconsistencies in the documentation of psql metacommands] Slight differences can be explained by the fact that PostgreSQL is written by many people. Is there anything that is actually wrong or confusing? If yes, do you have a suggestion how to improve it? Yours, Laurenz Albe
Isn't it obvious? Two help items with the same help description doesn't tell you which one you need. And if you saved the output of a list... blah blah, then recalling help with \?, you won't be told necessarily how to run blah blah list, because the names of the lists and the help are different. If I saw somewhere on the web, the output of psql entitled "List of relations" which command would run that, given that a dozen or so commands are titled "List of relations", even though they are not that at all.
Chris
On Thu, 30 Jan 2025 at 15:54, Laurenz Albe <laurenz.albe@cybertec.at> wrote:
On Thu, 2025-01-30 at 06:56 +0800, Chris BSomething wrote:
> [description of various inconsistencies in the documentation of psql metacommands]
Slight differences can be explained by the fact that PostgreSQL is
written by many people. Is there anything that is actually wrong
or confusing? If yes, do you have a suggestion how to improve it?
Yours,
Laurenz Albe
On Wed, Jan 29, 2025 at 3:56 PM Chris BSomething <xpusostomos@gmail.com> wrote:
In psql 17.2, if I do \? it says...\dE[S+] [PATTERN] list foreign tables
\des[+] [PATTERN] list foreign servers
\det[+] [PATTERN] list foreign tablesnotice the duplicate.If I do \dES+, it is titled "list of relations"... whatever that means.
Relations are a super-class of table-things. There are many subtypes of relations. \d Lists relations of all subtypes. You can also add a single letter to \d to limit the listing to only the subtype-specific relations. That is what the E is doing here.
It seems to be another list of foreign tables but with a different format.
Since \d can only show information limited to the super-class relation, and not specific subtypes, the information for the foreign table subtype needs to be made available somewhere. That place is \det
I also kind of feel like the name in the help text should always be the name you actually get. So for example, \ddS is described in help as "show object descriptions not displayed elsewhere" (BTW, why is this one "show" and the others are "list"), whereas the output is merely "object descriptions".
This kind of review of consistency doesn't really get treated like a bug report in most cases. It makes for a decent technical writing R&D project for someone interested in putting in the effort.
David J.
On Mon, 3 Feb 2025 at 04:36, David G. Johnston <david.g.johnston@gmail.com> wrote:
Relations are a super-class of table-things. There are many subtypes of relations. \d Lists relations of all subtypes. You can also add a single letter to \d to limit the listing to only the subtype-specific relations. That is what the E is doing here.
That's an obtuse answer. If everything is "a table thing", why even bother printing a title? Normally, select() doesn't show a title, so if you're just going to dump data to the screen with misleading titles, why bother with a garbage title? And how is \di, list indexes "table things"? You can't select from an index, so for users they're not relations.
It seems to be another list of foreign tables but with a different format.Since \d can only show information limited to the super-class relation, and not specific subtypes, the information for the foreign table subtype needs to be made available somewhere. That place is \det
I don't know what that means, but when two menu items have the same text, but a different function, Houston, we have a problem.
I also kind of feel like the name in the help text should always be the name you actually get. So for example, \ddS is described in help as "show object descriptions not displayed elsewhere" (BTW, why is this one "show" and the others are "list"), whereas the output is merely "object descriptions".This kind of review of consistency doesn't really get treated like a bug report in most cases. It makes for a decent technical writing R&D project for someone interested in putting in the effort.
It's not technical writing, it's part of the program. As much a part of the program as any menu in a gui program, or window title in a gui program.
On Sun, Feb 2, 2025 at 5:30 PM Chris BSomething <xpusostomos@gmail.com> wrote:
On Mon, 3 Feb 2025 at 04:36, David G. Johnston <david.g.johnston@gmail.com> wrote:Relations are a super-class of table-things. There are many subtypes of relations. \d Lists relations of all subtypes. You can also add a single letter to \d to limit the listing to only the subtype-specific relations. That is what the E is doing here.That's an obtuse answer. If everything is "a table thing", why even bother printing a title? Normally, select() doesn't show a title, so if you're just going to dump data to the screen with misleading titles, why bother with a garbage title? And how is \di, list indexes "table things"? You can't select from an index, so for users they're not relations.
You can quibble with our definitions but they probably aren't going to change (and a bug report isn't the best place to try anyway). The glossary says:
Relation
The generic term for all objects in a database that have a name and a list of attributes defined in a specific order. Tables, sequences, views, foreign tables, materialized views, composite types, and indexes are all relations.
More generically, a relation is a set of tuples; for example, the result of a query is also a relation.
And the design methodology given extends from that.
It seems to be another list of foreign tables but with a different format.Since \d can only show information limited to the super-class relation, and not specific subtypes, the information for the foreign table subtype needs to be made available somewhere. That place is \detI don't know what that means, but when two menu items have the same text, but a different function, Houston, we have a problem.
I agree with this premise. It's still a matter of R&D to find the violation and fix them - without confounding things with also tryIng to declassify indexes as relations.
David J.
Chris BSomething <xpusostomos@gmail.com> writes:
> On Mon, 3 Feb 2025 at 04:36, David G. Johnston <david.g.johnston@gmail.com>
> wrote:
>> Since \d can only show information limited to the super-class relation,
>> and not specific subtypes, the information for the foreign table subtype
>> needs to be made available somewhere. That place is \det
> I don't know what that means, but when two menu items have the same text,
> but a different function, Houston, we have a problem.
It could be argued that at the level of detail that's possible in this
help summary, their functions *are* the same. The family of commands
that includes \dE will show you Schema, Name, Type, Owner, which are
properties that all relations have so they are sensible to show in a
list that might include any type of relation. On the other hand,
\det shows Schema, Table, Server (and \det+ includes FDW options),
so it is only applicable to foreign tables. But we don't have the
space in \h output to go into the specific output columns. That's
pretty much left to the user to discover by trying things.
Having said that, if you have concrete ideas about how to make the
help output clearer, let's hear them. (I'm pretty sure we've
rearranged \h's explanation of the \dtisv family before, so it's
not like this text is set in stone.) But "this is a bug and
somebody else should fix it" is not going to cause anything to
happen, mainly because it's not very clear what would be better.
regards, tom lane
On Mon, 3 Feb 2025 at 10:12, David G. Johnston <david.g.johnston@gmail.com> wrote:
You can quibble with our definitions but they probably aren't going to change (and a bug report isn't the best place to try anyway). The glossary says:RelationThe generic term for all objects in a database that have a name and a list of attributes defined in a specific order. Tables, sequences, views, foreign tables, materialized views, composite types, and indexes are all relations.More generically, a relation is a set of tuples; for example, the result of a query is also a relation.
If an index is a set of tuples, there is no way for a user to see those tuples, know what attributes they have, know what order they're in, or what their contents are. One might surmise a hash index has hash values and a pointer to page tables, but that's all invisible to a user. An index does not fit the technical, mathematical or even the postgresql documented definition which says a relation is a "mathematical term for a table", and goes on to talk about how SQL queries relations, which you can't do on an index.
And even if indexes were relations, \di putting output saying "List of relations", at best it would be SOME relations, and therefore still wrong. And yet \dS manages the amazing feat of saying "Index..." if we're talking about an index.... it doesn't attempt to befuddle you by calling it a relation, like \di does.
But if you think this is great, why not change the help text to have 20 commands to "list relations", since they're all relations apparently, and informing the user beyond that is apparently overkill.
And the design methodology given extends from that.
What design methodology? Sounds like your understanding of pgsql internal design is leaking into the user interface.
I agree with this premise. It's still a matter of R&D to find the violation and fix them - without confounding things with also tryIng to declassify indexes as relations.
Who exactly in user land is edified by referring to indexes as relations?
On Mon, 3 Feb 2025 at 10:35, Tom Lane <tgl@sss.pgh.pa.us> wrote:
It could be argued that at the level of detail that's possible in this
help summary, their functions *are* the same. The family of commands
that includes \dE will show you Schema, Name, Type, Owner, which are
properties that all relations have so they are sensible to show in a
list that might include any type of relation. On the other hand,
\det shows Schema, Table, Server (and \det+ includes FDW options),
so it is only applicable to foreign tables. But we don't have the
space in \h output to go into the specific output columns. That's
pretty much left to the user to discover by trying things.
If I hired a programmer, and he couldn't write 2 functions because he couldn't think up 2 different names for similar, and yet different functions, I would fire him. Sounds like one is "list foreign tables (basic info)" and one is "list foreign tables (foreign info)" or some such. Surely it's not beyond a moderately talented person to come up with something. More time has already been expended arguing pedantic points than would take to fix it.
On 2025-Feb-03, Chris BSomething wrote: > Surely it's not beyond a moderately talented person to come up with > something. Please submit a patch or a mock-up that we can discuss. Also, if you have better ideas for glossary definitions, let's hear them. The current definitions are not set in stone. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
Chris BSomething <xpusostomos@gmail.com> writes:
> Who exactly in user land is edified by referring to indexes as relations?
They're relations because they have pg_class and pg_attribute entries.
If the system catalogs were something that no user ever looked at,
maybe this would not matter; but that's not how business is done with
Postgres.
They're also relations because they have storage. (Admittedly, there
are relations that don't have storage, like views.) If we didn't
collect everything with storage under the term "relation", we'd need
some other term whenever we want to talk about physical files.
> Surely
> it's not beyond a moderately talented person to come up with something.
The trick is to come up with something that will garner a consensus
that it's an improvement. As mentioned already, feel free to make
a concrete proposal. Don't expect that somebody else will.
regards, tom lane
On Wed, Jan 29, 2025 at 5:56 PM Chris BSomething <xpusostomos@gmail.com> wrote:
...
And if I do \di "list indexes" the output is titled "List of relations".
This one in particular has been nagging at me for quite a while, so I was inspired to make a patch.
See:
FWIW, I'm sympathetic to some of your other concerns, but have no plans to tackle them. :)
Cheers,
Greg
My patch was just committed by Tom (who did most of the work, thank you Tom!). So now you should see much less of "List of relations" in future versions of psql (which is backwards compatible!)
About your changes:
- /* If tabtypes is empty, we default to \dtvmsE (but see also command.c) */
+ /* If tabtypes is empty, we default to \dtivmsE (but see also command.c) */
This was not an oversight: \d defaults to all types EXCEPT indexes, on purpose.
+ if (showViews) {
+ if (cntTitle != 0) {
+ strcat(title, ", ");
+ }
+ strcat(title, "views");
+ cntTitle++;
+ }
+ if (cntTitle != 0) {
+ strcat(title, ", ");
+ }
+ strcat(title, "views");
+ cntTitle++;
+ }
...
See discussion on my patch about why we cannot do this for translation reasons. Well, we can do it, but we'd be asking the translators to either handle around 64 new strings, or to forcibly accept some assumptions about how their language should work.
- HELP0(" \\dE[Sx+] [PATTERN] list foreign tables\n");
+ HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");
HELP0(" \\des[x+] [PATTERN] list foreign servers\n");
- HELP0(" \\det[x+] [PATTERN] list foreign tables\n");
+ HELP0(" \\dE[Sx+] [PATTERN] list foreign tables (basic info)\n");
+ HELP0(" \\det[x+] [PATTERN] list foreign tables (foreign info)\n");
HELP0(" \\deu[x+] [PATTERN] list user mappings\n");
- HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");
+ HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");
HELP0(" \\des[x+] [PATTERN] list foreign servers\n");
- HELP0(" \\det[x+] [PATTERN] list foreign tables\n");
+ HELP0(" \\dE[Sx+] [PATTERN] list foreign tables (basic info)\n");
+ HELP0(" \\det[x+] [PATTERN] list foreign tables (foreign info)\n");
HELP0(" \\deu[x+] [PATTERN] list user mappings\n");
- HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");
I like this part, it's definitely an improvement.
Cheers,
Greg
On Thu, 6 Feb 2025 at 04:09, Greg Sabino Mullane <htamfids@gmail.com> wrote:
My patch was just committed by Tom (who did most of the work, thank you Tom!). So now you should see much less of "List+ if (showViews) {
+ if (cntTitle != 0) {
+ strcat(title, ", ");
+ }
+ strcat(title, "views");
+ cntTitle++;
+ }...See discussion on my patch about why we cannot do this for translation reasons. Well, we can do it, but we'd be asking the translators to either handle around 64 new strings, or to forcibly accept some assumptions about how their language should work.
Yes, I see. Although one might argue that translating individual words is good enough in this case.
Better to have just "tables, indexes, views" with no language specific grammar than give up. Though I think any language can cope well enough with "list tables" or "tables list" without having their grammar sensibilities offended.
And I've got to imagine that relations as a mathematical technical term doesn't really translate anyway. Let alone explaining in Chinese why an index is a relation.
- HELP0(" \\dE[Sx+] [PATTERN] list foreign tables\n");
+ HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");
HELP0(" \\des[x+] [PATTERN] list foreign servers\n");
- HELP0(" \\det[x+] [PATTERN] list foreign tables\n");
+ HELP0(" \\dE[Sx+] [PATTERN] list foreign tables (basic info)\n");
+ HELP0(" \\det[x+] [PATTERN] list foreign tables (foreign info)\n");
HELP0(" \\deu[x+] [PATTERN] list user mappings\n");
- HELP0(" \\dew[x+] [PATTERN] list foreign-data wrappers\n");I like this part, it's definitely an improvement.Cheers,Greg