pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedSummary of DDL/DML statement return/output values?
5+ messages / 2 participants
[nested] [flat]
* Summary of DDL/DML statement return/output values?
@ 2020-06-22 16:48 Steve Estes <denzera@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Steve Estes @ 2020-06-22 16:48 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi docs gang,
First time poster here, big fan of all the work you do.
When interacting with the server through all the various types of DML and
DDL statements, the return message that the server sends back to the client
varies in content and format. For example, a response to a CREATE TABLE is
just "CREATE TABLE" (so, no change in tense e.g. 'CREATED', or a table name
acknowledgement or something), whereas a COPY command yields "COPY
<rowcount>", and the output from an INSERT is "INSERT <oids> <rowcount>".
CREATE TABLE AS SELECT (...) yields a reply of "SELECT <rowcount>", very
different from other variations of the CREATE TABLE statement. The
variation in format is of course necessary, since the various SQL
statements do very different things.
However, for some statements PG's output format is documented (e.g. INSERT
<https://www.postgresql.org/docs/12/sql-insert.html;, EXPLAIN
<https://www.postgresql.org/docs/12/sql-explain.html;), and in others it is
not (e.g. SET <https://www.postgresql.org/docs/12/sql-set.html;, CREATE
TABLE <https://www.postgresql.org/docs/12/sql-createtable.html;, ALTER TABLE
<https://www.postgresql.org/docs/12/sql-altertable.html;, etc). The
output-control RETURNING clause gets its own page
<https://www.postgresql.org/docs/12/dml-returning.html;, but I'm unaware of
any other meta-summary of output values.
*Is there a summary of what PG returns in response to each of the various
statements that it supports? If not, should there be?*
I'm asking because I'm considering proposing a feature request to the
hackers list that would alter response output under certain circumstances,
and was looking to educate myself about the full scope of current server
outputs. So I was a little surprised when I couldn't readily find that
information, given the thoroughness of documentation in every other respect.
Thanks for your help,
Steve Estes
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Summary of DDL/DML statement return/output values?
@ 2020-06-22 17:43 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Steve Estes <denzera@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Alvaro Herrera @ 2020-06-22 17:43 UTC (permalink / raw)
To: Steve Estes <denzera@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On 2020-Jun-22, Steve Estes wrote:
> However, for some statements PG's output format is documented (e.g. INSERT
> <https://www.postgresql.org/docs/12/sql-insert.html;, EXPLAIN
> <https://www.postgresql.org/docs/12/sql-explain.html;), and in others it is
> not (e.g. SET <https://www.postgresql.org/docs/12/sql-set.html;, CREATE
> TABLE <https://www.postgresql.org/docs/12/sql-createtable.html;, ALTER TABLE
> <https://www.postgresql.org/docs/12/sql-altertable.html;, etc). The
> output-control RETURNING clause gets its own page
> <https://www.postgresql.org/docs/12/dml-returning.html;, but I'm unaware of
> any other meta-summary of output values.
>
> *Is there a summary of what PG returns in response to each of the various
> statements that it supports? If not, should there be?*
I think starting with commit 2f9661311b83 it might be possible to create
such a table. I'm wary of documenting this painting us into a corner
forever, though.
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=2f9661311b83dc481fc19f6e3bda01539...
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Summary of DDL/DML statement return/output values?
@ 2020-06-23 18:12 Steve Estes <denzera@gmail.com>
parent: Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 1 reply; 5+ messages in thread
From: Steve Estes @ 2020-06-23 18:12 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@2ndquadrant.com>; +Cc: pgsql-docs@lists.postgresql.org
Thanks Alvaro. Looks cool. So, on the one hand it'd be nice to be able to
auto-generate this once all the commands are standardized into one
structure. That'd be slick.
On the other hand, the number of commands in SQL is not that large a
universe, such that it'd be at least somewhat practical to just add Output
as a standard section of the doc page for any command. They number 182 in
both v11, v12 and v13 thus far, and many of those are variations of ALTER,
CREATE or DROP (127 of them, in fact), such that they probably mostly share
an output format. More importantly, the output of each command is unlikely
to change much going forward, certainly not within a major release
(right?). So we could just document each command's output, and if need be
then pull that information into a summary page thereafter, or when the
commit you mention is finished.
Just seemed like a standard thing that software docs cover - like how the
documentation of a programming language's function library always mentions
what is returned by each function (even if nothing).
-Steve
On Mon, Jun 22, 2020 at 1:43 PM Alvaro Herrera <alvherre@2ndquadrant.com>
wrote:
> On 2020-Jun-22, Steve Estes wrote:
>
> > However, for some statements PG's output format is documented (e.g.
> INSERT
> > <https://www.postgresql.org/docs/12/sql-insert.html;, EXPLAIN
> > <https://www.postgresql.org/docs/12/sql-explain.html;), and in others
> it is
> > not (e.g. SET <https://www.postgresql.org/docs/12/sql-set.html;, CREATE
> > TABLE <https://www.postgresql.org/docs/12/sql-createtable.html;, ALTER
> TABLE
> > <https://www.postgresql.org/docs/12/sql-altertable.html;, etc). The
> > output-control RETURNING clause gets its own page
> > <https://www.postgresql.org/docs/12/dml-returning.html;, but I'm
> unaware of
> > any other meta-summary of output values.
> >
> > *Is there a summary of what PG returns in response to each of the various
> > statements that it supports? If not, should there be?*
>
> I think starting with commit 2f9661311b83 it might be possible to create
> such a table. I'm wary of documenting this painting us into a corner
> forever, though.
>
>
> https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=2f9661311b83dc481fc19f6e3bda01539...
>
> --
> Álvaro Herrera https://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Summary of DDL/DML statement return/output values?
@ 2020-06-23 20:01 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Steve Estes <denzera@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Alvaro Herrera @ 2020-06-23 20:01 UTC (permalink / raw)
To: Steve Estes <denzera@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On 2020-Jun-23, Steve Estes wrote:
> Thanks Alvaro. Looks cool. So, on the one hand it'd be nice to be able to
> auto-generate this once all the commands are standardized into one
> structure. That'd be slick.
I thought they were already standardized ... But anyway, I was thinking
that this would generate *one* table listing all commands with their
tags. I was not thinking in putting the tag in each command's page:
I'm not sure that that would be generatable.
> On the other hand, the number of commands in SQL is not that large a
> universe, such that it'd be at least somewhat practical to just add Output
> as a standard section of the doc page for any command. They number 182 in
> both v11, v12 and v13 thus far, and many of those are variations of ALTER,
> CREATE or DROP (127 of them, in fact), such that they probably mostly share
> an output format. More importantly, the output of each command is unlikely
> to change much going forward, certainly not within a major release
> (right?). So we could just document each command's output, and if need be
> then pull that information into a summary page thereafter, or when the
> commit you mention is finished.
I can't say I'm terribly excited about this idea. I won't stop you if
you want to pursue it, but I'm not sure I see the value in a RETURN
VALUE section that says that the command returns the command name.
Maybe it would make sense to have that for the exceptional cases only?
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Summary of DDL/DML statement return/output values?
@ 2020-06-23 20:15 Steve Estes <denzera@gmail.com>
parent: Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 0 replies; 5+ messages in thread
From: Steve Estes @ 2020-06-23 20:15 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@2ndquadrant.com>; +Cc: pgsql-docs@lists.postgresql.org
Yeah I wouldn't say it's worth putting effort in over something that just
returns the command name, but the other cases do have some variety to them
and would probably be a benefit. I found INSERT to be very odd until I saw
its explanation (the OIDs legacy thing).
Is there a command that returns more than one line of input, for example?
Other than a SELECT or a DML with a RETURNING clause, of course.
On Tue, Jun 23, 2020 at 4:01 PM Alvaro Herrera <alvherre@2ndquadrant.com>
wrote:
> On 2020-Jun-23, Steve Estes wrote:
>
> > Thanks Alvaro. Looks cool. So, on the one hand it'd be nice to be able
> to
> > auto-generate this once all the commands are standardized into one
> > structure. That'd be slick.
>
> I thought they were already standardized ... But anyway, I was thinking
> that this would generate *one* table listing all commands with their
> tags. I was not thinking in putting the tag in each command's page:
> I'm not sure that that would be generatable.
>
> > On the other hand, the number of commands in SQL is not that large a
> > universe, such that it'd be at least somewhat practical to just add
> Output
> > as a standard section of the doc page for any command. They number 182
> in
> > both v11, v12 and v13 thus far, and many of those are variations of
> ALTER,
> > CREATE or DROP (127 of them, in fact), such that they probably mostly
> share
> > an output format. More importantly, the output of each command is
> unlikely
> > to change much going forward, certainly not within a major release
> > (right?). So we could just document each command's output, and if need
> be
> > then pull that information into a summary page thereafter, or when the
> > commit you mention is finished.
>
> I can't say I'm terribly excited about this idea. I won't stop you if
> you want to pursue it, but I'm not sure I see the value in a RETURN
> VALUE section that says that the command returns the command name.
> Maybe it would make sense to have that for the exceptional cases only?
>
> --
> Álvaro Herrera https://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2020-06-23 20:15 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-06-22 16:48 Summary of DDL/DML statement return/output values? Steve Estes <denzera@gmail.com>
2020-06-22 17:43 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-23 18:12 ` Steve Estes <denzera@gmail.com>
2020-06-23 20:01 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-23 20:15 ` Steve Estes <denzera@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox