From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 14 Feb 2014 17:54:53 +0000 (-0500)
Subject: Suggest shell here-documents instead of psql -c for multiple commands.
X-Git-Tag: REL9_0_16~13
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4588e330442fe130bbdcf4bdd4c35fc19deb329d;p=postgresql

Suggest shell here-documents instead of psql -c for multiple commands.

The documentation suggested using "echo | psql", but not the often-superior
alternative of a here-document.  Also, be more direct about suggesting
that people avoid -c for multiple commands.  Per discussion.
---

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 648a6e6094..fa2b994484 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -90,8 +90,8 @@ PostgreSQL documentation
       or a single backslash command. Thus you cannot mix
       <acronym>SQL</acronym> and <application>psql</application>
       meta-commands with this option. To achieve that, you could
-      pipe the string into <application>psql</application>, like
-      this: <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
+      pipe the string into <application>psql</application>, for example:
+      <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
       (<literal>\\</> is the separator meta-command.)
       </para>
       <para>
@@ -100,7 +100,21 @@ PostgreSQL documentation
        <command>BEGIN</>/<command>COMMIT</> commands included in the
        string to divide it into multiple transactions.  This is
        different from the behavior when the same string is fed to
-       <application>psql</application>'s standard input.
+       <application>psql</application>'s standard input.  Also, only
+       the result of the last SQL command is returned.
+      </para>
+      <para>
+       Because of these legacy behaviors, putting more than one command in
+       the <option>-c</option> string often has unexpected results.  It's
+       better to feed multiple commands to <application>psql</application>'s
+       standard input, either using <application>echo</application> as
+       illustrated above, or via a shell here-document, for example:
+<programlisting>
+psql &lt;&lt;EOF
+\x
+SELECT * FROM foo;
+EOF
+</programlisting>
       </para>
       </listitem>
     </varlistentry>