/
psql-ref.sgml
5078 lines (4574 loc) · 205 KB
/
psql-ref.sgml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!--
doc/src/sgml/ref/psql-ref.sgml
PostgreSQL documentation
-->
<refentry id="app-psql">
<indexterm zone="app-psql">
<primary>psql</primary>
</indexterm>
<refmeta>
<refentrytitle><application>psql</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname><application>psql</application></refname>
<refpurpose>
<productname>PostgreSQL</productname> interactive terminal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>psql</command>
<arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
<arg choice="opt"><replaceable class="parameter">dbname</replaceable>
<arg choice="opt"><replaceable class="parameter">username</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>psql</application> is a terminal-based front-end to
<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 or from command line
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>
<refsect1 id="r1-app-psql-3">
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-a</option></term>
<term><option>--echo-all</option></term>
<listitem>
<para>
Print all nonempty input lines to standard output as they are read.
(This does not apply to lines read interactively.) This is
equivalent to setting the variable <varname>ECHO</varname> to
<literal>all</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-A</option></term>
<term><option>--no-align</option></term>
<listitem>
<para>
Switches to unaligned output mode. (The default output mode is
<literal>aligned</literal>.) This is equivalent to
<command>\pset format unaligned</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option></term>
<term><option>--echo-errors</option></term>
<listitem>
<para>
Print failed SQL commands to standard error output. This is
equivalent to setting the variable <varname>ECHO</varname> to
<literal>errors</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c <replaceable class="parameter">command</replaceable></option></term>
<term><option>--command=<replaceable class="parameter">command</replaceable></option></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. 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 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>\\</literal> is the separator meta-command.)
</para>
<para>
Each <acronym>SQL</acronym> command string passed
to <option>-c</option> is sent to the server as a single request.
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>/<command>COMMIT</command>
commands included in the string to divide it into multiple
transactions. (See <xref linkend="protocol-flow-multi-statement"/>
for more details about how the server handles multi-query strings.)
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>
Because of this behavior, putting more than one SQL 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
via a shell here-document, for example:
<programlisting>
psql <<EOF
\x
SELECT * FROM foo;
EOF
</programlisting></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--csv</option></term>
<listitem>
<para>
Switches to <acronym>CSV</acronym> (Comma-Separated Values) output
mode. This is equivalent to <command>\pset format csv</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
<term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
<listitem>
<para>
Specifies the name of the database to connect to. This is
equivalent to specifying <replaceable
class="parameter">dbname</replaceable> as the first non-option
argument on the command line. The <replaceable>dbname</replaceable>
can be a <link linkend="libpq-connstring">connection string</link>.
If so, connection string parameters will override any conflicting
command line options.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option></term>
<term><option>--echo-queries</option></term>
<listitem>
<para>
Copy all SQL commands sent to the server to standard output as well.
This is equivalent
to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-E</option></term>
<term><option>--echo-hidden</option></term>
<listitem>
<para>
Echo the actual queries generated by <command>\d</command> and other backslash
commands. You can use this to study <application>psql</application>'s
internal operations. This is equivalent to
setting the variable <varname>ECHO_HIDDEN</varname> to <literal>on</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f <replaceable class="parameter">filename</replaceable></option></term>
<term><option>--file=<replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
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 until an EOF indication
or <command>\q</command> 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>
Using this option is subtly different from writing <literal>psql
< <replaceable
class="parameter">filename</replaceable></literal>. In general,
both will do what you expect, but using <literal>-f</literal>
enables some nice features such as error messages with line
numbers. There is also a slight chance that using this option will
reduce the start-up overhead. On the other hand, the variant using
the shell's input redirection is (in theory) guaranteed to yield
exactly the same output you would have received had you entered
everything by hand.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-F <replaceable class="parameter">separator</replaceable></option></term>
<term><option>--field-separator=<replaceable class="parameter">separator</replaceable></option></term>
<listitem>
<para>
Use <replaceable class="parameter">separator</replaceable> as the
field separator for unaligned output. This is equivalent to
<command>\pset fieldsep</command> or <command>\f</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
<term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term>
<listitem>
<para>
Specifies the host name of the machine on which the
server is running. If the value begins
with a slash, it is used as the directory for the Unix-domain
socket.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-H</option></term>
<term><option>--html</option></term>
<listitem>
<para>
Switches to <acronym>HTML</acronym> output mode. This is
equivalent to <command>\pset format html</command> or the
<command>\H</command> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<term><option>--list</option></term>
<listitem>
<para>
List all available databases, then exit. Other non-connection
options are ignored. This is similar to the meta-command
<command>\list</command>.
</para>
<para>
When this option is used, <application>psql</application> will connect
to the database <literal>postgres</literal>, unless a different database
is named on the command line (option <option>-d</option> or non-option
argument, possibly via a service entry, but not via an environment
variable).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-L <replaceable class="parameter">filename</replaceable></option></term>
<term><option>--log-file=<replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
Write all query output into file <replaceable
class="parameter">filename</replaceable>, in addition to the
normal output destination.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--no-readline</option></term>
<listitem>
<para>
Do not use <application>Readline</application> for line editing and do
not use the command history.
This can be useful to turn off tab expansion when cutting and pasting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o <replaceable class="parameter">filename</replaceable></option></term>
<term><option>--output=<replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
Put all query output into file <replaceable
class="parameter">filename</replaceable>. This is equivalent to
the command <command>\o</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable class="parameter">port</replaceable></option></term>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
Specifies the TCP port or the local Unix-domain
socket file extension on which the server is listening for
connections. Defaults to the value of the <envar>PGPORT</envar>
environment variable or, if not set, to the port specified at
compile time, usually 5432.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P <replaceable class="parameter">assignment</replaceable></option></term>
<term><option>--pset=<replaceable class="parameter">assignment</replaceable></option></term>
<listitem>
<para>
Specifies printing options, in the style of
<command>\pset</command>. Note that here you
have to separate name and value with an equal sign instead of a
space. For example, to set the output format to <application>LaTeX</application>, you could write
<literal>-P format=latex</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<listitem>
<para>
Specifies that <application>psql</application> should do its work
quietly. By default, it prints welcome messages and various
informational output. If this option is used, none of this
happens. This is useful with the <option>-c</option> option.
This is equivalent to setting the variable <varname>QUIET</varname>
to <literal>on</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-R <replaceable class="parameter">separator</replaceable></option></term>
<term><option>--record-separator=<replaceable class="parameter">separator</replaceable></option></term>
<listitem>
<para>
Use <replaceable class="parameter">separator</replaceable> as the
record separator for unaligned output. This is equivalent to
<command>\pset recordsep</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option></term>
<term><option>--single-step</option></term>
<listitem>
<para>
Run in single-step mode. That means the user is prompted before
each command is sent to the server, with the option to cancel
execution as well. Use this to debug scripts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option></term>
<term><option>--single-line</option></term>
<listitem>
<para>
Runs in single-line mode where a newline terminates an SQL command, as a
semicolon does.
</para>
<note>
<para>
This mode is provided for those who insist on it, but you are not
necessarily encouraged to use it. In particular, if you mix
<acronym>SQL</acronym> and meta-commands on a line the order of
execution might not always be clear to the inexperienced user.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option></term>
<term><option>--tuples-only</option></term>
<listitem>
<para>
Turn off printing of column names and result row count footers,
etc. This is equivalent to <command>\t</command> or
<command>\pset tuples_only</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-T <replaceable class="parameter">table_options</replaceable></option></term>
<term><option>--table-attr=<replaceable class="parameter">table_options</replaceable></option></term>
<listitem>
<para>
Specifies options to be placed within the
<acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
<command>\pset tableattr</command> for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
<listitem>
<para>
Connect to the database as the user <replaceable
class="parameter">username</replaceable> instead of the default.
(You must have permission to do so, of course.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v <replaceable class="parameter">assignment</replaceable></option></term>
<term><option>--set=<replaceable class="parameter">assignment</replaceable></option></term>
<term><option>--variable=<replaceable class="parameter">assignment</replaceable></option></term>
<listitem>
<para>
Perform a variable assignment, like the <command>\set</command>
meta-command. Note that you must separate name and value, if
any, by an equal sign on the command line. To unset a variable,
leave off the equal sign. To set a variable with an empty value,
use the equal sign but leave off the value. These assignments are
done during command line processing, so variables that reflect
connection state will get overwritten later.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<term><option>--version</option></term>
<listitem>
<para>
Print the <application>psql</application> version and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</option></term>
<term><option>--no-password</option></term>
<listitem>
<para>
Never issue a password prompt. If the server requires password
authentication and a password is not available from other sources
such as a <filename>.pgpass</filename> file, the connection
attempt will fail. This option can be useful in batch jobs and
scripts where no user is present to enter a password.
</para>
<para>
Note that this option will remain set for the entire session,
and so it affects uses of the meta-command
<command>\connect</command> as well as the initial connection attempt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-W</option></term>
<term><option>--password</option></term>
<listitem>
<para>
Force <application>psql</application> to prompt for a
password before connecting to a database, even if the password will
not be used.
</para>
<para>
If the server requires password authentication and a password is not
available from other sources such as a <filename>.pgpass</filename>
file, <application>psql</application> will prompt for a
password in any case. However, <application>psql</application>
will waste a connection attempt finding out that the server wants a
password. In some cases it is worth typing <option>-W</option> to avoid
the extra connection attempt.
</para>
<para>
Note that this option will remain set for the entire session,
and so it affects uses of the meta-command
<command>\connect</command> as well as the initial connection attempt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<term><option>--expanded</option></term>
<listitem>
<para>
Turn on the expanded table formatting mode. This is equivalent to
<command>\x</command> or <command>\pset expanded</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-X,</option></term>
<term><option>--no-psqlrc</option></term>
<listitem>
<para>
Do not read the start-up file (neither the system-wide
<filename>psqlrc</filename> file nor the user's
<filename>~/.psqlrc</filename> file).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-z</option></term>
<term><option>--field-separator-zero</option></term>
<listitem>
<para>
Set the field separator for unaligned output to a zero byte. This is
equivalent to <command>\pset fieldsep_zero</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-0</option></term>
<term><option>--record-separator-zero</option></term>
<listitem>
<para>
Set the record separator for unaligned output to a zero byte. This is
useful for interfacing, for example, with <literal>xargs -0</literal>.
This is equivalent to <command>\pset recordsep_zero</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-1</option></term>
<term><option>--single-transaction</option></term>
<listitem>
<para>
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> command
before the first such option and a <command>COMMIT</command> 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>
If the commands themselves
contain <command>BEGIN</command>, <command>COMMIT</command>,
or <command>ROLLBACK</command>, this option will not have the desired
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>
<varlistentry>
<term><option>-?</option></term>
<term><option>--help[=<replaceable class="parameter">topic</replaceable>]</option></term>
<listitem>
<para>
Show help about <application>psql</application> and exit. The optional
<replaceable class="parameter">topic</replaceable> parameter (defaulting
to <literal>options</literal>) selects which part of <application>psql</application> is
explained: <literal>commands</literal> describes <application>psql</application>'s
backslash commands; <literal>options</literal> describes the command-line
options that can be passed to <application>psql</application>;
and <literal>variables</literal> shows help about <application>psql</application> configuration
variables.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit Status</title>
<para>
<application>psql</application> returns 0 to the shell if it
finished normally, 1 if a fatal error of its own occurs (e.g., out of memory,
file not found), 2 if the connection to the server went bad
and the session was not interactive, and 3 if an error occurred in a
script and the variable <varname>ON_ERROR_STOP</varname> was set.
</para>
</refsect1>
<refsect1>
<title>Usage</title>
<refsect2 id="r2-app-psql-connecting">
<title>Connecting to a Database</title>
<para>
<application>psql</application> is a regular
<productname>PostgreSQL</productname> client application. In order
to connect to a database you need to know the name of your target
database, the host name and port number of the server, and what user
name you want to connect as. <application>psql</application> can be
told about those parameters via command line options, namely
<option>-d</option>, <option>-h</option>, <option>-p</option>, and
<option>-U</option> respectively. If an argument is found that does
not belong to any option it will be interpreted as the database name
(or the user name, if the database name is already given). Not all
of these options are required; there are useful defaults. If you omit the host
name, <application>psql</application> will connect via a Unix-domain socket
to a server on the local host, or via TCP/IP to <literal>localhost</literal> on
machines that don't have Unix-domain sockets. The default port number is
determined at compile time.
Since the database server uses the same default, you will not have
to specify the port in most cases. The default user name is your
operating-system user name, as is the default database name.
Note that you cannot
just connect to any database under any user name. Your database
administrator should have informed you about your access rights.
</para>
<para>
When the defaults aren't quite right, you can save yourself
some typing by setting the environment variables
<envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
<envar>PGPORT</envar> and/or <envar>PGUSER</envar> to appropriate
values. (For additional environment variables, see <xref
linkend="libpq-envars"/>.) It is also convenient to have a
<filename>~/.pgpass</filename> file to avoid regularly having to type in
passwords. See <xref linkend="libpq-pgpass"/> for more information.
</para>
<para>
An alternative way to specify connection parameters is in a
<parameter>conninfo</parameter> string or
a <acronym>URI</acronym>, which is used instead of a database
name. This mechanism give you very wide control over the
connection. For example:
<programlisting>
$ <userinput>psql "service=myservice sslmode=require"</userinput>
$ <userinput>psql postgresql://dbmaster:5433/mydb?sslmode=require</userinput>
</programlisting>
This way you can also use <acronym>LDAP</acronym> for connection
parameter lookup as described in <xref linkend="libpq-ldap"/>.
See <xref linkend="libpq-paramkeywords"/> for more information on all the
available connection options.
</para>
<para>
If the connection could not be made for any reason (e.g., insufficient
privileges, server is not running on the targeted host, etc.),
<application>psql</application> will return an error and terminate.
</para>
<para>
If both standard input and standard output are a
terminal, then <application>psql</application> sets the client
encoding to <quote>auto</quote>, which will detect the
appropriate client encoding from the locale settings
(<envar>LC_CTYPE</envar> environment variable on Unix systems).
If this doesn't work out as expected, the client encoding can be
overridden using the environment
variable <envar>PGCLIENTENCODING</envar>.
</para>
</refsect2>
<refsect2 id="r2-app-psql-4">
<title>Entering SQL Commands</title>
<para>
In normal operation, <application>psql</application> provides a
prompt with the name of the database to which
<application>psql</application> is currently connected, followed by
the string <literal>=></literal>. For example:
<programlisting>
$ <userinput>psql testdb</userinput>
psql (&version;)
Type "help" for help.
testdb=>
</programlisting>
</para>
<para>
At the prompt, the user can type in <acronym>SQL</acronym> commands.
Ordinarily, input lines are sent to the server when a
command-terminating semicolon is reached. An end of line does not
terminate a command. Thus commands can be spread over several lines for
clarity. If the command was sent and executed without error, the results
of the command are displayed on the screen.
</para>
<para>
If untrusted users have access to a database that has not adopted a
<link linkend="ddl-schemas-patterns">secure schema usage pattern</link>,
begin your session by removing publicly-writable schemas
from <varname>search_path</varname>. One can
add <literal>options=-csearch_path=</literal> to the connection string or
issue <literal>SELECT pg_catalog.set_config('search_path', '',
false)</literal> before other SQL commands. This consideration is not
specific to <application>psql</application>; it applies to every interface
for executing arbitrary SQL commands.
</para>
<para>
Whenever a command is executed, <application>psql</application> also polls
for asynchronous notification events generated by
<link linkend="sql-listen"><command>LISTEN</command></link> and
<link linkend="sql-notify"><command>NOTIFY</command></link>.
</para>
<para>
While C-style block comments are passed to the server for
processing and removal, SQL-standard comments are removed by
<application>psql</application>.
</para>
</refsect2>
<refsect2 id="app-psql-meta-commands">
<title>Meta-Commands</title>
<para>
Anything you enter in <application>psql</application> that begins
with an unquoted backslash is a <application>psql</application>
meta-command that is processed by <application>psql</application>
itself. These commands make
<application>psql</application> more useful for administration or
scripting. Meta-commands are often called slash or backslash commands.
</para>
<para>
The format of a <application>psql</application> command is the backslash,
followed immediately by a command verb, then any arguments. The arguments
are separated from the command verb and each other by any number of
whitespace characters.
</para>
<para>
To include whitespace in an argument you can quote it with
single quotes. To include a single quote in an argument,
write two single quotes within single-quoted text.
Anything contained in single quotes is
furthermore subject to C-like substitutions for
<literal>\n</literal> (new line), <literal>\t</literal> (tab),
<literal>\b</literal> (backspace), <literal>\r</literal> (carriage return),
<literal>\f</literal> (form feed),
<literal>\</literal><replaceable>digits</replaceable> (octal), and
<literal>\x</literal><replaceable>digits</replaceable> (hexadecimal).
A backslash preceding any other character within single-quoted text
quotes that single character, whatever it is.
</para>
<para>
If an unquoted colon (<literal>:</literal>) followed by a
<application>psql</application> variable name appears within an argument, it is
replaced by the variable's value, as described in <xref
linkend="app-psql-interpolation"/> below.
The forms <literal>:'<replaceable>variable_name</replaceable>'</literal> and
<literal>:"<replaceable>variable_name</replaceable>"</literal> described there
work as well.
The <literal>:{?<replaceable>variable_name</replaceable>}</literal> syntax allows
testing whether a variable is defined. It is substituted by
TRUE or FALSE.
Escaping the colon with a backslash protects it from substitution.
</para>
<para>
Within an argument, text that is enclosed in backquotes
(<literal>`</literal>) is taken as a command line that is passed to the
shell. The output of the command (with any trailing newline removed)
replaces the backquoted text. Within the text enclosed in backquotes,
no special quoting or other processing occurs, except that appearances
of <literal>:<replaceable>variable_name</replaceable></literal> where
<replaceable>variable_name</replaceable> is a <application>psql</application> variable name
are replaced by the variable's value. Also, appearances of
<literal>:'<replaceable>variable_name</replaceable>'</literal> are replaced by the
variable's value suitably quoted to become a single shell command
argument. (The latter form is almost always preferable, unless you are
very sure of what is in the variable.) Because carriage return and line
feed characters cannot be safely quoted on all platforms, the
<literal>:'<replaceable>variable_name</replaceable>'</literal> form prints an
error message and does not substitute the variable value when such
characters appear in the value.
</para>
<para>
Some commands take an <acronym>SQL</acronym> identifier (such as a
table name) as argument. These arguments follow the syntax rules
of <acronym>SQL</acronym>: Unquoted letters are forced to
lowercase, while double quotes (<literal>"</literal>) protect letters
from case conversion and allow incorporation of whitespace into
the identifier. Within double quotes, paired double quotes reduce
to a single double quote in the resulting name. For example,
<literal>FOO"BAR"BAZ</literal> is interpreted as <literal>fooBARbaz</literal>,
and <literal>"A weird"" name"</literal> becomes <literal>A weird"
name</literal>.
</para>
<para>
Parsing for arguments stops at the end of the line, or when another
unquoted backslash is found. An unquoted backslash
is taken as the beginning of a new meta-command. The special
sequence <literal>\\</literal> (two backslashes) marks the end of
arguments and continues parsing <acronym>SQL</acronym> commands, if
any. That way <acronym>SQL</acronym> and
<application>psql</application> commands can be freely mixed on a
line. But in any case, the arguments of a meta-command cannot
continue beyond the end of the line.
</para>
<para>
Many of the meta-commands act on the <firstterm>current query buffer</firstterm>.
This is simply a buffer holding whatever SQL command text has been typed
but not yet sent to the server for execution. This will include previous
input lines as well as any text appearing before the meta-command on the
same line.
</para>
<para>
The following meta-commands are defined:
<variablelist>
<varlistentry>
<term><literal>\a</literal></term>
<listitem>
<para>
If the current table output format is unaligned, it is switched to aligned.
If it is not unaligned, it is set to unaligned. This command is
kept for backwards compatibility. See <command>\pset</command> for a
more general solution.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>\c</literal> or <literal>\connect [ -reuse-previous=<replaceable class="parameter">on|off</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">host</replaceable> ] [ <replaceable class="parameter">port</replaceable> ] | <replaceable class="parameter">conninfo</replaceable> ]</literal></term>
<listitem>
<para>
Establishes a new connection to a <productname>PostgreSQL</productname>
server. The connection parameters to use can be specified either
using a positional syntax (one or more of database name, user,
host, and port), or using a <replaceable>conninfo</replaceable>
connection string as detailed in
<xref linkend="libpq-connstring"/>. If no arguments are given, a
new connection is made using the same parameters as before.
</para>
<para>
Specifying any
of <replaceable class="parameter">dbname</replaceable>,
<replaceable class="parameter">username</replaceable>,
<replaceable class="parameter">host</replaceable> or
<replaceable class="parameter">port</replaceable>
as <literal>-</literal> is equivalent to omitting that parameter.
</para>
<para>
The new connection can re-use connection parameters from the previous
connection; not only database name, user, host, and port, but other
settings such as <replaceable>sslmode</replaceable>. By default,
parameters are re-used in the positional syntax, but not when
a <replaceable>conninfo</replaceable> string is given. Passing a
first argument of <literal>-reuse-previous=on</literal>
or <literal>-reuse-previous=off</literal> overrides that default. If
parameters are re-used, then any parameter not explicitly specified as
a positional parameter or in the <replaceable>conninfo</replaceable>
string is taken from the existing connection's parameters. An
exception is that if the <replaceable>host</replaceable> setting
is changed from its previous value using the positional syntax,
any <replaceable>hostaddr</replaceable> setting present in the
existing connection's parameters is dropped.
Also, any password used for the existing connection will be re-used
only if the user, host, and port settings are not changed.
When the command neither specifies nor reuses a particular parameter,
the <application>libpq</application> default is used.
</para>
<para>
If the new connection is successfully made, the previous
connection is closed.
If the connection attempt fails (wrong user name, access
denied, etc.), the previous connection will be kept if
<application>psql</application> is in interactive mode. But when
executing a non-interactive script, the old connection is closed
and an error is reported. That may or may not terminate the
script; if it does not, all database-accessing commands will fail
until another <literal>\connect</literal> command is successfully
executed. This distinction was chosen as
a user convenience against typos on the one hand, and a safety
mechanism that scripts are not accidentally acting on the
wrong database on the other hand.
Note that whenever a <literal>\connect</literal> command attempts
to re-use parameters, the values re-used are those of the last
successful connection, not of any failed attempts made subsequently.
However, in the case of a
non-interactive <literal>\connect</literal> failure, no parameters
are allowed to be re-used later, since the script would likely be
expecting the values from the failed <literal>\connect</literal>
to be re-used.
</para>
<para>
Examples:
</para>
<programlisting>
=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \c -reuse-previous=on sslmode=require -- changes only sslmode
=> \c postgresql://tom@localhost/mydb?application_name=myapp
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>\C [ <replaceable class="parameter">title</replaceable> ]</literal></term>
<listitem>
<para>
Sets the title of any tables being printed as the result of a
query or unset any such title. This command is equivalent to
<literal>\pset title <replaceable
class="parameter">title</replaceable></literal>. (The name of
this command derives from <quote>caption</quote>, as it was
previously only used to set the caption in an
<acronym>HTML</acronym> table.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>\cd [ <replaceable>directory</replaceable> ]</literal></term>
<listitem>
<para>
Changes the current working directory to
<replaceable>directory</replaceable>. Without argument, changes
to the current user's home directory.
</para>
<tip>
<para>
To print your current working directory, use <literal>\! pwd</literal>.
</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>\conninfo</literal></term>
<listitem>