@@ -39,9 +39,9 @@ PostgreSQL documentation
39
39
queries interactively, issue them to
40
40
<productname>PostgreSQL</productname>, and see the query results.
41
41
Alternatively, input can be from a file or from command line
42
- arguments. In addition, it provides a number of meta-commands and various
43
- shell-like features to facilitate writing scripts and automating a wide
44
- variety of tasks.
42
+ arguments. In addition, <application>psql</application> provides a
43
+ number of meta-commands and various shell-like features to
44
+ facilitate writing scripts and automating a wide variety of tasks.
45
45
</para>
46
46
</refsect1>
47
47
@@ -90,42 +90,50 @@ PostgreSQL documentation
90
90
<term><option>--command=<replaceable class="parameter">command</replaceable></></term>
91
91
<listitem>
92
92
<para>
93
- Specifies that <application>psql</application> is to execute the given
94
- command string, <replaceable class="parameter">command</replaceable>.
95
- This option can be repeated and combined in any order with
96
- the <option>-f</option> option.
93
+ Specifies that <application>psql</application> is to execute the given
94
+ command string, <replaceable class="parameter">command</replaceable>.
95
+ This option can be repeated and combined in any order with
96
+ the <option>-f</option> option. When either <option>-c</option>
97
+ or <option>-f</option> is specified, <application>psql</application>
98
+ does not read commands from standard input; instead it terminates
99
+ after processing all the <option>-c</option> and <option>-f</option>
100
+ options in sequence.
97
101
</para>
98
102
<para>
99
- <replaceable class="parameter">command</replaceable> must be either
100
- a command string that is completely parsable by the server (i.e.,
101
- it contains no <application>psql</application>-specific features),
102
- or a single backslash command. Thus you cannot mix
103
- <acronym>SQL</acronym> and <application>psql</application>
104
- meta-commands with this option. To achieve that, you could
105
- use repeated <option>-c</option> options or pipe the string
106
- into <application>psql</application>, for example:
107
- <literal>psql -c '\x' -c 'SELECT * FROM foo;'</literal> or
108
- <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
109
- (<literal>\\</> is the separator meta-command.)
103
+ <replaceable class="parameter">command</replaceable> must be either
104
+ a command string that is completely parsable by the server (i.e.,
105
+ it contains no <application>psql</application>-specific features),
106
+ or a single backslash command. Thus you cannot mix
107
+ <acronym>SQL</acronym> and <application>psql</application>
108
+ meta-commands within a <option>-c</option> option. To achieve that,
109
+ you could use repeated <option>-c</option> options or pipe the string
110
+ into <application>psql</application>, for example:
111
+ <programlisting>
112
+ psql -c '\x' -c 'SELECT * FROM foo;'
113
+ </programlisting>
114
+ or
115
+ <programlisting>
116
+ echo '\x \\ SELECT * FROM foo;' | psql
117
+ </programlisting>
118
+ (<literal>\\</> is the separator meta-command.)
110
119
</para>
111
120
<para>
112
- Each command string passed to <option>-c</option> is sent to the server
113
- as a single query. Because of this, the server executes it as a single
114
- transaction, even if a command string contains
115
- multiple <acronym>SQL</acronym> commands, unless there are
116
- explicit <command>BEGIN</>/<command>COMMIT</> commands included in the
117
- string to divide it into multiple transactions. Also, the server only
118
- returns the result of the last <acronym>SQL</acronym> command to the
119
- client. This is different from the behavior when the same string with
120
- multiple <acronym>SQL</acronym> commands is fed
121
- to <application>psql</application>'s standard input because
122
- then <application>psql</application> sends each <acronym>SQL</acronym>
123
- command separately.
121
+ Each <acronym>SQL</acronym> command string passed
122
+ to <option>-c</option> is sent to the server as a single query.
123
+ Because of this, the server executes it as a single transaction even
124
+ if the string contains multiple <acronym>SQL</acronym> commands,
125
+ unless there are explicit <command>BEGIN</>/<command>COMMIT</>
126
+ commands included in the string to divide it into multiple
127
+ transactions. Also, <application>psql</application> only prints the
128
+ result of the last <acronym>SQL</acronym> command in the string.
129
+ This is different from the behavior when the same string is read from
130
+ a file or fed to <application>psql</application>'s standard input,
131
+ because then <application>psql</application> sends
132
+ each <acronym>SQL</acronym> command separately.
124
133
</para>
125
134
<para>
126
- Putting more than one command in the <option>-c</option> string often
127
- has unexpected results. This is a result of the fact that the whole
128
- string is sent to the server as a single query.
135
+ Because of this behavior, putting more than one command in a
136
+ single <option>-c</option> string often has unexpected results.
129
137
It's better to use repeated <option>-c</option> commands or feed
130
138
multiple commands to <application>psql</application>'s standard input,
131
139
either using <application>echo</application> as illustrated above, or
@@ -192,18 +200,26 @@ EOF
192
200
<term><option>--file=<replaceable class="parameter">filename</replaceable></></term>
193
201
<listitem>
194
202
<para>
195
- Use the file <replaceable class="parameter">filename</replaceable>
196
- as the source of commands instead of reading commands interactively.
197
- This option can be repeated and combined in any order with
198
- the <option>-c</option> option. After the commands in
199
- every <option>-c</option> command string and <option>-f</option> file
200
- are processed, <application>psql</application> terminates. This option
201
- is in many ways equivalent to the meta-command <command>\i</command>.
203
+ Read commands from the
204
+ file <replaceable class="parameter">filename</replaceable>,
205
+ rather than standard input.
206
+ This option can be repeated and combined in any order with
207
+ the <option>-c</option> option. When either <option>-c</option>
208
+ or <option>-f</option> is specified, <application>psql</application>
209
+ does not read commands from standard input; instead it terminates
210
+ after processing all the <option>-c</option> and <option>-f</option>
211
+ options in sequence.
212
+ Except for that, this option is largely equivalent to the
213
+ meta-command <command>\i</command>.
202
214
</para>
203
215
204
216
<para>
205
217
If <replaceable>filename</replaceable> is <literal>-</literal>
206
- (hyphen), then standard input is read.
218
+ (hyphen), then standard input is read until an EOF indication
219
+ or <command>\q</> meta-command. This can be used to intersperse
220
+ interactive input with input from files. Note however that Readline
221
+ is not used in this case (much as if <option>-n</option> had been
222
+ specified).
207
223
</para>
208
224
209
225
<para>
@@ -550,12 +566,13 @@ EOF
550
566
<term><option>--single-transaction</option></term>
551
567
<listitem>
552
568
<para>
553
- When <application>psql</application> executes commands from a script
554
- and/or a <option>-c</option> option, adding this option
555
- wraps <command>BEGIN</>/<command>COMMIT</> around all of those
556
- commands as a whole to execute them as a single transaction. This
557
- ensures that either all the commands complete successfully, or no
558
- changes are applied.
569
+ This option can only be used in combination with one or more
570
+ <option>-c</option> and/or <option>-f</option> options. It causes
571
+ <application>psql</application> to issue a <command>BEGIN</> command
572
+ before the first such option and a <command>COMMIT</> command after
573
+ the last one, thereby wrapping all the commands into a single
574
+ transaction. This ensures that either all the commands complete
575
+ successfully, or no changes are applied.
559
576
</para>
560
577
561
578
<para>
@@ -3799,16 +3816,6 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
3799
3816
<title>Notes</title>
3800
3817
3801
3818
<itemizedlist>
3802
- <listitem>
3803
- <para>
3804
- In an earlier life <application>psql</application> allowed the
3805
- first argument of a single-letter backslash command to start
3806
- directly after the command, without intervening whitespace.
3807
- As of <productname>PostgreSQL</productname> 8.4 this is no
3808
- longer allowed.
3809
- </para>
3810
- </listitem>
3811
-
3812
3819
<listitem>
3813
3820
<para><application>psql</application> works best with servers of the same
3814
3821
or an older major version. Backslash commands are particularly likely
@@ -3824,17 +3831,28 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
3824
3831
If you want to use <application>psql</application> to connect to several
3825
3832
servers of different major versions, it is recommended that you use the
3826
3833
newest version of <application>psql</application>. Alternatively, you
3827
- can keep a copy of <application>psql</application> from each major
3828
- version around and be sure to use the version that matches the
3834
+ can keep around a copy of <application>psql</application> from each
3835
+ major version and be sure to use the version that matches the
3829
3836
respective server. But in practice, this additional complication should
3830
3837
not be necessary.
3831
3838
</para>
3832
3839
</listitem>
3833
3840
3834
3841
<listitem>
3835
3842
<para>
3836
- Before <productname>PostgreSQL</productname> 9.6, <option>-c</option>
3837
- implied <option>-X</option>; this is no longer the case.
3843
+ Before <productname>PostgreSQL</productname> 9.6,
3844
+ the <option>-c</option> option implied <option>-X</option>
3845
+ (<option>--no-psqlrc</>); this is no longer the case.
3846
+ </para>
3847
+ </listitem>
3848
+
3849
+ <listitem>
3850
+ <para>
3851
+ Before <productname>PostgreSQL</productname> 8.4,
3852
+ <application>psql</application> allowed the
3853
+ first argument of a single-letter backslash command to start
3854
+ directly after the command, without intervening whitespace.
3855
+ Now, some whitespace is required.
3838
3856
</para>
3839
3857
</listitem>
3840
3858
</itemizedlist>
0 commit comments