From f70a78bc1f5556546d809a8164b9ba6a907f266f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 13 Mar 2014 13:49:03 -0400
Subject: Allow psql to print COPY command status in more cases.

Previously, psql would print the "COPY nnn" command status only for COPY
commands executed server-side.  Now it will print that for frontend copies
too (including \copy).  However, we continue to suppress the command status
for COPY TO STDOUT, since in that case the copy data has been routed to the
same place that the command status would go, and there is a risk of the
status line being mistaken for another line of COPY data.  Doing that would
break existing scripts, and it doesn't seem worth the benefit --- this case
seems fairly analogous to SELECT, for which we also suppress the command
status.

Kumar Rajeev Rastogi, with substantial review by Amit Khandekar
---
 doc/src/sgml/ref/copy.sgml     | 10 ++++++++++
 doc/src/sgml/ref/psql-ref.sgml | 38 +++++++++++++++++++-------------------
 2 files changed, 29 insertions(+), 19 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 5be3514612e..0544c68bbc0 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -370,6 +370,16 @@ COPY <replaceable class="parameter">count</replaceable>
    The <replaceable class="parameter">count</replaceable> is the number
    of rows copied.
   </para>
+
+  <note>
+   <para>
+    <application>psql</> will print this command tag only if the command
+    was not <literal>COPY ... TO STDOUT</>, or the
+    equivalent <application>psql</> meta-command
+    <literal>\copy ... to stdout</>.  This is to prevent confusing the
+    command tag with the data that was just printed.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 8813be8f2a2..5dce06af26e 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -863,36 +863,36 @@ testdb=&gt;
         <para>
         When <literal>program</> is specified,
         <replaceable class="parameter">command</replaceable> is
-        executed by <application>psql</application> and the data from
+        executed by <application>psql</application> and the data passed from
         or to <replaceable class="parameter">command</replaceable> is
         routed between the server and the client.
-        This means that the execution privileges are those of
+        Again, the execution privileges are those of
         the local user, not the server, and no SQL superuser
         privileges are required.
         </para>
 
-        <para><literal>\copy ... from stdin | to stdout</literal>
-        reads/writes based on the command input and output respectively.
-        All rows are read from the same source that issued the command,
-        continuing until <literal>\.</literal> is read or the stream
-        reaches <acronym>EOF</>. Output is sent to the same place as
-        command output. To read/write from
-        <application>psql</application>'s standard input or output, use
-        <literal>pstdin</> or <literal>pstdout</>. This option is useful
+        <para>
+        For <literal>\copy ... from stdin</>, data rows are read from the same
+        source that issued the command, continuing until <literal>\.</literal>
+        is read or the stream reaches <acronym>EOF</>. This option is useful
         for populating tables in-line within a SQL script file.
+        For <literal>\copy ... to stdout</>, output is sent to the same place
+        as <application>psql</> command output, and
+        the <literal>COPY <replaceable>count</></literal> command status is
+        not printed (since it might be confused with a data row).
+        To read/write <application>psql</application>'s standard input or
+        output regardless of the current command source or <literal>\o</>
+        option, write <literal>from pstdin</> or <literal>to pstdout</>.
         </para>
 
         <para>
-        The syntax of the command is similar to that of the
+        The syntax of this command is similar to that of the
         <acronym>SQL</acronym> <xref linkend="sql-copy">
-        command, and
-        <replaceable class="parameter">option</replaceable>
-        must indicate one of the options of the
-        <acronym>SQL</acronym> <xref linkend="sql-copy"> command.
-        Note that, because of this,
-        special parsing rules apply to the <command>\copy</command>
-        command. In particular, the variable substitution rules and
-        backslash escapes do not apply.
+        command.  All options other than the data source/destination are
+        as specified for <xref linkend="sql-copy">.
+        Because of this, special parsing rules apply to the <command>\copy</>
+        command. In particular, <application>psql</>'s variable substitution
+        rules and backslash escapes do not apply.
         </para>
 
         <tip>
-- 
cgit v1.2.3