Home > mailing lists

Thread: \describe*

\describe*

From

Corey Huinker

Date:

26 January 2018, 07:11:00

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?

Re: \describe*

From

Vik Fearing

Date:

26 January 2018, 07:58:09

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

> 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

Re: \describe*

From

Laurenz Albe

Date:

26 January 2018, 15:56:58

Corey Huinker wrote:
> Some of the discussions about making psql more user friendly (more tab completions help, exit, etc) got me thinking
aboutother 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",
butyou 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
toknow 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
downon 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
alsomake 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*

From

David Fetter

Date:

26 January 2018, 20:49:12

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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Andreas Karlsson

Date:

26 January 2018, 20:54:49

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*

From

Vik Fearing

Date:

26 January 2018, 21:28:24

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.
-- 
Vik Fearing                                          +33 6 46 75 15 36
http://2ndQuadrant.fr     PostgreSQL : Expertise, Formation et Support

Re: \describe*

From

Corey Huinker

Date:

27 January 2018, 00:57:54

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<tab>" 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<tab>, I might see:

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

...

So my voyage of discovery would have completed with having typed "\desc<tab>-sc<tab>" 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*

From

David Fetter

Date:

27 January 2018, 22:39:17

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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Vik Fearing

Date:

28 January 2018, 03:54:07

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*

From

David Fetter

Date:

28 January 2018, 05:01:20

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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Ryan Murphy

Date:

29 January 2018, 20:51:53

>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. We would most likely want them implemented the same, to avoid needless complexity.

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.

But \describe gives a hint that it's different with the \, so it might be fine.

Overall I agree with your idea: the \d* commands are cryptic and a longhand form would help people learning.

Best,

Ryan

Re: \describe*

From

David Fetter

Date:

29 January 2018, 20:56:57

On Mon, Jan 29, 2018 at 02:51:53PM +0000, 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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Corey Huinker

Date:

25 January 2019, 04:37:48

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 <david@fetter.org> wrote:

On Mon, Jan 29, 2018 at 02:51:53PM +0000, 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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Attachment

0001-Add-describe-commands-to-compliment-d-commands.patch

Re: \describe*

From

Andres Freund

Date:

14 February 2019, 21:44:02

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*

From

Corey Huinker

Date:

24 February 2019, 03:14:27

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*

From

Andres Freund

Date:

24 February 2019, 03:18:54

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*

From

Robert Haas

Date:

25 February 2019, 22:44:21

On Sat, Feb 23, 2019 at 7:19 PM Andres Freund <andres@anarazel.de> 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*

From

Ibrar Ahmed

Date:

04 March 2019, 17:01:24

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
ofthe 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
sampleif you want I can do that for whole code.
 

-- 
Ibrar Ahmed

The new status of this patch is: Waiting on Author

Re: \describe*

From

Ibrar Ahmed

Date:

04 March 2019, 17:04:00

Hi Corey,

Here is the modified patch (sample).

On Mon, Mar 4, 2019 at 7:02 PM Ibrar Ahmed <ibrar.ahmad@gmail.com> 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

Attachment

0001-Add-describe-commands-to-compliment-d-commands-ibrar-v2.patch

Re: \describe*

From

Corey Huinker

Date:

04 March 2019, 21:45:23

- 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: Re: \describe*

From

David Steele

Date:

05 March 2019, 10:57:25

On 2/25/19 9:44 PM, Robert Haas wrote:
> On Sat, Feb 23, 2019 at 7:19 PM Andres Freund <andres@anarazel.de> 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
david@pgmasters.net

Re: Re: \describe*

From

Corey Huinker

Date:

05 March 2019, 20:01:45

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: \describe*

From

Corey Huinker

Date:

09 March 2019, 03:19:45

On Mon, Mar 4, 2019 at 1:45 PM Corey Huinker <corey.huinker@gmail.com> 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.

Attachment

0001-Add-describe-commands-to-compliment-d-commands.patch

Re: \describe*

From

Pavel Stehule

Date:

09 March 2019, 08:10:42

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*

From

Alvaro Herrera

Date:

22 June 2019, 00:20:54

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 Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: \describe*

From

David Fetter

Date:

22 June 2019, 00:37:49

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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Alvaro Herrera

Date:

22 June 2019, 00:49:43

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 Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: \describe*

From

Tom Lane

Date:

22 June 2019, 01:53:06

Alvaro Herrera <alvherre@2ndquadrant.com> 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*

From

David Fetter

Date:

22 June 2019, 02:53:53

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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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

Re: \describe*

From

Corey Huinker

Date:

22 June 2019, 22:34:33

> 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 <object>" (essentially, pg_dump of <object>) which would have basically the same design issues as DESCRIBE would, though the result set would be a much simpler SETOF text.

Re: \describe*

From

Thomas Munro

Date:

01 August 2019, 13:03:51

On Sun, Jun 23, 2019 at 7:34 AM Corey Huinker <corey.huinker@gmail.com> 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*

From

Corey Huinker

Date:

01 August 2019, 21:57:19

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 has attempted to implement that (Snowflake) and even that was far from seamless.

3. There's a clear need to be able to get the DDL steps needed to re-create most common objects. This could be to copy-paste the info into another session to create a similar object elsewhere, or for test cases, or so an experienced person can see the "real guts" of an object without worrying about what details have been hidden.

4. The needs in #1 and #3 are in direct opposition to each other, and cannot easily be handled by the same command. Indeed, no one has tried.

5. The SHOW CREATE commands are neat, but the plethora of options (include comments? include RI constraints? does current session locale figure into the answer? dependencies?) probably mean that a function the get_ddl() examples above, can be jam-packed with default parameters and it's still going to have a very RETURNS SETOF TEXT output.

6. The convenience-function DESCRIBE / SHOW COLUMNS commands strive to have a tabular format with following: column name, a user-readable datatype, null/notnull flag, indicator that the column participates in a PK, in a unique index, in any other sort of index, without naming the index, and options for showing default values, and comments

7. People coming from other databases have expectations of a command like DESCRIBE existing, and those expectations are reasonable.

8. The commands we do make should strive to have a stable result-set format to allow their use in situations where the results can easily be handled via JDBC/DBD/DBI, and maybe somewhere down the road the commands themselves can be used as a subquery the same way that TABLE foo is an alias for SELECT * FROM foo.

9. Since the relevant columns for describing a table are different than those for a view or an index or another object, they should be separate commands.

I'm interested to hear what other people thing, and which of these goals are most worth pursuing in the near term to make postgres more usable to newbies and veterans alike.

Re: \describe*

From

Alvaro Herrera

Date:

03 September 2019, 21:33:05

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 Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services