database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Code and docs review for multiple -c and -f options in psql.

Browse Source 
Commit d5563d7df9 drew complaints from Coverity, which quite
correctly complained that one copy of each -c or -f string was being
leaked.  What's more, simple_action_list_append was allocating enough space
for still a third copy of each string as part of the SimpleActionListCell,
even though that coding method had been superseded by a separate strdup
operation.  There were some other minor coding infelicities too.  The
documentation needed more work as well, eg it forgot to explain that -c
causes psql not to accept any interactive input.
This commit is contained in:
Tom Lane
2015-12-13 14:52:07 -05:00
parent a91bdf67c4
commit fcbbf82d2b
2 changed files with 121 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
doc/src/sgml/ref/psql-ref.sgml
View File

@ -39,9 +39,9 @@ PostgreSQL documentation
queries interactively, issue them to
<productname>PostgreSQL</productname>, and see the query results.
Alternatively, input can be from a file or from command line
arguments. In addition, it provides a number of meta-commands and various
shell-like features to facilitate writing scripts and automating a wide
variety of tasks.
arguments. In addition, <application>psql</application> provides a
number of meta-commands and various shell-like features to
facilitate writing scripts and automating a wide variety of tasks.
</para>
</refsect1>
@ -90,42 +90,50 @@ PostgreSQL documentation
<term><option>--command=<replaceable class="parameter">command</replaceable></></term>
<listitem>
<para>
Specifies that <application>psql</application> is to execute the given
command string, <replaceable class="parameter">command</replaceable>.
This option can be repeated and combined in any order with
the <option>-f</option> option.
Specifies that <application>psql</application> is to execute the given
command string, <replaceable class="parameter">command</replaceable>.
This option can be repeated and combined in any order with
the <option>-f</option> option. When either <option>-c</option>
or <option>-f</option> is specified, <application>psql</application>
does not read commands from standard input; instead it terminates
after processing all the <option>-c</option> and <option>-f</option>
options in sequence.
</para>
<para>
<replaceable class="parameter">command</replaceable> must be either
a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application>-specific features),
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
use repeated <option>-c</option> options or pipe the string
into <application>psql</application>, for example:
<literal>psql -c '\x' -c 'SELECT * FROM foo;'</literal> or
<literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
(<literal>\\</> is the separator meta-command.)
<replaceable class="parameter">command</replaceable> must be either
a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application>-specific features),
or a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application>
meta-commands within a <option>-c</option> option. To achieve that,
you could use repeated <option>-c</option> options or pipe the string
into <application>psql</application>, for example:
<programlisting>
psql -c '\x' -c 'SELECT * FROM foo;'
</programlisting>
or
<programlisting>
echo '\x \\ SELECT * FROM foo;' | psql
</programlisting>
(<literal>\\</> is the separator meta-command.)
</para>
<para>
Each command string passed to <option>-c</option> is sent to the server
as a single query. Because of this, the server executes it as a single
transaction, even if a command string contains
multiple <acronym>SQL</acronym> commands, unless there are
explicit <command>BEGIN</>/<command>COMMIT</> commands included in the
string to divide it into multiple transactions. Also, the server only
returns the result of the last <acronym>SQL</acronym> command to the
client. This is different from the behavior when the same string with
multiple <acronym>SQL</acronym> commands is fed
to <application>psql</application>'s standard input because
then <application>psql</application> sends each <acronym>SQL</acronym>
command separately.
Each <acronym>SQL</acronym> command string passed
to <option>-c</option> is sent to the server as a single query.
Because of this, the server executes it as a single transaction even
if the string contains multiple <acronym>SQL</acronym> commands,
unless there are explicit <command>BEGIN</>/<command>COMMIT</>
commands included in the string to divide it into multiple
transactions. Also, <application>psql</application> only prints the
result of the last <acronym>SQL</acronym> command in the string.
This is different from the behavior when the same string is read from
a file or fed to <application>psql</application>'s standard input,
because then <application>psql</application> sends
each <acronym>SQL</acronym> command separately.
</para>
<para>
Putting more than one command in the <option>-c</option> string often
has unexpected results. This is a result of the fact that the whole
string is sent to the server as a single query.
Because of this behavior, putting more than one command in a
single <option>-c</option> string often has unexpected results.
It's better to use repeated <option>-c</option> commands or feed
multiple commands to <application>psql</application>'s standard input,
either using <application>echo</application> as illustrated above, or
@ -192,18 +200,26 @@ EOF
<term><option>--file=<replaceable class="parameter">filename</replaceable></></term>
<listitem>
<para>
Use the file <replaceable class="parameter">filename</replaceable>
as the source of commands instead of reading commands interactively.
This option can be repeated and combined in any order with
the <option>-c</option> option. After the commands in
every <option>-c</option> command string and <option>-f</option> file
are processed, <application>psql</application> terminates. This option
is in many ways equivalent to the meta-command <command>\i</command>.
Read commands from the
file <replaceable class="parameter">filename</replaceable>,
rather than standard input.
This option can be repeated and combined in any order with
the <option>-c</option> option. When either <option>-c</option>
or <option>-f</option> is specified, <application>psql</application>
does not read commands from standard input; instead it terminates
after processing all the <option>-c</option> and <option>-f</option>
options in sequence.
Except for that, this option is largely equivalent to the
meta-command <command>\i</command>.
</para>
<para>
If <replaceable>filename</replaceable> is <literal>-</literal>
(hyphen), then standard input is read.
(hyphen), then standard input is read until an EOF indication
or <command>\q</> meta-command. This can be used to intersperse
interactive input with input from files. Note however that Readline
is not used in this case (much as if <option>-n</option> had been
specified).
</para>
<para>
@ -550,12 +566,13 @@ EOF
<term><option>--single-transaction</option></term>
<listitem>
<para>
When <application>psql</application> executes commands from a script
and/or a <option>-c</option> option, adding this option
wraps <command>BEGIN</>/<command>COMMIT</> around all of those
commands as a whole to execute them as a single transaction. This
ensures that either all the commands complete successfully, or no
changes are applied.
This option can only be used in combination with one or more
<option>-c</option> and/or <option>-f</option> options. It causes
<application>psql</application> to issue a <command>BEGIN</> command
before the first such option and a <command>COMMIT</> command after
the last one, thereby wrapping all the commands into a single
transaction. This ensures that either all the commands complete
successfully, or no changes are applied.
</para>
<para>
@ -3799,16 +3816,6 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
In an earlier life <application>psql</application> allowed the
first argument of a single-letter backslash command to start
directly after the command, without intervening whitespace.
As of <productname>PostgreSQL</productname> 8.4 this is no
longer allowed.
</para>
</listitem>
<listitem>
<para><application>psql</application> works best with servers of the same
or an older major version. Backslash commands are particularly likely
@ -3824,8 +3831,8 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
If you want to use <application>psql</application> to connect to several
servers of different major versions, it is recommended that you use the
newest version of <application>psql</application>. Alternatively, you
can keep a copy of <application>psql</application> from each major
version around and be sure to use the version that matches the
can keep around a copy of <application>psql</application> from each
major version and be sure to use the version that matches the
respective server. But in practice, this additional complication should
not be necessary.
</para>
@ -3833,8 +3840,19 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
<listitem>
<para>
Before <productname>PostgreSQL</productname> 9.6, <option>-c</option>
implied <option>-X</option>; this is no longer the case.
Before <productname>PostgreSQL</productname> 9.6,
the <option>-c</option> option implied <option>-X</option>
(<option>--no-psqlrc</>); this is no longer the case.
</para>
</listitem>
<listitem>
<para>
Before <productname>PostgreSQL</productname> 8.4,
<application>psql</application> allowed the
first argument of a single-letter backslash command to start
directly after the command, without intervening whitespace.
Now, some whitespace is required.
</para>
</listitem>
</itemizedlist>