Skip to content

Commit

Permalink
psql: Support multiple -c and -f options, and allow mixing them.
Browse files Browse the repository at this point in the history 
To support this, we must reconcile some historical anomalies in the
behavior of -c.  In particular, as a backward-incompatibility, -c no
longer implies --no-psqlrc.

Pavel Stehule (code) and Catalin Iacob (documentation).  Review by
Michael Paquier and myself.  Proposed behavior per Tom Lane.
  • Loading branch information
@robertmhaas
robertmhaas committed Dec 8, 2015
1 parent 385f337 commit d5563d7
Show file tree
Hide file tree
Showing 5 changed files with 205 additions and 135 deletions.
88 changes: 53 additions & 35 deletions doc/src/sgml/ref/psql-ref.sgml
View file
Expand Up @@ -38,9 +38,10 @@ PostgreSQL documentation
<productname>PostgreSQL</productname>. It enables you to type in
queries interactively, issue them to
<productname>PostgreSQL</productname>, and see the query results.
Alternatively, input can be from a file. 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.
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.
</para>
</refsect1>

Expand Down Expand Up @@ -89,11 +90,10 @@ PostgreSQL documentation
<term><option>--command=<replaceable class="parameter">command</replaceable></></term>
<listitem>
<para>
Specifies that <application>psql</application> is to execute one
command string, <replaceable class="parameter">command</replaceable>,
and then exit. This is useful in shell scripts. Start-up files
(<filename>psqlrc</filename> and <filename>~/.psqlrc</filename>) are
ignored with this 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.
</para>
<para>
<replaceable class="parameter">command</replaceable> must be either
Expand All @@ -102,25 +102,34 @@ 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>, for example:
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.)
</para>
<para>
If the command string contains multiple SQL commands, they are
processed in a single transaction, unless there are explicit
<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. Also, only
the result of the last SQL command is returned.
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.
</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:
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.
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
via a shell here-document, for example:
<programlisting>
psql &lt;&lt;EOF
\x
Expand Down Expand Up @@ -185,9 +194,11 @@ EOF
<para>
Use the file <replaceable class="parameter">filename</replaceable>
as the source of commands instead of reading commands interactively.
After the file is processed, <application>psql</application>
terminates. This is in many ways equivalent to the meta-command
<command>\i</command>.
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>.
</para>

<para>
Expand Down Expand Up @@ -539,20 +550,21 @@ EOF
<term><option>--single-transaction</option></term>
<listitem>
<para>
When <application>psql</application> executes a script, adding
this option wraps <command>BEGIN</>/<command>COMMIT</> around the
script to execute it as a single transaction. This ensures that
either all the commands complete successfully, or no changes are
applied.
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.
</para>

<para>
If the script itself uses <command>BEGIN</>, <command>COMMIT</>,
If the commands themselves
contain <command>BEGIN</>, <command>COMMIT</>,
or <command>ROLLBACK</>, this option will not have the desired
effects.
Also, if the script contains any command that cannot be executed
inside a transaction block, specifying this option will cause that
command (and hence the whole transaction) to fail.
effects. Also, if an individual command cannot be executed inside a
transaction block, specifying this option will cause the whole
transaction to fail.
</para>
</listitem>
</varlistentry>
Expand Down Expand Up @@ -3725,7 +3737,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
<term><filename>psqlrc</filename> and <filename>~/.psqlrc</filename></term>
<listitem>
<para>
Unless it is passed an <option>-X</option> or <option>-c</option> option,
Unless it is passed an <option>-X</option> option,
<application>psql</application> attempts to read and execute commands
from the system-wide startup file (<filename>psqlrc</filename>) and then
the user's personal startup file (<filename>~/.psqlrc</filename>), after
Expand Down Expand Up @@ -3819,6 +3831,12 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
</para>
</listitem>

<listitem>
<para>
Before <productname>PostgreSQL</productname> 9.6, <option>-c</option>
implied <option>-X</option>; this is no longer the case.
</para>
</listitem>
</itemizedlist>
</refsect1>

Expand Down
34 changes: 2 additions & 32 deletions src/bin/psql/command.c
View file
Expand Up @@ -916,7 +916,7 @@ exec_command(const char *cmd,
include_relative = (strcmp(cmd, "ir") == 0
|| strcmp(cmd, "include_relative") == 0);
expand_tilde(&fname);
success = (process_file(fname, false, include_relative) == EXIT_SUCCESS);
success = (process_file(fname, include_relative) == EXIT_SUCCESS);
free(fname);
}
}
Expand Down Expand Up @@ -2288,13 +2288,12 @@ do_edit(const char *filename_arg, PQExpBuffer query_buf,
* the file from where the currently processed file (if any) is located.
*/
int
process_file(char *filename, bool single_txn, bool use_relative_path)
process_file(char *filename, bool use_relative_path)
{
FILE *fd;
int result;
char *oldfilename;
char relpath[MAXPGPATH];
PGresult *res;

if (!filename)
{
Expand Down Expand Up @@ -2339,37 +2338,8 @@ process_file(char *filename, bool single_txn, bool use_relative_path)
oldfilename = pset.inputfile;
pset.inputfile = filename;

if (single_txn)
{
if ((res = PSQLexec("BEGIN")) == NULL)
{
if (pset.on_error_stop)
{
result = EXIT_USER;
goto error;
}
}
else
PQclear(res);
}

result = MainLoop(fd);

if (single_txn)
{
if ((res = PSQLexec("COMMIT")) == NULL)
{
if (pset.on_error_stop)
{
result = EXIT_USER;
goto error;
}
}
else
PQclear(res);
}

error:
if (fd != stdin)
fclose(fd);

Expand Down
2 changes: 1 addition & 1 deletion src/bin/psql/command.h
View file
Expand Up @@ -27,7 +27,7 @@ typedef enum _backslashResult
extern backslashResult HandleSlashCmds(PsqlScanState scan_state,
PQExpBuffer query_buf);

extern int process_file(char *filename, bool single_txn, bool use_relative_path);
extern int process_file(char *filename, bool use_relative_path);

extern bool do_pset(const char *param,
const char *value,
Expand Down

0 comments on commit d5563d7

Please sign in to comment.