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