Re: describe-config issue

[vignesh C]

On Wed, Sep 2, 2020 at 8:06 PM Tom Lane  wrote:

> Please defend that claim.  Otherwise this seems like a pretty
> random change.

I had seen that there is discrepancy in postgres --describe-config & the
value displayed from pg_settings like in the below case:
postgres=# select name,min_val, max_val, boot_val,reset_val from
pg_settings where name = 'checkpoint_timeout';
name| min_val | max_val | *boot_val | reset_val*
+-+-+--+---
 checkpoint_timeout | 30  | 86400   | *300  | 300*
(1 row)

[vignesh@localhost bin]$ ./postgres --describe-config | grep
checkpoint_timeout
checkpoint_timeout sighup Write-Ahead Log / Checkpoints INTEGER *0 *30
86400 Sets the maximum time between automatic WAL checkpoints.

In the case of pg_settings we display 300 for boot_val/reset_val whereas in
the case of describe-config we display 0, shouldn't it be 300 here?
Thoughts?

 Regards,
Vignesh
EnterpriseDB: http://www.enterprisedb.com

Re: describe-config issue

[Tom Lane]

vignesh C  writes:
> Postgres's describe-config option prints reset_val for int & real
> configuration parameters which is not useful as it is not updated.

Uh, what?

> Printing boot_val is better in this case.

Please defend that claim.  Otherwise this seems like a pretty
random change.

regards, tom lane

Re: \describe*

[Alvaro Herrera]

On 2019-Aug-01, Corey Huinker wrote:

> From all this, I have so far concluded:
> 
> 1. There is real demand to be able to easily see the basic structure of
> tables, views, and indexes in a way that strikes a balance between detail
> and clutter.

That's great.  That said, I'm not opposed to a DESCRIBE server-side
command, and others have shown some interest too.  However, the thread
and commitfest entry at hand refer to a new psql command \describe,
which is completely unrelated.  So I suggest we should close this CF
entry as Returned with Feedback, and wait until Corey comes back with a
server-side patch for DESCRIBE.  I don't see the point of keeping a
\describe item alive if the patch we ultimately end up doing is
something completely different.

-- 
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: \describe*

[Corey Huinker]

>
> It seems this topic is ongoing so I've moved it to the September CF,
> but it's in "Waiting on Author" because we don't have a concrete patch
> that applies (or agreement on what it should do?) right now.
>

All recent work has been investigating the need(s) we're trying to address.
This is as good of a time as any to share my findings (with much
collaboration with Dave Fetter) so far.

1. Adding helper commands to psql aids only psql, and a great number of
users do not, or can not, use psql. So adding something on the server side
would have broader usage and appeal. Furthermore, some access tools
(especially browser-based ones) are not good about returning non-tabular
results, so helper commands that return result sets would have the broadest
usage.

2. Our own interest in server-side commands is all over the map. Some just
want the convenience of having them server side, or familiarity with
$OTHER_DB. Others want to eliminate the need for some code in pg_dump,
JDBC, or elsewhere.

3. There isn't much consensus in the other databases, though all of them do
*something*:

SQLServer
---

SQLServer has sp_help (
https://docs.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-help-transact-sql?view=sql-server-2017
 )

which contextually returns one of two different result sets (name, owner,
object type) or (column name, type, storage, length, precision, scale,
nullable, default, rule, collation)

DB2
--
Has a describe command (source:
https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.cmd.doc/doc/r0002019.html)
 which
can be used to describe query output (data type, data type length, column
name, column name length).

It also has an option to DESCRIBE TABLE foo which returns a set of
(col_name, schema_of_datatype, data_type, data_type_length,
data_type_scale, Nulls t/f)

It also has DESCRIBE INDEXES FOR TABLE foo which returns a set of (schema
of index, name of index, unique flag, number of columns, index type)

It also has DESCRIBE DATA PARTITIONS FOR TABLE which as you might guess
shows partitions.

All of these options have a SHOW DETAIL modifier which adds more columns.

MySQL
--

(https://dev.mysql.com/doc/refman/8.0/en/show-columns.html)
MySSQL has SHOW COLUMNS which also returns a set of  (name, type similar to
format_type(), null flag, PK or index indicator, default value, notes about
auto-increment/autogreneration/implicit trggers), and can be extended to
show privileges and comments with the EXTENDED and FULL options.

MySQL has a DESCRIBE command, but it is a synonym of EXPLAIN.

MySQL also has a raft of commands like SHOW CREATE USER, SHOW CREATE VIEW,
SHOW CREATE TRIGGER, SHOW CREATE TABLE, etc. (ex:
https://dev.mysql.com/doc/refman/8.0/en/show-create-user.html)  These
commands all return a result set of of exactly one column, each row
representing one SQL statement, essentially doing a single-object
schema-only pg_dump.

Oracle
-

https://docs.oracle.com/cd/B19306_01/server.102/b14357/ch12019.htm

SQL*Plus has a describe command that works on tables and views and
composite types (tabular set of: name, null, type) procedures (tabular set
of: arg name, type, in/out), and packages (a series of sets one per type
and procedure)

SQLcl has the INFO statement, which is roughly analogous to psql's \d in
that it is a mix of tabular and non-tabular information.

Oracle itself has dbms_metadata.get_ddl() which seems analogous to mysql's
SHOW CREATE commands.

Snowflake
--

Snowflake has DESCRIBE TABLE
https://docs.snowflake.net/manuals/sql-reference/sql/desc-table.html and
DESCRIBE VIEW
https://docs.snowflake.net/manuals/sql-reference/functions/get_ddl.html

Which return a set of: (name, type, column type, null flag, default,
primary key, unique key, check, expression, comment).

It also has an option for describing "stage" tables, which are s3 buckets
with a file format associated, the closest postgresql analog would be a
file_fdw foreign table, and there is a separate result set format for that.

Snowflake has no concept of indexes (it understands that there's things
called a unique keys, and it remembers that you said you wanted one, but
does nothing to enforce it), so no command for that.

These result sets are not composable in a query, however, they are stored
in the RESULT_SCAN cache, which means that you can run a describe, and then
immediately fetch the results of that command as if it was a table.

Snowflake also has a get_ddl() function
https://docs.snowflake.net/manuals/sql-reference/sql/desc-view.html which
is a one-column result set of statements to re-create the given object.


>From all this, I have so far concluded:

1. There is real demand to be able to easily see the basic structure of
tables, views, and indexes in a way that strikes a balance between detail
and clutter.
2. There is some acknowledgement that this data be useful if it was further
filtered through SQL, though only one vendor 

Re: \describe*

[Thomas Munro]

On Sun, Jun 23, 2019 at 7:34 AM Corey Huinker  wrote:
>> > So what is the uptake on implementing this at the server side, ie.
>> > DESCRIBE?
>>
>> I'm pretty skeptical of this idea, unless you are willing to throw
>> away at least one and possibly both of the following goals:

It seems this topic is ongoing so I've moved it to the September CF,
but it's in "Waiting on Author" because we don't have a concrete patch
that applies (or agreement on what it should do?) right now.

-- 
Thomas Munro
https://enterprisedb.com

Re: \describe*

[Corey Huinker]

>
> > So what is the uptake on implementing this at the server side, ie.
> > DESCRIBE?
>
> I'm pretty skeptical of this idea, unless you are willing to throw
> away at least one and possibly both of the following goals:
>
> 1. Compatibility with psql's existing \d behavior.
>

I don't think *compatibility* with the behavior should be a goal in itself.
Coverage of the majority of the use-cases is.

2. Usability of DESCRIBE for any purpose whatsoever other than emitting
> something that looks just like what psql prints.
>
> We've migrated many of the \d displays so far away from "a single query
> result" that I don't believe there's a way for a server command to
> duplicate them, at least not without some seriously unholy in-bed-ness
> between the server command and some postprocessing logic in describe.c.
> (At which point you've lost whatever system architectural value there
> might be in the whole project, since having a more-arm's-length
> relationship there kinda seems like the point to me.)
>

I think there's a genuine use for regular printed output, and there's also
a use for a query-able output. Maybe that queryable output is just a JSONB
output that the outer query can pick apart as it sees fit, and that would
handle the fact that the data often doesn't fit into a single query's
output.

Incidentally, I had need of this very functionality in Snowflake the other
day. The data dictionary there isn't capable of telling you which columns
are in a primary key, but that information is printed when you run
"DESCRIBE my_table".  The workaround is to run "DESCRIBE my_table" and then
make another query using a table function to recall the output of the last
query made in the session, and then filter that. Yeah, as a pattern it's
weird and sad, but it shows that there's are uses for something
DESCRIBE-ish on the server side.

So if we're going servier-side on DESCRIBE, it should be it's own entity,
not beholden to design decisions made in psql.


> There are a bunch of other little behavioral differences that you just
> can't replicate server-side, like the fact that localization of the
> results depends on psql's LC_MESSAGES not the server's.  Maybe people
> would be okay with changing that, but it's not a transparent
> reimplementation.
>

I think people would be OK with that. We're asking the server what it knows
about an object, not how psql feels about that same information.

I think if we want to have server-side describe capability, we're better
> off just to implement a DESCRIBE command that's not intended to be exactly
> like \d anything, and not try to make it be the implementation for \d
> anything.  (This was, in fact, where David started IIUC.  Other people's
> sniping at that idea hasn't yielded any better idea.)
>

I'm very much in support of server-side DESCRIBE that's not beholden to \d
in any way. For instance, I'm totally fine with DESCRIBE not being able to
handle wildcard patterns.

My initial suggestion for client-side \describe was mostly borne of it
being easy to implement a large subset of the \d commands to help users.
Not all users have psql access, so having a server side command helps more
people.

It could be that we decide that DESCRIBE is set-returning, and we have to
break up \d functionality to suit. By this I mean that we might find it
simpler to require DESCRIBE TABLE foo to only show columns with minimal
information about PKs and follow up commands like "DESCRIBE TABLE foo
INDEXES" or "DESCRIBE TABLE foo CONSTRAINTS" to keep output in tabular
format.


> In particular, I'm really strongly against having "\describe-foo-bar"
> invoke DESCRIBE, because (a) that will break compatibility with the
> existing \des command, and (b) it's not actually saving any typing,
> and (c) I think it'd confuse users no end.
>

+1. Having psql figure out which servers can give proper
servier-side-describes would boggle the mind.


> Of course, this line of thought does lead to the conclusion that we'd be
> maintaining psql/describe.c and server-side DESCRIBE in parallel forever,
>

Not fun, but what's our motivation for adding new new \d functionality once
a viable DESCRIBE is in place? Wouldn't the \d commands essentially be
feature-frozen at that point?


> which doesn't sound like fun.  But we should be making DESCRIBE with an
> eye to more use-cases than psql.  If it allows jdbc to not also maintain
> a pile of equivalent code, that'd be a win.  If it allows pg_dump to toss
> a bunch of logic overboard (or at least stop incrementally adding new
> variants), that'd be a big win.
>

I don't know enough about JDBC internals to know what sort of non-set
results it can handle, but that seems key to showing us how to proceed.

As for pg_dump, that same goal was a motivation for a similar server-side
command "SHOW CREATE " (essentially, pg_dump of ) which
would have basically the same design issues as DESCRIBE would, though the
result set would be a much simpler SETOF text.

Re: \describe*

[David Fetter]

On Fri, Jun 21, 2019 at 05:49:43PM -0400, Alvaro Herrera wrote:
> On 2019-Jun-21, David Fetter wrote:
> 
> > On Fri, Jun 21, 2019 at 05:20:54PM -0400, Alvaro Herrera wrote:
> > > On 2018-Jan-29, David Fetter wrote:
> > > 
> > > > We could certainly have \d call DESCRIBE for later versions of the
> > > > server.  \ commands which call different SQL depending on server
> > > > version have long been a standard practice.
> > > 
> > > So what is the uptake on implementing this at the server side, ie.
> > > DESCRIBE?
> > 
> > I've got a few Round Tuits available this weekend.  This seems like a
> > worthwhile thing to spend them on.
> 
> That's great, but my question is whether you managed to convince anyone
> whether it's a good idea.

Everybody who's used MySQL will.  In some sense, I'm more concerned
about the users in the future, who I hope vastly outnumber the users
in the present and past.

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[Tom Lane]

Alvaro Herrera  writes:
> On 2018-Jan-29, David Fetter wrote:
>> We could certainly have \d call DESCRIBE for later versions of the
>> server.  \ commands which call different SQL depending on server
>> version have long been a standard practice.

> So what is the uptake on implementing this at the server side, ie.
> DESCRIBE?

I'm pretty skeptical of this idea, unless you are willing to throw
away at least one and possibly both of the following goals:

1. Compatibility with psql's existing \d behavior.

2. Usability of DESCRIBE for any purpose whatsoever other than emitting
something that looks just like what psql prints.

We've migrated many of the \d displays so far away from "a single query
result" that I don't believe there's a way for a server command to
duplicate them, at least not without some seriously unholy in-bed-ness
between the server command and some postprocessing logic in describe.c.
(At which point you've lost whatever system architectural value there
might be in the whole project, since having a more-arm's-length
relationship there kinda seems like the point to me.)

There are a bunch of other little behavioral differences that you just
can't replicate server-side, like the fact that localization of the
results depends on psql's LC_MESSAGES not the server's.  Maybe people
would be okay with changing that, but it's not a transparent
reimplementation.

I think if we want to have server-side describe capability, we're better
off just to implement a DESCRIBE command that's not intended to be exactly
like \d anything, and not try to make it be the implementation for \d
anything.  (This was, in fact, where David started IIUC.  Other people's
sniping at that idea hasn't yielded any better idea.)

In particular, I'm really strongly against having "\describe-foo-bar"
invoke DESCRIBE, because (a) that will break compatibility with the
existing \des command, and (b) it's not actually saving any typing,
and (c) I think it'd confuse users no end.

Of course, this line of thought does lead to the conclusion that we'd be
maintaining psql/describe.c and server-side DESCRIBE in parallel forever,
which doesn't sound like fun.  But we should be making DESCRIBE with an
eye to more use-cases than psql.  If it allows jdbc to not also maintain
a pile of equivalent code, that'd be a win.  If it allows pg_dump to toss
a bunch of logic overboard (or at least stop incrementally adding new
variants), that'd be a big win.

regards, tom lane

Re: \describe*

[Alvaro Herrera]

On 2019-Jun-21, David Fetter wrote:

> On Fri, Jun 21, 2019 at 05:20:54PM -0400, Alvaro Herrera wrote:
> > On 2018-Jan-29, David Fetter wrote:
> > 
> > > We could certainly have \d call DESCRIBE for later versions of the
> > > server.  \ commands which call different SQL depending on server
> > > version have long been a standard practice.
> > 
> > So what is the uptake on implementing this at the server side, ie.
> > DESCRIBE?
> 
> I've got a few Round Tuits available this weekend.  This seems like a
> worthwhile thing to spend them on.

That's great, but my question is whether you managed to convince anyone
whether it's a good idea.

-- 
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: \describe*

[David Fetter]

On Fri, Jun 21, 2019 at 05:20:54PM -0400, Alvaro Herrera wrote:
> On 2018-Jan-29, David Fetter wrote:
> 
> > We could certainly have \d call DESCRIBE for later versions of the
> > server.  \ commands which call different SQL depending on server
> > version have long been a standard practice.
> 
> So what is the uptake on implementing this at the server side, ie.
> DESCRIBE?

I've got a few Round Tuits available this weekend.  This seems like a
worthwhile thing to spend them on.

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[Alvaro Herrera]

On 2018-Jan-29, David Fetter wrote:

> We could certainly have \d call DESCRIBE for later versions of the
> server.  \ commands which call different SQL depending on server
> version have long been a standard practice.

So what is the uptake on implementing this at the server side, ie.
DESCRIBE?

-- 
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: describe working as intended?

[Melanie Plageman]

On Sat, May 18, 2019 at 1:17 AM Sergei Kornilov  wrote:

> Hello
>
> No, this is not bug. This is expected beharior of search_path setting:
> https://www.postgresql.org/docs/current/runtime-config-client.html
>
> > Likewise, the current session's temporary-table schema, pg_temp_nnn, is
> always searched if it exists. It can be explicitly listed in the path by
> using the alias pg_temp. If it is not listed in the path then it is
> searched first
>
> psql \d command checks current search_path (by pg_table_is_visible call).
> You can use \d *.t1 syntax to display tables with such name in all schemas.
>
> regards, Sergei
>


Thanks! I suppose it would behoove me to check the documentation
before resorting to looking at the source code :)

-- 
Melanie Plageman

Re: describe working as intended?

[Sergei Kornilov]

Hello

No, this is not bug. This is expected beharior of search_path setting: 
https://www.postgresql.org/docs/current/runtime-config-client.html

> Likewise, the current session's temporary-table schema, pg_temp_nnn, is 
> always searched if it exists. It can be explicitly listed in the path by 
> using the alias pg_temp. If it is not listed in the path then it is searched 
> first

psql \d command checks current search_path (by pg_table_is_visible call). You 
can use \d *.t1 syntax to display tables with such name in all schemas.

regards, Sergei

Re: describe working as intended?

[Tom Lane]

Melanie Plageman  writes:
> So, I noticed that if I make a table in one schema and then a table with the
> same name in another schema that describe only shows me one of them.

Yes, that's intended, psql's \d will only show you tables that are
visible in the search path, unless you give it a qualified pattern.
You can do something like "\d *.t1" if you want to see all the
instances of t1.

This is documented I believe ... ah yes, here:

Whenever the pattern parameter is omitted completely, the \d commands
display all objects that are visible in the current schema search path
— this is equivalent to using * as the pattern. (An object is said to
be visible if its containing schema is in the search path and no
object of the same kind and name appears earlier in the search
path. This is equivalent to the statement that the object can be
referenced by name without explicit schema qualification.) To see all
objects in the database regardless of visibility, use *.* as the
pattern.
...
A pattern that contains a dot (.) is interpreted as a schema name
pattern followed by an object name pattern. For example, \dt
foo*.*bar* displays all tables whose table name includes bar that are
in schemas whose schema name starts with foo. When no dot appears,
then the pattern matches only objects that are visible in the current
schema search path. Again, a dot within double quotes loses its
special meaning and is matched literally.

regards, tom lane

Re: \describe*

[Pavel Stehule]

Hi


> Since this is now waiting for v13, there's a bit more time to entertain
> the question of whether we'd rather have these in psql or in a new server
> command DESCRIBE [verbose] [system], and if so, whether the output of that
> would itself be query-able or not.
>

Including this feature in core can be nice. If they are on server side,
then should to produce result via API - like EXPLAIN. That's all.

Regards

Pavel

Re: \describe*

[Corey Huinker]

On Mon, Mar 4, 2019 at 1:45 PM Corey Huinker 
wrote:

>
>>> - Tab completion for \descibe-verbose.
>>> I know that \d+ tab completion is also not there, but I think we must
>>> have tab completion for \descibe-verbose.
>>>
>>> postgres=# \describe-
>>> \describe-extension
>>>  \describe-replication-publication \describe-user-mapping
>>> \describe-foreign-data-wrapper
>>> \describe-replication-subscription\describe-view
>>> \describe-foreign-server  \describe-role
>>> \describe-window-function
>>> \describe-foreign-table   \describe-rule
>>>  ...
>>>
>>
> I just confirmed that there isn't tab completion for the existing S/+
> options, so it's hard to justify them for the equivalent verbose suffixes.
>

We can add completions for describe[-thing-]-verbose, but the
auto-completions start to run into combinatoric complexity, and the
original short-codes don't do that completion, probably for the same reason.

+   success =
>>> listTables("tvmsE", NULL, show_verbose, show_system);
>>> +   }
>>> +   status =
>>> PSQL_CMD_UNKNOWN;
>>>
>>>
> I'll look into this, thanks!
>

This was fixed, good find.



> - Confusion about \desc and \desC
>>> There is confusion while running the \desc command. I know the problem,
>>> but the user may confuse by this.
>>> postgres=# \desC
>>>List of foreign servers
>>>  Name | Owner | Foreign-data wrapper
>>> --+---+--
>>> (0 rows)
>>>
>>> postgres=# \desc
>>> Invalid command \desc. Try \? for help.
>>>
>>
I've changed the code to first strip out 0-1 instances of "-verbose" and
"-system" and the remaining string must be an exact match of a describe
command or it's an error. This same system could be applied to the short
commands to strip out 'S' and '+' and it might clean up the original code a
bit.

This command shows a list of relation "\d"
>>> postgres=# \describe-aggregatE-function
>>> List of relations
>>>  Schema | Name | Type  |  Owner
>>> +--+---+-
>>>  public | foo  | table | vagrant
>>> (1 row)
>>>
>>
Same issue, same fix.


>>> I have done a brief code review except for the documentation code. I
>>> don't like this code
>>>
>>> if (cmd_match(cmd,"describe-aggregate-function"))
>>>
>>>  success = describeAggregates(pattern, show_verbose, show_system);
>>>  else if (cmd_match(cmd,
>>> "describe-access-method"))
>>>  success =
>>> describeAccessMethods(pattern, show_verbose);
>>>  else if (cmd_match(cmd,
>>> "describe-tablespace"))
>>>  success = describeTablespaces(pattern,
>>> show_verbose);
>>>  else if (cmd_match(cmd,
>>> "describe-conversion"))
>>>  success = listConversions(pattern,
>>> show_verbose, show_system);
>>>  else if (cmd_match(cmd, "describe-cast"))
>>>  success = listCasts(pattern,
>>> show_verbose
>>>
>>>
>>> This can be achieved with the list/array/hash table, so I have changed
>>> that code in the attached patch just for a sample if you want I can do that
>>> for whole code.
>>>
>>
> There's some problems with a hash table. The function signatures vary
> quite a lot, and some require additional psql_scan_slash_options to be
> called. The hash option, if implemented, probably should be expanded to all
> slash commands, at which point maybe it belongs in psqlscanslash.l...
>

As I suspected, there's a lot of variance in the function signatures of the
various listSomething()/describeSomething() commands,
and listDbRoleSettings requires a second pattern to be scanned, and as far
as I know PsqlScanState isn't known inside describe.h, so building and
using a hash table would be a lot of work for uncertain gain. The original
code just plows through strings in alphabetical order, breaking things up
by comparing leading characters, so I largely did the same at the
des/decribe levels.

Instead of a hash table, It might be fun to write something that takes a
list of alphabetized strings, and builds a binary search tree at compile
time, but that would only work for the long form commands, the short forms
that allow filters like df[anptw]+ and d[tvmisE]+ effectively defeat any
attempt at hashing or btree-ing that I can presently imagine.

Having said that, here's v3 of the patch.

Since this is now waiting for v13, there's a bit more time to entertain the
question of whether we'd rather have these in psql or in a new server
command DESCRIBE [verbose] [system], and if so, whether the output of that
would itself be query-able or not.
From 6ff5ebd39a5bda3c2b398ac0b0062bd629f3c877 Mon Sep 17 00:00:00 2001
From: Corey Huinker 
Date: Fri, 8 Mar 2019 23:38:10 +

Re: Re: \describe*

[Corey Huinker]

>
>
> I agree with Andres and Robert.  This patch should be pushed to PG13.
>
> I'll do that on March 8 unless there is a compelling argument not to.
>
>
No objection. I'll continue to work on it, though.

Re: Re: \describe*

[David Steele]

On 2/25/19 9:44 PM, Robert Haas wrote:

On Sat, Feb 23, 2019 at 7:19 PM Andres Freund  wrote:

Sure, but it was late, and we have far more patches than we can deal
with. Many of them much much older than this.


More importantly, at least in my opinion, is that this is one of those
questions that people tend to have very strong feelings about.  Doing
something at the last minute risks people not feeling that they had an
adequate time to express those feelings before something got shipped.
Not everybody reads this list every day, or tests every new commit as
soon as it goes into the tree.


I agree with Andres and Robert.  This patch should be pushed to PG13.

I'll do that on March 8 unless there is a compelling argument not to.

Regards,
--
-David
da...@pgmasters.net

Re: \describe*

[Corey Huinker]

>
>
>> - Tab completion for \descibe-verbose.
>> I know that \d+ tab completion is also not there, but I think we must
>> have tab completion for \descibe-verbose.
>>
>> postgres=# \describe-
>> \describe-extension
>>  \describe-replication-publication \describe-user-mapping
>> \describe-foreign-data-wrapper
>> \describe-replication-subscription\describe-view
>> \describe-foreign-server  \describe-role
>>   \describe-window-function
>> \describe-foreign-table   \describe-rule
>>  ...
>>
>
I just confirmed that there isn't tab completion for the existing S/+
options, so it's hard to justify them for the equivalent verbose suffixes.



> (1 row)
>> Invalid command \describe. Try \? for help.
>>
>>
>> I think this status is causing the problem.
>>
>>
>>
>> +   /*
>> standard listing of interesting things */
>> +   success =
>> listTables("tvmsE", NULL, show_verbose, show_system);
>> +   }
>> +   status = PSQL_CMD_UNKNOWN;
>>
>>
I'll look into this, thanks!



> - Confusion about \desc and \desC
>> There is confusion while running the \desc command. I know the problem,
>> but the user may confuse by this.
>> postgres=# \desC
>>List of foreign servers
>>  Name | Owner | Foreign-data wrapper
>> --+---+--
>> (0 rows)
>>
>> postgres=# \desc
>> Invalid command \desc. Try \? for help.
>>
>> - Auto-completion of commands.
>> There is some more confusion in the completion of commands.
>>
>> This command shows List of aggregates.
>> postgres=# \describe-aggregate-function
>>  List of aggregate functions
>>  Schema | Name | Result data type | Argument data types | Description
>> +--+--+-+-
>> (0 rows)
>>
>>
>>
>> This command shows a list of relation "\d"
>> postgres=# \describe-aggregatE-function
>> List of relations
>>  Schema | Name | Type  |  Owner
>> +--+---+-
>>  public | foo  | table | vagrant
>> (1 row)
>>
>> This command also shows a list of relations "\d".
>> postgres=# \describe-aggr
>> List of relations
>>  Schema | Name | Type  |  Owner
>> +--+---+-
>>  public | foo  | table | vagrant
>> (1 row)
>>
>> This command shows error messages.
>> postgres=# \descr
>> Invalid command \descr. Try \? for help.
>>
>>
I will look into it.



>
>> I have done a brief code review except for the documentation code. I
>> don't like this code
>>
>> if (cmd_match(cmd,"describe-aggregate-function"))
>>
>>  success = describeAggregates(pattern, show_verbose, show_system);
>>  else if (cmd_match(cmd,
>> "describe-access-method"))
>>  success = describeAccessMethods(pattern,
>> show_verbose);
>>  else if (cmd_match(cmd,
>> "describe-tablespace"))
>>  success = describeTablespaces(pattern,
>> show_verbose);
>>  else if (cmd_match(cmd,
>> "describe-conversion"))
>>  success = listConversions(pattern,
>> show_verbose, show_system);
>>  else if (cmd_match(cmd, "describe-cast"))
>>  success = listCasts(pattern, show_verbose
>>
>>
>> This can be achieved with the list/array/hash table, so I have changed
>> that code in the attached patch just for a sample if you want I can do that
>> for whole code.
>>
>
There's some problems with a hash table. The function signatures vary quite
a lot, and some require additional psql_scan_slash_options to be called.
The hash option, if implemented, probably should be expanded to all slash
commands, at which point maybe it belongs in psqlscanslash.l...

>

Re: \describe*

[Ibrar Ahmed]

Hi Corey,

Here is the modified patch (sample).



On Mon, Mar 4, 2019 at 7:02 PM Ibrar Ahmed  wrote:

> The following review has been posted through the commitfest application:
> make installcheck-world:  not tested
> Implements feature:   not tested
> Spec compliant:   not tested
> Documentation:not tested
>
> Thanks for the patch, I have reviewed the patch and have some comments
> about the patch. The review includes the testing of the patch along with
> some code review.
>
> Here are my testings results,
>
> - Tab completion for \descibe-verbose.
> I know that \d+ tab completion is also not there, but I think we must have
> tab completion for \descibe-verbose.
>
> postgres=# \describe-
> \describe-extension
>  \describe-replication-publication \describe-user-mapping
> \describe-foreign-data-wrapper
> \describe-replication-subscription\describe-view
> \describe-foreign-server  \describe-role
>   \describe-window-function
> \describe-foreign-table   \describe-rule
>  ...
>
>
> - Error message in each command.
> There is an error message after each command, here is the example.
> postgres=# \describe
> List of relations
>  Schema | Name | Type  |  Owner
> +--+---+-
>  public | foo  | table | vagrant
>
> (1 row)
> Invalid command \describe. Try \? for help.
>
>
> I think this status is causing the problem.
>
>
>
> +   /*
> standard listing of interesting things */
> +   success =
> listTables("tvmsE", NULL, show_verbose, show_system);
> +   }
> +   status = PSQL_CMD_UNKNOWN;
>
>
>
>
> - Confusion about \desc and \desC
> There is confusion while running the \desc command. I know the problem,
> but the user may confuse by this.
> postgres=# \desC
>List of foreign servers
>  Name | Owner | Foreign-data wrapper
> --+---+--
> (0 rows)
>
> postgres=# \desc
> Invalid command \desc. Try \? for help.
>
> - Auto-completion of commands.
> There is some more confusion in the completion of commands.
>
> This command shows List of aggregates.
> postgres=# \describe-aggregate-function
>  List of aggregate functions
>  Schema | Name | Result data type | Argument data types | Description
> +--+--+-+-
> (0 rows)
>
>
>
> This command shows a list of relation "\d"
> postgres=# \describe-aggregatE-function
> List of relations
>  Schema | Name | Type  |  Owner
> +--+---+-
>  public | foo  | table | vagrant
> (1 row)
>
> This command also shows a list of relations "\d".
> postgres=# \describe-aggr
> List of relations
>  Schema | Name | Type  |  Owner
> +--+---+-
>  public | foo  | table | vagrant
> (1 row)
>
> This command shows error messages.
> postgres=# \descr
> Invalid command \descr. Try \? for help.
>
> ...
>
>
> Code review.
> -
>
> I have done a brief code review except for the documentation code. I don't
> like this code
>
> if (cmd_match(cmd,"describe-aggregate-function"))
>
>  success = describeAggregates(pattern, show_verbose, show_system);
>  else if (cmd_match(cmd,
> "describe-access-method"))
>  success = describeAccessMethods(pattern,
> show_verbose);
>  else if (cmd_match(cmd,
> "describe-tablespace"))
>  success = describeTablespaces(pattern,
> show_verbose);
>  else if (cmd_match(cmd,
> "describe-conversion"))
>  success = listConversions(pattern,
> show_verbose, show_system);
>  else if (cmd_match(cmd, "describe-cast"))
>  success = listCasts(pattern, show_verbose
>
>
> This can be achieved with the list/array/hash table, so I have changed
> that code in the attached patch just for a sample if you want I can do that
> for whole code.
>
> --
> Ibrar Ahmed
>
> The new status of this patch is: Waiting on Author
>


-- 
Ibrar Ahmed


0001-Add-describe-commands-to-compliment-d-commands-ibrar-v2.patch
Description: Binary data

Re: \describe*

[Ibrar Ahmed]

The following review has been posted through the commitfest application:
make installcheck-world:  not tested
Implements feature:   not tested
Spec compliant:   not tested
Documentation:not tested

Thanks for the patch, I have reviewed the patch and have some comments about 
the patch. The review includes the testing of the patch along with some code 
review. 

Here are my testings results, 

- Tab completion for \descibe-verbose.
I know that \d+ tab completion is also not there, but I think we must have tab 
completion for \descibe-verbose.

postgres=# \describe-
\describe-extension   \describe-replication-publication 
\describe-user-mapping
\describe-foreign-data-wrapper\describe-replication-subscription
\describe-view
\describe-foreign-server  \describe-role
\describe-window-function
\describe-foreign-table   \describe-rule  
 ...


- Error message in each command.
There is an error message after each command, here is the example. 
postgres=# \describe
List of relations
 Schema | Name | Type  |  Owner  
+--+---+-
 public | foo  | table | vagrant

(1 row)
Invalid command \describe. Try \? for help.


I think this status is causing the problem.



+   /* standard 
listing of interesting things */
+   success = 
listTables("tvmsE", NULL, show_verbose, show_system);
+   }
+   status = PSQL_CMD_UNKNOWN;




- Confusion about \desc and \desC
There is confusion while running the \desc command. I know the problem, but the 
user may confuse by this.
postgres=# \desC
   List of foreign servers
 Name | Owner | Foreign-data wrapper 
--+---+--
(0 rows)

postgres=# \desc
Invalid command \desc. Try \? for help.

- Auto-completion of commands.
There is some more confusion in the completion of commands. 

This command shows List of aggregates.
postgres=# \describe-aggregate-function 
 List of aggregate functions
 Schema | Name | Result data type | Argument data types | Description 
+--+--+-+-
(0 rows)



This command shows a list of relation "\d" 
postgres=# \describe-aggregatE-function 
List of relations
 Schema | Name | Type  |  Owner  
+--+---+-
 public | foo  | table | vagrant
(1 row)

This command also shows a list of relations "\d".
postgres=# \describe-aggr 
List of relations
 Schema | Name | Type  |  Owner  
+--+---+-
 public | foo  | table | vagrant
(1 row)

This command shows error messages.
postgres=# \descr
Invalid command \descr. Try \? for help.

...


Code review. 
-

I have done a brief code review except for the documentation code. I don't like 
this code 

if (cmd_match(cmd,"describe-aggregate-function"))   
 
 success = describeAggregates(pattern, show_verbose, show_system);
 else if (cmd_match(cmd, "describe-access-method"))
 success = describeAccessMethods(pattern, 
show_verbose);
 else if (cmd_match(cmd, "describe-tablespace"))
 success = describeTablespaces(pattern, 
show_verbose);
 else if (cmd_match(cmd, "describe-conversion"))
 success = listConversions(pattern, 
show_verbose, show_system);
 else if (cmd_match(cmd, "describe-cast"))
 success = listCasts(pattern, show_verbose


This can be achieved with the list/array/hash table, so I have changed that 
code in the attached patch just for a sample if you want I can do that for 
whole code.

-- 
Ibrar Ahmed

The new status of this patch is: Waiting on Author

Re: \describe*

[Robert Haas]

On Sat, Feb 23, 2019 at 7:19 PM Andres Freund  wrote:
> Sure, but it was late, and we have far more patches than we can deal
> with. Many of them much much older than this.

More importantly, at least in my opinion, is that this is one of those
questions that people tend to have very strong feelings about.  Doing
something at the last minute risks people not feeling that they had an
adequate time to express those feelings before something got shipped.
Not everybody reads this list every day, or tests every new commit as
soon as it goes into the tree.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Re: \describe*

[Andres Freund]

Hi,

On 2019-02-23 19:14:27 -0500, Corey Huinker wrote:
> >
> > Given that this patch has been added to the last commitfest for v12, I
> > think we should mark it as targeting 13, so it can be skipped over by
> > people looking to get things into v12.  Even leaving fairness aside, I
> > don't think it's likely to be ready quickly enough...
> >
> 
> Obviously this patch is nowhere near the importance of most patches slated
> for v12, but I would hope it can be considered, time permitting.
> 
> The size of the patch may look large (1036 lines), but 650+ of that is pure
> documentation changes, ~50 lines of added autocomplete strings, ~140 lines
> are added TailMatches calls (one per new autocomplete string), and what
> remains is strncmp() calls to match those same strings, so it's pretty mild
> in terms of impact.

Sure, but it was late, and we have far more patches than we can deal
with. Many of them much much older than this.

Greetings,

Andres Freund

Re: \describe*

[Corey Huinker]

>
> Given that this patch has been added to the last commitfest for v12, I
> think we should mark it as targeting 13, so it can be skipped over by
> people looking to get things into v12.  Even leaving fairness aside, I
> don't think it's likely to be ready quickly enough...
>

Obviously this patch is nowhere near the importance of most patches slated
for v12, but I would hope it can be considered, time permitting.

The size of the patch may look large (1036 lines), but 650+ of that is pure
documentation changes, ~50 lines of added autocomplete strings, ~140 lines
are added TailMatches calls (one per new autocomplete string), and what
remains is strncmp() calls to match those same strings, so it's pretty mild
in terms of impact.

Re: \describe*

[Andres Freund]

Hi,

On 2019-01-24 20:37:48 -0500, Corey Huinker wrote:
> Attached is a patch to add verbose \describe commands to compliment our
> existing but slightly cryptic family of \d commands.

Given that this patch has been added to the last commitfest for v12, I
think we should mark it as targeting 13, so it can be skipped over by
people looking to get things into v12.  Even leaving fairness aside, I
don't think it's likely to be ready quickly enough...

Greetings,

Andres Freund

Re: \describe*

[Corey Huinker]

Attached is a patch to add verbose \describe commands to compliment our
existing but slightly cryptic family of \d commands.

The goals of this are:
- aid user discovery of \d-commands via tab completion
- make scripts and snippets slightly more self-documenting and
understandable
- save experienced users that 0.22 seconds where they try to remember what
\dFpS+ means or which command lists user mappings.

DESIGN CHOICES:

Every new command is of the form
\describe-some-system-object-type[-system][-verbose]. The -system suffix
stands in for the 'S' suffix and -verbose stands in for '+'.

New commands used the singular form, not plural.

Every new command has a direct analog \d-command, but the reverse is not
always true, especially when it comes to the commands that can specify
multiple object types. In those cases, there are multiple long versions
that correspond to several singular parameters (\describe-view,
\describe-materialized-view, \describe-index, etc) but no combinatorics
(i.e. no \describe-view-and-foreign-table).

There is a \describe-schema and \describe-namespace, both of which perform
\dn.

There is a \describe-role but no \describe-user or \describe-database-role.

I chose \describe-privilege for \dp

I chose \describe-type for \dT instead of \describe-data-type.

The command \describe-aggregate-function is \dfa, whereas
\describe-aggregate is \da.

NOTES:

There is currently nothing stopping you from using the short form suffixes
on long form commands, but the reverse isn't true. For example, you can
type \describe-functionS+ and it'll work, but \df-verbose will not. I allow
this mostly because it would take work to prevent it.

Documentation XML was updated but not formatted to make the diff easier to
read.

No regression cases were added. Currently our coverage of \d commands in
psql ifself is quite minimal:

~/src/postgres$ grep '\\d' src/test/regress/sql/psql.sql | sort | uniq
\copyright \dt arg1 \e arg1 arg2
\df exp
\d psql_serial_tab_id_seq


but perhaps we could test it indirectly in these other areas:

~/src/postgres/src/test/regress/sql$ grep '\\d' * | sed -e 's/^.*\\d/\\d/g'
-e 's/ .*//g' | sort | uniq -c
156 \d
  2 \d'
  1 \d*',
157 \d+
  1 \d{4})',
  1 \da
  2 \d+):([a-zA-Z0-9+/=]+)\$([a-zA-Z0-9+=/]+):([a-zA-Z0-9+/=]+)',
  4 \des
  8 \des+
  1 \det+
  4 \deu
  6 \deu+
  1 \dew
 14 \dew+
 21 \df
  1 \dfn
  1 \dfp
  4 \dp
  4 \dRp
  6 \dRp+
  2 \dRs
  3 \dRs+
  2 \dt



On Mon, Jan 29, 2018 at 9:56 AM David Fetter  wrote:

> On Mon, Jan 29, 2018 at 02:51:53PM +, Ryan Murphy wrote:
> > >
> > > >What I propose is in fact a server command, >which at least three of
> > > >the other popular RDBMSs already have.
> > >
> > Well to actually implement it, it would probably be a client command,
> > because that's what \d* are.
>
> Why should this command be silo'ed off to the psql client?  If it's a
> server command, it's available to all clients, not just psql.
>
> > We would most likely want them implemented the same, to avoid
> > needless complexity.
>
> We could certainly have \d call DESCRIBE for later versions of the
> server.  \ commands which call different SQL depending on server
> version have long been a standard practice.
>
> > I think people are more ok with \describe (with the backslash), which
> seems
> > like what you're suggesting anyway.  I read Vik's "hard pass" as being on
> > having DESCRIBE which looks like an SQL command but would actually be
> > implemented on the client.  This seems simpler at first but could cause
> > deep confusion later.
>
> If we implement \d as DESCRIBE for server versions as of when DESCRIBE
> is actually implemented, we've got wins all around.
>
> Best,
> David.
> --
> David Fetter  http://fetter.org/
> Phone: +1 415 235 3778
>
> Remember to vote!
> Consider donating to Postgres: http://www.postgresql.org/about/donate
>
From e67e61ae789b09c98fe03378c819224d838c2f65 Mon Sep 17 00:00:00 2001
From: Corey Huinker 
Date: Fri, 25 Jan 2019 00:57:23 +
Subject: [PATCH] Add \describe commands to compliment \d commands

---
 doc/src/sgml/ref/psql-ref.sgml | 175 -
 src/bin/psql/command.c | 132 -
 src/bin/psql/describe.c|  13 ++-
 src/bin/psql/describe.h|   3 +
 src/bin/psql/tab-complete.c| 135 -
 5 files changed, 381 insertions(+), 77 deletions(-)

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 6c76cf2f00..363d6d9678 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -871,6 +871,17 @@ testdb=
 same line.
 
 
+
+The family of meta-commands starting with \d often
+have an equivalent \describe- "long form" command.
+The long-form commands often have the suffixes -system
+and -verbose which are the equivalent of the
+short form suffixes S and +
+

Re: \describe*

[David Fetter]

On Mon, Jan 29, 2018 at 02:51:53PM +, Ryan Murphy wrote:
> >
> > >What I propose is in fact a server command, >which at least three of
> > >the other popular RDBMSs already have.
> >
> Well to actually implement it, it would probably be a client command,
> because that's what \d* are.

Why should this command be silo'ed off to the psql client?  If it's a
server command, it's available to all clients, not just psql.

> We would most likely want them implemented the same, to avoid
> needless complexity.

We could certainly have \d call DESCRIBE for later versions of the
server.  \ commands which call different SQL depending on server
version have long been a standard practice.

> I think people are more ok with \describe (with the backslash), which seems
> like what you're suggesting anyway.  I read Vik's "hard pass" as being on
> having DESCRIBE which looks like an SQL command but would actually be
> implemented on the client.  This seems simpler at first but could cause
> deep confusion later.

If we implement \d as DESCRIBE for server versions as of when DESCRIBE
is actually implemented, we've got wins all around.

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[David Fetter]

On Sat, Jan 27, 2018 at 10:54:07PM +0100, Vik Fearing wrote:
> On 01/27/2018 05:39 PM, David Fetter wrote:
> > On Fri, Jan 26, 2018 at 04:28:24PM +0100, Vik Fearing wrote:
> >> On 01/26/2018 03:49 PM, David Fetter wrote:
> >>> I propose that we do what at least MySQL, Oracle, and DB2 do and
> >>> implement DESCRIBE as its own command.
> >> Hard pass.
> > 
> > Would you be so kind as to expand on this?  "Pass" might indicate a
> > lack of interest in doing the work, but "hard pass" seems to indicate
> > that you have reasons the work should not be done.  Have I interpreted
> > this correctly?
> 
> Andreas said it quite well.  I don't like having client commands look
> like server commands.  I don't mind exceptions for "help" and "quit",
> but I see no reason for anything more.

I did not propose a client command mimicking a server command.  I
thought I made that clear by mentioning that the \ commands are
unavailable to clients other than psql, and offering an alternative.

What I propose is in fact a server command, which at least three of
the other popular RDBMSs already have.

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[Vik Fearing]

On 01/27/2018 05:39 PM, David Fetter wrote:
> On Fri, Jan 26, 2018 at 04:28:24PM +0100, Vik Fearing wrote:
>> On 01/26/2018 03:49 PM, David Fetter wrote:
>>> I propose that we do what at least MySQL, Oracle, and DB2 do and
>>> implement DESCRIBE as its own command.
>> Hard pass.
> 
> Would you be so kind as to expand on this?  "Pass" might indicate a
> lack of interest in doing the work, but "hard pass" seems to indicate
> that you have reasons the work should not be done.  Have I interpreted
> this correctly?

Andreas said it quite well.  I don't like having client commands look
like server commands.  I don't mind exceptions for "help" and "quit",
but I see no reason for anything more.
-- 
Vik Fearing  +33 6 46 75 15 36
http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support

Re: \describe*

[David Fetter]

On Fri, Jan 26, 2018 at 04:28:24PM +0100, Vik Fearing wrote:
> On 01/26/2018 03:49 PM, David Fetter wrote:
> > I propose that we do what at least MySQL, Oracle, and DB2 do and
> > implement DESCRIBE as its own command.
> Hard pass.

Would you be so kind as to expand on this?  "Pass" might indicate a
lack of interest in doing the work, but "hard pass" seems to indicate
that you have reasons the work should not be done.  Have I interpreted
this correctly?

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[Corey Huinker]

>
> It would be about as hard to memorize \describe-schemas as it is to
> memorize \dn:
> You'd have to remember that it is "-" and not "_", that it is "describe",
> not "desc"
> and that it is "schemas", not "schema".
>

You wouldn't memorize them.  You'd discover them with tab completion.

Type "\d"  and you'll see
\d  \dA \dc \dd \ddp \des \deu \df \dFd \dFt \di \dL \dn \d0 \drds \dS \dT
\dv \dy
\da \db \dC \dD \dE  \det \dew \dF \dFp \dg  \dl \dm \do \dp \ds   \dt \du
\dx

which is more heat than light. Yes, those are all the possibilites, but I,
Joe Newguy, want to list schemas, and \ds and \dS look like the good
guesses, neither of which is the right answer.  If, with this feature, I
typed \desc, I might see:

\describe  \describe-functions  \describe-schemas  \describe-tables
...

So my voyage of discovery would have completed with having typed
"\desc-sc" and if we add a note to interactive mode, I'd be shown
the hint that \dn is the shortcut for that just above the list of schemas.

Re: \describe*

[Andreas Karlsson]

On 01/26/2018 03:49 PM, David Fetter wrote:> They are indeed terse and 
cryptic, and what's worse, they're not

available to clients other than psql, so I propose that we do what at
least MySQL, Oracle, and DB2 do and implement DESCRIBE as its own
command.

Especially handy would be a variant DESCRIBE CREATE, which would do
what it says on the label in a copy-and-paste-able form, but that's
not strictly necessary for the first cut.


I am not fan of this since I like how easy it is to explain to beginners 
that all backslash commands are processed by the client while everything 
else is handled by the server. Yes, "help" is an exception, but nobody 
really needs to know about that command.


As for the actually proposal I do not care strongly either way. The \d 
commands are a bit cryptic and unfriendly to the occasional user, but I 
am not sure that having two ways to do it would be better.


Andreas

Re: \describe*

[David Fetter]

On Thu, Jan 25, 2018 at 08:11:00PM -0500, Corey Huinker wrote:
> Some of the discussions about making psql more user friendly (more
> tab completions help, exit, etc) got me thinking about other ways
> that psql could be more friendly, and the one that comes to mind is
> our terse but cryptic \d* commands.

They are indeed terse and cryptic, and what's worse, they're not
available to clients other than psql, so I propose that we do what at
least MySQL, Oracle, and DB2 do and implement DESCRIBE as its own
command.

Especially handy would be a variant DESCRIBE CREATE, which would do
what it says on the label in a copy-and-paste-able form, but that's
not strictly necessary for the first cut.

Best,
David.
-- 
David Fetter  http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

Re: \describe*

[Laurenz Albe]

Corey Huinker wrote:
> Some of the discussions about making psql more user friendly (more tab 
> completions help, exit, etc) got me thinking about other ways that psql could 
> be more friendly, and the one that comes to mind is our terse but cryptic \d* 
> commands.
> 
> I think it would be helpful and instructive to have corresponding long-form 
> describe commands. 
> 
> Take describing schemas. Is \dn intuitive? Not really. In hindsight, you may 
> think "yeah, a schema is a namespace", but you never guessed 'n' on the first 
> try, or the second.
> 
> Looking over exec_command_d() a bit, I think it's a bit of a stretch do have 
> each command handle a long form like this:
> 
> \describe table my_table
> or
> \describe table verbose my_table
> 
> because then each \d-variant has to account for objects named "table" and 
> "verbose" and that's a path to unhappiness.
> 
> But if we dash-separated them, then all of the strcmps would be in the 'e' 
> subsection, and each one would just have to know it's long to short 
> translation, and call exec_command_d with the corresponding short command
> 
> describe => d
> describe-verbose => d+
> describe-aggregates-verbose => da+
> describe-roles => du
> 
> We could even presume the verbose flag in all cases (after all, the user was 
> being verbose...), which would also cut down on tab-completion results, and 
> we could check for interactive mode and display a message like
> 
> \describe-schemas (short: \dn+)
> 
> so that the person has the opportunity to learn the corresponding short 
> command.
> 
> In additional to aiding tab completion discovery of the commands (i.e. typing 
> "\desc" and then hitting tab, it would also make scripts a little more 
> self-documenting.
> 
> Thoughts?

I'm somewhat -1 on this.

It would be about as hard to memorize \describe-schemas as it is to memorize 
\dn:
You'd have to remember that it is "-" and not "_", that it is "describe", not 
"desc"
and that it is "schemas", not "schema".

Moreover, it would be as awkward to have
   \describe-schemas public
as it would be to list all schemas with
   \describe-schema

But my strongest criticism is that the \d* commands are for interactive use,
and who wants to type in a long string like that?  The beginner won't be able to
guess the correct command, and the experienced user would refuse to use it.


Having said all that, I can imagine that having \desc and \describe as an
alternative to \d would help beginners who come e.g. from Oracle,
but that would mean a change of the current behavior:

test=> \describe
 List of foreign servers
  Name  |  Owner   | Foreign-data wrapper 
+--+--
 oracle | postgres | oracle_fdw
(1 row)

This is because \des lists foreign servers, and the rest of the command is 
ignored.

Yours,
Laurenz Albe

Re: \describe*

[Vik Fearing]

On 01/26/2018 02:11 AM, Corey Huinker wrote:
> Some of the discussions about making psql more user friendly (more tab
> completions help, exit, etc) got me thinking about other ways that psql
> could be more friendly, and the one that comes to mind is our terse but
> cryptic \d* commands.
> 
> I think it would be helpful and instructive to have corresponding
> long-form describe commands. 
> 
> Take describing schemas. Is \dn intuitive? Not really. In hindsight, you
> may think "yeah, a schema is a namespace", but you never guessed 'n' on
> the first try, or the second.

At first blush, I support this idea.

> Looking over exec_command_d() a bit, I think it's a bit of a stretch do
> have each command handle a long form like this:
> 
> \describe table my_table
> or
> \describe table verbose my_table
> 
> because then each \d-variant has to account for objects named "table"
> and "verbose" and that's a path to unhappiness.

We're already being verbose so we can easily require

\describe table table

for the first case, and if you move "verbose" to before the object, then
we can have

\describe verbose table verbose

So basically, the grammar would be "\describe [verbose] [system] object
name" instead of "\dXS[+] name" where X is the object.

One thing not addressed here is a long version of \ditvS+.  Maybe
something like

\describe verbose system index, table, view 

> But if we dash-separated them, then all of the strcmps would be in the
> 'e' subsection, and each one would just have to know it's long to short
> translation, and call exec_command_d with the corresponding short command
> 
> describe => d
> describe-verbose => d+
> describe-aggregates-verbose => da+
> describe-roles => du

-1

> We could even presume the verbose flag in all cases (after all, the user
> was being verbose...), which would also cut down on tab-completion
> results, and we could check for interactive mode and display a message like
> 
> \describe-schemas (short: \dn+)
> 
> so that the person has the opportunity to learn the corresponding short
> command.

-1 on this, too.

If we presume "verbose", we need to add a "terse".  If the user is
interested in the short forms, they can issue a \? like everybody else.

> In additional to aiding tab completion discovery of the commands (i.e.
> typing "\desc" and then hitting tab, it would also make scripts a little
> more self-documenting.

I always use long versions of options when writing scripts specifically
because they are self-documenting (see 0be22457d7) so I certainly
support this argument.


Note: I am not volunteering to implement any of this, but I'll happily
review it.
-- 
Vik Fearing  +33 6 46 75 15 36
http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support