Hello devs,
I'm looking at psql's use of PQexec for implementing some feature.
When running with multiple SQL commands, the doc is not very helpful.
From the source code I gathered that PQexec returns the first COPY results
if any, and if not the last non-empty results, unless all is empty in
which case an empty result is returned. So * marks the returned result
in the following examples:
INSERT ... \; * COPY ... \; SELECT ... \; \;
SELECT ... \; UPDATE ... \; * SELECT ... \; \;
\; \; * ;
The attached patch tries to improve the documentation based on my
understanding.
IMVHO, psql's code is kind of a mess to work around this strange behavior,
as there is a loop over results within PQexec, then another one after
PQexec if there were some COPY.
--
Fabien.
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7f01fcc148..de9a0652a1 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -2488,9 +2488,14 @@ PGresult *PQexec(PGconn *conn, const char *command);
for more details about how the server handles multi-query strings.)
Note however that the returned
<structname>PGresult</structname> structure describes only the result
- of the last command executed from the string. Should one of the
- commands fail, processing of the string stops with it and the returned
- <structname>PGresult</structname> describes the error condition.
+ of the last command executed from the string.
+ If the strings contains <command>COPY</command> commands, the result of the
+ first of those is returned and further results should be fetched with
+ <function>PQgetResult</function>.
+ If the string contains only empty commands, an empty result is returned.
+ Otherwise, the result of the last non-empty command is returned.
+ Should one of the commands fail, processing of the string stops with it and
+ the returned <structname>PGresult</structname> describes the error condition.
</para>
<para>
