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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.1. Database Connection Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq.html" title="Chapter 34. libpq — C Library" /><link rel="next" href="libpq-status.html" title="34.2. Connection Status Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.1. Database Connection Control Functions <a href="#LIBPQ-CONNECT" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">34.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></span></dt></dl></div><p>
The following functions deal with making a connection to a
<span class="productname">PostgreSQL</span> backend server. An
application program can have several backend connections open at
one time. (One reason to do that is to access more than one
database.) Each connection is represented by a
<code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which
is obtained from the function <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>,
<a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, or
<a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too
little memory even to allocate the <code class="structname">PGconn</code> object.
The <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a> function should be called to check
the return value for a successful connection before queries are sent
via the connection object.
</p><div class="warning"><h3 class="title">Warning</h3><p>
If untrusted users have access to a database that has not adopted a
<a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
begin each session by removing publicly-writable schemas from
<code class="varname">search_path</code>. One can set parameter key
word <code class="literal">options</code> to
value <code class="literal">-csearch_path=</code>. Alternately, one can
issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT
pg_catalog.set_config('search_path', '', false)")</code> after
connecting. This consideration is not specific
to <span class="application">libpq</span>; it applies to every interface for
executing arbitrary SQL commands.
</p></div><p>
</p><div class="warning"><h3 class="title">Warning</h3><p>
On Unix, forking a process with open libpq connections can lead to
unpredictable results because the parent and child processes share
the same sockets and operating system resources. For this reason,
such usage is not recommended, though doing an <code class="function">exec</code> from
the child process to load a new executable is safe.
</p></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONNECTDBPARAMS"><span class="term"><code class="function">PQconnectdbParams</code><a id="id-1.7.3.8.2.11.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTDBPARAMS" class="id_link">#</a></dt><dd><p>
Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQconnectdbParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
</pre><p>
</p><p>
This function opens a new database connection using the parameters taken
from two <code class="symbol">NULL</code>-terminated arrays. The first,
<code class="literal">keywords</code>, is defined as an array of strings, each one
being a key word. The second, <code class="literal">values</code>, gives the value
for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter
set can be extended without changing the function signature, so use of
this function (or its nonblocking analogs <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>
and <code class="function">PQconnectPoll</code>) is preferred for new application
programming.
</p><p>
The currently recognized parameter key words are listed in
<a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.
</p><p>
The passed arrays can be empty to use all default parameters, or can
contain one or more parameter settings. They must be matched in length.
Processing will stop at the first <code class="symbol">NULL</code> entry
in the <code class="literal">keywords</code> array.
Also, if the <code class="literal">values</code> entry associated with a
non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is
<code class="symbol">NULL</code> or an empty string, that entry is ignored and
processing continues with the next pair of array entries.
</p><p>
When <code class="literal">expand_dbname</code> is non-zero, the value for
the first <em class="parameter"><code>dbname</code></em> key word is checked to see
if it is a <em class="firstterm">connection string</em>. If so, it
is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection
parameters extracted from the string. The value is considered to
be a connection string, rather than just a database name, if it
contains an equal sign (<code class="literal">=</code>) or it begins with a
URI scheme designator. (More details on connection string formats
appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.) Only the first
occurrence of <em class="parameter"><code>dbname</code></em> is treated in this way;
any subsequent <em class="parameter"><code>dbname</code></em> parameter is processed
as a plain database name.
</p><p>
In general the parameter arrays are processed from start to end.
If any key word is repeated, the last value (that is
not <code class="symbol">NULL</code> or empty) is used. This rule applies in
particular when a key word found in a connection string conflicts
with one appearing in the <code class="literal">keywords</code> array. Thus,
the programmer may determine whether array entries can override or
be overridden by values taken from a connection string. Array
entries appearing before an expanded <em class="parameter"><code>dbname</code></em>
entry can be overridden by fields of the connection string, and in
turn those fields are overridden by array entries appearing
after <em class="parameter"><code>dbname</code></em> (but, again, only if those
entries supply non-empty values).
</p><p>
After processing all the array entries and any expanded connection
string, any connection parameters that remain unset are filled with
default values. If an unset parameter's corresponding environment
variable (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>) is set, its value is
used. If the environment variable is not set either, then the
parameter's built-in default value is used.
</p></dd><dt id="LIBPQ-PQCONNECTDB"><span class="term"><code class="function">PQconnectdb</code><a id="id-1.7.3.8.2.11.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTDB" class="id_link">#</a></dt><dd><p>
Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQconnectdb(const char *conninfo);
</pre><p>
</p><p>
This function opens a new database connection using the parameters taken
from the string <code class="literal">conninfo</code>.
</p><p>
The passed string can be empty to use all default parameters, or it can
contain one or more parameter settings separated by whitespace,
or it can contain a <acronym class="acronym">URI</acronym>.
See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for details.
</p></dd><dt id="LIBPQ-PQSETDBLOGIN"><span class="term"><code class="function">PQsetdbLogin</code><a id="id-1.7.3.8.2.11.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETDBLOGIN" class="id_link">#</a></dt><dd><p>
Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd);
</pre><p>
</p><p>
This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed
set of parameters. It has the same functionality except that the
missing parameters will always take on default values. Write <code class="symbol">NULL</code> or an
empty string for any one of the fixed parameters that is to be defaulted.
</p><p>
If the <em class="parameter"><code>dbName</code></em> contains
an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it
is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as
if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining
parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
</p><p>
<code class="literal">pgtty</code> is no longer used and any value passed will
be ignored.
</p></dd><dt id="LIBPQ-PQSETDB"><span class="term"><code class="function">PQsetdb</code><a id="id-1.7.3.8.2.11.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETDB" class="id_link">#</a></dt><dd><p>
Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
</pre><p>
</p><p>
This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers
for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters. It is provided
for backward compatibility with very old programs.
</p></dd><dt id="LIBPQ-PQCONNECTSTARTPARAMS"><span class="term"><code class="function">PQconnectStartParams</code><a id="id-1.7.3.8.2.11.5.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectStart</code><a id="id-1.7.3.8.2.11.5.2.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.11.5.3.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTSTARTPARAMS" class="id_link">#</a></dt><dd><p>
<a id="id-1.7.3.8.2.11.5.4.1.1" class="indexterm"></a>
Make a connection to the database server in a nonblocking manner.
</p><pre class="synopsis">
PGconn *PQconnectStartParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
PGconn *PQconnectStart(const char *conninfo);
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</pre><p>
</p><p>
These three functions are used to open a connection to a database server such
that your application's thread of execution is not blocked on remote I/O
whilst doing so. The point of this approach is that the waits for I/O to
complete can occur in the application's main loop, rather than down inside
<a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and so the
application can manage this operation in parallel with other activities.
</p><p>
With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made
using the parameters taken from the <code class="literal">keywords</code> and
<code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>,
as described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
</p><p>
With <code class="function">PQconnectStart</code>, the database connection is made
using the parameters taken from the string <code class="literal">conninfo</code> as
described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
</p><p>
Neither <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> nor <code class="function">PQconnectStart</code>
nor <code class="function">PQconnectPoll</code> will block, so long as a number of
restrictions are met:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The <code class="literal">hostaddr</code> parameter must be used appropriately
to prevent DNS queries from being made. See the documentation of
this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for details.
</p></li><li class="listitem"><p>
If you call <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>, ensure that the stream object
into which you trace will not block.
</p></li><li class="listitem"><p>
You must ensure that the socket is in the appropriate state
before calling <code class="function">PQconnectPoll</code>, as described below.
</p></li></ul></div><p>
</p><p>
To begin a nonblocking connection request,
call <code class="function">PQconnectStart</code>
or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>. If the result is null,
then <span class="application">libpq</span> has been unable to allocate a
new <code class="structname">PGconn</code> structure. Otherwise, a
valid <code class="structname">PGconn</code> pointer is returned (though not
yet representing a valid connection to the database). Next
call <code class="literal">PQstatus(conn)</code>. If the result
is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already
failed, typically because of invalid connection parameters.
</p><p>
If <code class="function">PQconnectStart</code>
or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> succeeds, the next stage
is to poll <span class="application">libpq</span> so that it can proceed with
the connection sequence.
Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the
socket underlying the database connection.
(Caution: do not assume that the socket remains the same
across <code class="function">PQconnectPoll</code> calls.)
Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned
<code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to
read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or
similar system function).
Then call <code class="function">PQconnectPoll(conn)</code> again.
Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned
<code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready
to write, then call <code class="function">PQconnectPoll(conn)</code> again.
On the first iteration, i.e., if you have yet to call
<code class="function">PQconnectPoll</code>, behave as if it last returned
<code class="symbol">PGRES_POLLING_WRITING</code>. Continue this loop until
<code class="function">PQconnectPoll(conn)</code> returns
<code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure
has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection
has been successfully made.
</p><p>
At any time during connection, the status of the connection can be
checked by calling <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the
connection procedure has failed; if the call returns <code class="function">CONNECTION_OK</code>, then the
connection is ready. Both of these states are equally detectable
from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur
during (and only during) an asynchronous connection procedure. These
indicate the current stage of the connection procedure and might be useful
to provide feedback to the user for example. These statuses are:
</p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECTION-STARTED"><span class="term"><code class="symbol">CONNECTION_STARTED</code></span> <a href="#LIBPQ-CONNECTION-STARTED" class="id_link">#</a></dt><dd><p>
Waiting for connection to be made.
</p></dd><dt id="LIBPQ-CONNECTION-MADE"><span class="term"><code class="symbol">CONNECTION_MADE</code></span> <a href="#LIBPQ-CONNECTION-MADE" class="id_link">#</a></dt><dd><p>
Connection OK; waiting to send.
</p></dd><dt id="LIBPQ-CONNECTION-AWAITING-RESPONSE"><span class="term"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></span> <a href="#LIBPQ-CONNECTION-AWAITING-RESPONSE" class="id_link">#</a></dt><dd><p>
Waiting for a response from the server.
</p></dd><dt id="LIBPQ-CONNECTION-AUTH-OK"><span class="term"><code class="symbol">CONNECTION_AUTH_OK</code></span> <a href="#LIBPQ-CONNECTION-AUTH-OK" class="id_link">#</a></dt><dd><p>
Received authentication; waiting for backend start-up to finish.
</p></dd><dt id="LIBPQ-CONNECTION-SSL-STARTUP"><span class="term"><code class="symbol">CONNECTION_SSL_STARTUP</code></span> <a href="#LIBPQ-CONNECTION-SSL-STARTUP" class="id_link">#</a></dt><dd><p>
Negotiating SSL encryption.
</p></dd><dt id="LIBPQ-CONNECTION-SETENV"><span class="term"><code class="symbol">CONNECTION_SETENV</code></span> <a href="#LIBPQ-CONNECTION-SETENV" class="id_link">#</a></dt><dd><p>
Negotiating environment-driven parameter settings.
</p></dd><dt id="LIBPQ-CONNECTION-CHECK-WRITABLE"><span class="term"><code class="symbol">CONNECTION_CHECK_WRITABLE</code></span> <a href="#LIBPQ-CONNECTION-CHECK-WRITABLE" class="id_link">#</a></dt><dd><p>
Checking if connection is able to handle write transactions.
</p></dd><dt id="LIBPQ-CONNECTION-CONSUME"><span class="term"><code class="symbol">CONNECTION_CONSUME</code></span> <a href="#LIBPQ-CONNECTION-CONSUME" class="id_link">#</a></dt><dd><p>
Consuming any remaining response messages on connection.
</p></dd></dl></div><p>
Note that, although these constants will remain (in order to maintain
compatibility), an application should never rely upon these occurring in a
particular order, or at all, or on the status always being one of these
documented values. An application might do something like this:
</p><pre class="programlisting">
switch(PQstatus(conn))
{
case CONNECTION_STARTED:
feedback = "Connecting...";
break;
case CONNECTION_MADE:
feedback = "Connected to server...";
break;
.
.
.
default:
feedback = "Connecting...";
}
</pre><p>
</p><p>
The <code class="literal">connect_timeout</code> connection parameter is ignored
when using <code class="function">PQconnectPoll</code>; it is the application's
responsibility to decide whether an excessive amount of time has elapsed.
Otherwise, <code class="function">PQconnectStart</code> followed by a
<code class="function">PQconnectPoll</code> loop is equivalent to
<a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
</p><p>
Note that when <code class="function">PQconnectStart</code>
or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null
pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are
finished with it, in order to dispose of the structure and any
associated memory blocks. This must be done even if the connection
attempt fails or is abandoned.
</p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNDEFAULTS" class="id_link">#</a></dt><dd><p>
Returns the default connection options.
</p><pre class="synopsis">
PQconninfoOption *PQconndefaults(void);
typedef struct
{
char *keyword; /* The keyword of the option */
char *envvar; /* Fallback environment variable name */
char *compiled; /* Fallback compiled in default value */
char *val; /* Option's current value, or NULL */
char *label; /* Label for field in connect dialog */
char *dispchar; /* Indicates how to display this field
in a connect dialog. Values are:
"" Display entered value as is
"*" Password field - hide value
"D" Debug option - don't show by default */
int dispsize; /* Field size in characters for dialog */
} PQconninfoOption;
</pre><p>
</p><p>
Returns a connection options array. This can be used to determine
all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their
current default values. The return value points to an array of
<code class="structname">PQconninfoOption</code> structures, which ends
with an entry having a null <code class="structfield">keyword</code> pointer. The
null pointer is returned if memory could not be allocated. Note that
the current default values (<code class="structfield">val</code> fields)
will depend on environment variables and other context. A
missing or invalid service file will be silently ignored. Callers
must treat the connection options data as read-only.
</p><p>
After processing the options array, free it by passing it to
<a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, a small amount of memory
is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>.
</p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFO" class="id_link">#</a></dt><dd><p>
Returns the connection options used by a live connection.
</p><pre class="synopsis">
PQconninfoOption *PQconninfo(PGconn *conn);
</pre><p>
</p><p>
Returns a connection options array. This can be used to determine
all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the
values that were used to connect to the server. The return
value points to an array of <code class="structname">PQconninfoOption</code>
structures, which ends with an entry having a null <code class="structfield">keyword</code>
pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also
apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>.
</p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFOPARSE" class="id_link">#</a></dt><dd><p>
Returns parsed connection options from the provided connection string.
</p><pre class="synopsis">
PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
</pre><p>
</p><p>
Parses a connection string and returns the resulting options as an
array; or returns <code class="symbol">NULL</code> if there is a problem with the connection
string. This function can be used to extract
the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided
connection string. The return value points to an array of
<code class="structname">PQconninfoOption</code> structures, which ends
with an entry having a null <code class="structfield">keyword</code> pointer.
</p><p>
All legal options will be present in the result array, but the
<code class="literal">PQconninfoOption</code> for any option not present
in the connection string will have <code class="literal">val</code> set to
<code class="literal">NULL</code>; default values are not inserted.
</p><p>
If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set
to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining
the problem. (It is also possible for <code class="literal">*errmsg</code> to be
set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;
this indicates an out-of-memory condition.)
</p><p>
After processing the options array, free it by passing it to
<a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, some memory
is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,
be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>.
</p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFINISH" class="id_link">#</a></dt><dd><p>
Closes the connection to the server. Also frees
memory used by the <code class="structname">PGconn</code> object.
</p><pre class="synopsis">
void PQfinish(PGconn *conn);
</pre><p>
</p><p>
Note that even if the server connection attempt fails (as
indicated by <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>), the application should call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>
to free the memory used by the <code class="structname">PGconn</code> object.
The <code class="structname">PGconn</code> pointer must not be used again after
<a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called.
</p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESET" class="id_link">#</a></dt><dd><p>
Resets the communication channel to the server.
</p><pre class="synopsis">
void PQreset(PGconn *conn);
</pre><p>
</p><p>
This function will close the connection
to the server and attempt to establish a new
connection, using all the same
parameters previously used. This might be useful for
error recovery if a working connection is lost.
</p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.11.2.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESETSTART" class="id_link">#</a></dt><dd><p>
Reset the communication channel to the server, in a nonblocking manner.
</p><pre class="synopsis">
int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);
</pre><p>
</p><p>
These functions will close the connection to the server and attempt to
establish a new connection, using all the same
parameters previously used. This can be useful for error recovery if a
working connection is lost. They differ from <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> (above) in that they
act in a nonblocking manner. These functions suffer from the same
restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
and <code class="function">PQconnectPoll</code>.
</p><p>
To initiate a connection reset, call
<a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has
failed. If it returns 1, poll the reset using
<code class="function">PQresetPoll</code> in exactly the same way as you
would create the connection using <code class="function">PQconnectPoll</code>.
</p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPINGPARAMS" class="id_link">#</a></dt><dd><p>
<a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the
server. It accepts connection parameters identical to those of
<a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above. It is not
necessary to supply correct user name, password, or database name
values to obtain the server status; however, if incorrect values
are provided, the server will log a failed connection attempt.
</p><pre class="synopsis">
PGPing PQpingParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
</pre><p>
The function returns one of the following values:
</p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPINGPARAMS-PQPING_OK"><span class="term"><code class="literal">PQPING_OK</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_OK" class="id_link">#</a></dt><dd><p>
The server is running and appears to be accepting connections.
</p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_REJECT"><span class="term"><code class="literal">PQPING_REJECT</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_REJECT" class="id_link">#</a></dt><dd><p>
The server is running but is in a state that disallows connections
(startup, shutdown, or crash recovery).
</p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE"><span class="term"><code class="literal">PQPING_NO_RESPONSE</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE" class="id_link">#</a></dt><dd><p>
The server could not be contacted. This might indicate that the
server is not running, or that there is something wrong with the
given connection parameters (for example, wrong port number), or
that there is a network connectivity problem (for example, a
firewall blocking the connection request).
</p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT"><span class="term"><code class="literal">PQPING_NO_ATTEMPT</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT" class="id_link">#</a></dt><dd><p>
No attempt was made to contact the server, because the supplied
parameters were obviously incorrect or there was some client-side
problem (for example, out of memory).
</p></dd></dl></div><p>
</p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPING" class="id_link">#</a></dt><dd><p>
<a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the
server. It accepts connection parameters identical to those of
<a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above. It is not
necessary to supply correct user name, password, or database name
values to obtain the server status; however, if incorrect values
are provided, the server will log a failed connection attempt.
</p><pre class="synopsis">
PGPing PQping(const char *conninfo);
</pre><p>
</p><p>
The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>.
</p></dd><dt id="LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
<code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override
<span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="34.19.2. Client Certificates">default
handling of encrypted client certificate key files</a> using
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting.
</p><pre class="synopsis">
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
</pre><p>
The application passes a pointer to a callback function with signature:
</p><pre class="programlisting">
int callback_fn(char *buf, int size, PGconn *conn);
</pre><p>
which <span class="application">libpq</span> will then call
<span class="emphasis"><em>instead of</em></span> its default
<code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The
callback should determine the password for the key and copy it to
result-buffer <em class="parameter"><code>buf</code></em> of size
<em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em>
must be null-terminated. The callback must return the length of the
password stored in <em class="parameter"><code>buf</code></em> excluding the null
terminator. On failure, the callback should set
<code class="literal">buf[0] = '\0'</code> and return 0. See
<code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in
<span class="application">libpq</span>'s source code for an example.
</p><p>
If the user specified an explicit key location,
its path will be in <code class="literal">conn->sslkey</code> when the callback
is invoked. This will be empty if the default key path is being used.
For keys that are engine specifiers, it is up to engine implementations
whether they use the <span class="productname">OpenSSL</span> password
callback or define their own handling.
</p><p>
The app callback may choose to delegate unhandled cases to
<code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>,
or call it first and try something else if it returns 0, or completely override it.
</p><p>
The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions,
<code class="function">longjmp(...)</code>, etc. It must return normally.
</p></dd><dt id="LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQgetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.15.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
<code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current
client certificate key password hook, or <code class="literal">NULL</code>
if none has been set.
</p><pre class="synopsis">
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
</pre><p>
</p></dd></dl></div><p>
</p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">34.1.1. Connection Strings <a href="#LIBPQ-CONNSTRING" class="id_link">#</a></h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a><p>
Several <span class="application">libpq</span> functions parse a user-specified string to obtain
connection parameters. There are two accepted formats for these strings:
plain keyword/value strings
and URIs. URIs generally follow
<a class="ulink" href="https://tools.ietf.org/html/rfc3986" target="_top">RFC
3986</a>, except that multi-host connection strings are allowed
as further described below.
</p><div class="sect3" id="LIBPQ-CONNSTRING-KEYWORD-VALUE"><div class="titlepage"><div><div><h4 class="title">34.1.1.1. Keyword/Value Connection Strings <a href="#LIBPQ-CONNSTRING-KEYWORD-VALUE" class="id_link">#</a></h4></div></div></div><p>
In the keyword/value format, each parameter setting is in the form
<em class="replaceable"><code>keyword</code></em> <code class="literal">=</code>
<em class="replaceable"><code>value</code></em>, with space(s) between settings.
Spaces around a setting's equal sign are
optional. To write an empty value, or a value containing spaces, surround it
with single quotes, for example <code class="literal">keyword = 'a value'</code>.
Single quotes and backslashes within
a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and
<code class="literal">\\</code>.
</p><p>
Example:
</p><pre class="programlisting">
host=localhost port=5432 dbname=mydb connect_timeout=10
</pre><p>
</p><p>
The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.
</p></div><div class="sect3" id="LIBPQ-CONNSTRING-URIS"><div class="titlepage"><div><div><h4 class="title">34.1.1.2. Connection URIs <a href="#LIBPQ-CONNSTRING-URIS" class="id_link">#</a></h4></div></div></div><p>
The general form for a connection <acronym class="acronym">URI</acronym> is:
</p><pre class="synopsis">
postgresql://[<span class="optional"><em class="replaceable"><code>userspec</code></em>@</span>][<span class="optional"><em class="replaceable"><code>hostspec</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>paramspec</code></em></span>]
<span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span>
<em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>]
<span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span>
[<span class="optional"><em class="replaceable"><code>host</code></em></span>][<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">,...</span>]
<span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span>
<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&...</span>]
</pre><p>
</p><p>
The <acronym class="acronym">URI</acronym> scheme designator can be either
<code class="literal">postgresql://</code> or <code class="literal">postgres://</code>. Each
of the remaining <acronym class="acronym">URI</acronym> parts is optional. The
following examples illustrate valid <acronym class="acronym">URI</acronym> syntax:
</p><pre class="programlisting">
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
</pre><p>
Values that would normally appear in the hierarchical part of
the <acronym class="acronym">URI</acronym> can alternatively be given as named
parameters. For example:
</p><pre class="programlisting">
postgresql:///mydb?host=localhost&port=5433
</pre><p>
All named parameters must match key words listed in
<a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>, except that for compatibility
with JDBC connection <acronym class="acronym">URI</acronym>s, instances
of <code class="literal">ssl=true</code> are translated into
<code class="literal">sslmode=require</code>.
</p><p>
The connection <acronym class="acronym">URI</acronym> needs to be encoded with <a class="ulink" href="https://tools.ietf.org/html/rfc3986#section-2.1" target="_top">percent-encoding</a>
if it includes symbols with special meaning in any of its parts. Here is
an example where the equal sign (<code class="literal">=</code>) is replaced with
<code class="literal">%3D</code> and the space character with
<code class="literal">%20</code>:
</p><pre class="programlisting">
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
</pre><p>
</p><p>
The host part may be either a host name or an IP address. To specify an
IPv6 address, enclose it in square brackets:
</p><pre class="synopsis">
postgresql://[2001:db8::1234]/database
</pre><p>
</p><p>
The host part is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>. In particular, a Unix-domain socket
connection is chosen if the host part is either empty or looks like an
absolute path name,
otherwise a TCP/IP connection is initiated. Note, however, that the
slash is a reserved character in the hierarchical part of the URI. So, to
specify a non-standard Unix-domain socket directory, either omit the host
part of the URI and specify the host as a named parameter, or
percent-encode the path in the host part of the URI:
</p><pre class="programlisting">
postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</pre><p>
</p><p>
It is possible to specify multiple host components, each with an optional
port component, in a single URI. A URI of the form
<code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>
is equivalent to a connection string of the form
<code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>.
As further described below, each
host will be tried in turn until a connection is successfully established.
</p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">34.1.1.3. Specifying Multiple Hosts <a href="#LIBPQ-MULTIPLE-HOSTS" class="id_link">#</a></h4></div></div></div><p>
It is possible to specify multiple hosts to connect to, so that they are
tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,
<code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated
lists of values. The same number of elements must be given in each
option that is specified, such
that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name,
the second <code class="literal">hostaddr</code> corresponds to the second host name, and so
forth. As an exception, if only one <code class="literal">port</code> is specified, it
applies to all the hosts.
</p><p>
In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs
separated by commas in the <code class="literal">host</code> component of the URI.
</p><p>
In either format, a single host name can translate to multiple network
addresses. A common example of this is a host that has both an IPv4 and
an IPv6 address.
</p><p>
When multiple hosts are specified, or when a single host name is
translated to multiple addresses, all the hosts and addresses will be
tried in order, until one succeeds. If none of the hosts can be reached,
the connection fails. If a connection is established successfully, but
authentication fails, the remaining hosts in the list are not tried.
</p><p>
If a password file is used, you can have different passwords for
different hosts. All the other connection options are the same for every
host in the list; it is not possible to e.g., specify different
usernames for different hosts.
</p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">34.1.2. Parameter Key Words <a href="#LIBPQ-PARAMKEYWORDS" class="id_link">#</a></h3></div></div></div><p>
The currently recognized parameter key words are:
</p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECT-HOST"><span class="term"><code class="literal">host</code></span> <a href="#LIBPQ-CONNECT-HOST" class="id_link">#</a></dt><dd><p>
Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a> If a host name looks like an absolute path
name, it specifies Unix-domain communication rather than TCP/IP
communication; the value is the name of the directory in which the
socket file is stored. (On Unix, an absolute path name begins with a
slash. On Windows, paths starting with drive letters are also
recognized.) If the host name starts with <code class="literal">@</code>, it is
taken as a Unix-domain socket in the abstract namespace (currently
supported on Linux and Windows).
The default behavior when <code class="literal">host</code> is not
specified, or is empty, is to connect to a Unix-domain
socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in
<code class="filename">/tmp</code> (or whatever socket directory was specified
when <span class="productname">PostgreSQL</span> was built). On Windows,
the default is to connect to <code class="literal">localhost</code>.
</p><p>
A comma-separated list of host names is also accepted, in which case
each host name in the list is tried in order; an empty item in the
list selects the default behavior as explained above. See
<a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.
</p></dd><dt id="LIBPQ-CONNECT-HOSTADDR"><span class="term"><code class="literal">hostaddr</code></span> <a href="#LIBPQ-CONNECT-HOSTADDR" class="id_link">#</a></dt><dd><p>
Numeric IP address of host to connect to. This should be in the
standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>. If
your machine supports IPv6, you can also use those addresses.
TCP/IP communication is
always used when a nonempty string is specified for this parameter.
If this parameter is not specified, the value of <code class="literal">host</code>
will be looked up to find the corresponding IP address — or, if
<code class="literal">host</code> specifies an IP address, that value will be
used directly.
</p><p>
Using <code class="literal">hostaddr</code> allows the
application to avoid a host name look-up, which might be important
in applications with time constraints. However, a host name is
required for GSSAPI or SSPI authentication
methods, as well as for <code class="literal">verify-full</code> SSL
certificate verification. The following rules are used:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If <code class="literal">host</code> is specified
without <code class="literal">hostaddr</code>, a host name lookup occurs.
(When using <code class="function">PQconnectPoll</code>, the lookup occurs
when <code class="function">PQconnectPoll</code> first considers this host
name, and it may cause <code class="function">PQconnectPoll</code> to block
for a significant amount of time.)
</p></li><li class="listitem"><p>
If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,
the value for <code class="literal">hostaddr</code> gives the server network address.
The connection attempt will fail if the authentication
method requires a host name.
</p></li><li class="listitem"><p>
If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,
the value for <code class="literal">hostaddr</code> gives the server network address.
The value for <code class="literal">host</code> is ignored unless the
authentication method requires it, in which case it will be
used as the host name.
</p></li></ul></div><p>
Note that authentication is likely to fail if <code class="literal">host</code>
is not the name of the server at network address <code class="literal">hostaddr</code>.
Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code>
are specified, <code class="literal">host</code>
is used to identify the connection in a password file (see
<a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
</p><p>
A comma-separated list of <code class="literal">hostaddr</code> values is also
accepted, in which case each host in the list is tried in order.
An empty item in the list causes the corresponding host name to be
used, or the default host name if that is empty as well. See
<a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.
</p><p>
Without either a host name or host address,
<span class="application">libpq</span> will connect using a local
Unix-domain socket; or on Windows, it will attempt to connect to
<code class="literal">localhost</code>.
</p></dd><dt id="LIBPQ-CONNECT-PORT"><span class="term"><code class="literal">port</code></span> <a href="#LIBPQ-CONNECT-PORT" class="id_link">#</a></dt><dd><p>
Port number to connect to at the server host, or socket file
name extension for Unix-domain
connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>
If multiple hosts were given in the <code class="literal">host</code> or
<code class="literal">hostaddr</code> parameters, this parameter may specify a
comma-separated list of ports of the same length as the host list, or
it may specify a single port number to be used for all hosts.
An empty string, or an empty item in a comma-separated list,
specifies the default port number established
when <span class="productname">PostgreSQL</span> was built.
</p></dd><dt id="LIBPQ-CONNECT-DBNAME"><span class="term"><code class="literal">dbname</code></span> <a href="#LIBPQ-CONNECT-DBNAME" class="id_link">#</a></dt><dd><p>
The database name. Defaults to be the same as the user name.
In certain contexts, the value is checked for extended
formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for more details on
those.
</p></dd><dt id="LIBPQ-CONNECT-USER"><span class="term"><code class="literal">user</code></span> <a href="#LIBPQ-CONNECT-USER" class="id_link">#</a></dt><dd><p>
<span class="productname">PostgreSQL</span> user name to connect as.
Defaults to be the same as the operating system name of the user
running the application.
</p></dd><dt id="LIBPQ-CONNECT-PASSWORD"><span class="term"><code class="literal">password</code></span> <a href="#LIBPQ-CONNECT-PASSWORD" class="id_link">#</a></dt><dd><p>
Password to be used if the server demands password authentication.
</p></dd><dt id="LIBPQ-CONNECT-PASSFILE"><span class="term"><code class="literal">passfile</code></span> <a href="#LIBPQ-CONNECT-PASSFILE" class="id_link">#</a></dt><dd><p>
Specifies the name of the file used to store passwords
(see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
Defaults to <code class="filename">~/.pgpass</code>, or
<code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.
(No error is reported if this file does not exist.)
</p></dd><dt id="LIBPQ-CONNECT-REQUIRE-AUTH"><span class="term"><code class="literal">require_auth</code></span> <a href="#LIBPQ-CONNECT-REQUIRE-AUTH" class="id_link">#</a></dt><dd><p>
Specifies the authentication method that the client requires from the
server. If the server does not use the required method to authenticate
the client, or if the authentication handshake is not fully completed by
the server, the connection will fail. A comma-separated list of methods
may also be provided, of which the server must use exactly one in order
for the connection to succeed. By default, any authentication method is
accepted, and the server is free to skip authentication altogether.
</p><p>
Methods may be negated with the addition of a <code class="literal">!</code>
prefix, in which case the server must <span class="emphasis"><em>not</em></span> attempt
the listed method; any other method is accepted, and the server is free
not to authenticate the client at all. If a comma-separated list is
provided, the server may not attempt <span class="emphasis"><em>any</em></span> of the
listed negated methods. Negated and non-negated forms may not be
combined in the same setting.
</p><p>
As a final special case, the <code class="literal">none</code> method requires the
server not to use an authentication challenge. (It may also be negated,
to require some form of authentication.)
</p><p>
The following methods may be specified:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
The server must request plaintext password authentication.
</p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
The server must request MD5 hashed password authentication.
</p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>
The server must either request a Kerberos handshake via
<acronym class="acronym">GSSAPI</acronym> or establish a
<acronym class="acronym">GSS</acronym>-encrypted channel (see also
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE">gssencmode</a>).
</p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>
The server must request Windows <acronym class="acronym">SSPI</acronym>
authentication.
</p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
The server must successfully complete a SCRAM-SHA-256 authentication
exchange with the client.
</p></dd><dt><span class="term"><code class="literal">none</code></span></dt><dd><p>
The server must not prompt the client for an authentication
exchange. (This does not prohibit client certificate authentication
via TLS, nor GSS authentication via its encrypted transport.)
</p></dd></dl></div><p>
</p></dd><dt id="LIBPQ-CONNECT-CHANNEL-BINDING"><span class="term"><code class="literal">channel_binding</code></span> <a href="#LIBPQ-CONNECT-CHANNEL-BINDING" class="id_link">#</a></dt><dd><p>
This option controls the client's use of channel binding. A setting
of <code class="literal">require</code> means that the connection must employ
channel binding, <code class="literal">prefer</code> means that the client will
choose channel binding if available, and <code class="literal">disable</code>
prevents the use of channel binding. The default
is <code class="literal">prefer</code> if
<span class="productname">PostgreSQL</span> is compiled with SSL support;
otherwise the default is <code class="literal">disable</code>.
</p><p>
Channel binding is a method for the server to authenticate itself to
the client. It is only supported over SSL connections
with <span class="productname">PostgreSQL</span> 11 or later servers using
the <code class="literal">SCRAM</code> authentication method.
</p></dd><dt id="LIBPQ-CONNECT-CONNECT-TIMEOUT"><span class="term"><code class="literal">connect_timeout</code></span> <a href="#LIBPQ-CONNECT-CONNECT-TIMEOUT" class="id_link">#</a></dt><dd><p>
Maximum time to wait while connecting, in seconds (write as a decimal integer,
e.g., <code class="literal">10</code>). Zero, negative, or not specified means
wait indefinitely. The minimum allowed timeout is 2 seconds, therefore
a value of <code class="literal">1</code> is interpreted as <code class="literal">2</code>.
This timeout applies separately to each host name or IP address.
For example, if you specify two hosts and <code class="literal">connect_timeout</code>
is 5, each host will time out if no connection is made within 5
seconds, so the total time spent waiting for a connection might be
up to 10 seconds.
</p></dd><dt id="LIBPQ-CONNECT-CLIENT-ENCODING"><span class="term"><code class="literal">client_encoding</code></span> <a href="#LIBPQ-CONNECT-CLIENT-ENCODING" class="id_link">#</a></dt><dd><p>
This sets the <code class="varname">client_encoding</code>
configuration parameter for this connection. In addition to
the values accepted by the corresponding server option, you
can use <code class="literal">auto</code> to determine the right
encoding from the current locale in the client
(<code class="envar">LC_CTYPE</code> environment variable on Unix
systems).
</p></dd><dt id="LIBPQ-CONNECT-OPTIONS"><span class="term"><code class="literal">options</code></span> <a href="#LIBPQ-CONNECT-OPTIONS" class="id_link">#</a></dt><dd><p>
Specifies command-line options to send to the server at connection
start. For example, setting this to <code class="literal">-c geqo=off</code> sets the
session's value of the <code class="varname">geqo</code> parameter to
<code class="literal">off</code>. Spaces within this string are considered to
separate command-line arguments, unless escaped with a backslash
(<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal
backslash. For a detailed discussion of the available
options, consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.
</p></dd><dt id="LIBPQ-CONNECT-APPLICATION-NAME"><span class="term"><code class="literal">application_name</code></span> <a href="#LIBPQ-CONNECT-APPLICATION-NAME" class="id_link">#</a></dt><dd><p>
Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>
configuration parameter.
</p></dd><dt id="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME"><span class="term"><code class="literal">fallback_application_name</code></span> <a href="#LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME" class="id_link">#</a></dt><dd><p>
Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.
This value will be used if no value has been given for
<code class="literal">application_name</code> via a connection parameter or the
<code class="envar">PGAPPNAME</code> environment variable. Specifying
a fallback name is useful in generic utility programs that
wish to set a default application name but allow it to be
overridden by the user.
</p></dd><dt id="LIBPQ-KEEPALIVES"><span class="term"><code class="literal">keepalives</code></span> <a href="#LIBPQ-KEEPALIVES" class="id_link">#</a></dt><dd><p>
Controls whether client-side TCP keepalives are used. The default
value is 1, meaning on, but you can change this to 0, meaning off,
if keepalives are not wanted. This parameter is ignored for
connections made via a Unix-domain socket.
</p></dd><dt id="LIBPQ-KEEPALIVES-IDLE"><span class="term"><code class="literal">keepalives_idle</code></span> <a href="#LIBPQ-KEEPALIVES-IDLE" class="id_link">#</a></dt><dd><p>
Controls the number of seconds of inactivity after which TCP should
send a keepalive message to the server. A value of zero uses the
system default. This parameter is ignored for connections made via a
Unix-domain socket, or if keepalives are disabled.
It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or
an equivalent socket option is available, and on Windows; on other
systems, it has no effect.
</p></dd><dt id="LIBPQ-KEEPALIVES-INTERVAL"><span class="term"><code class="literal">keepalives_interval</code></span> <a href="#LIBPQ-KEEPALIVES-INTERVAL" class="id_link">#</a></dt><dd><p>
Controls the number of seconds after which a TCP keepalive message
that is not acknowledged by the server should be retransmitted. A
value of zero uses the system default. This parameter is ignored for
connections made via a Unix-domain socket, or if keepalives are disabled.
It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or
an equivalent socket option is available, and on Windows; on other
systems, it has no effect.
</p></dd><dt id="LIBPQ-KEEPALIVES-COUNT"><span class="term"><code class="literal">keepalives_count</code></span> <a href="#LIBPQ-KEEPALIVES-COUNT" class="id_link">#</a></dt><dd><p>
Controls the number of TCP keepalives that can be lost before the
client's connection to the server is considered dead. A value of
zero uses the system default. This parameter is ignored for
connections made via a Unix-domain socket, or if keepalives are disabled.
It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or
an equivalent socket option is available; on other systems, it has no
effect.
</p></dd><dt id="LIBPQ-TCP-USER-TIMEOUT"><span class="term"><code class="literal">tcp_user_timeout</code></span> <a href="#LIBPQ-TCP-USER-TIMEOUT" class="id_link">#</a></dt><dd><p>
Controls the number of milliseconds that transmitted data may
remain unacknowledged before a connection is forcibly closed.
A value of zero uses the system default. This parameter is
ignored for connections made via a Unix-domain socket.
It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code>
is available; on other systems, it has no effect.
</p></dd><dt id="LIBPQ-CONNECT-REPLICATION"><span class="term"><code class="literal">replication</code></span> <a href="#LIBPQ-CONNECT-REPLICATION" class="id_link">#</a></dt><dd><p>
This option determines whether the connection should use the
replication protocol instead of the normal protocol. This is what
PostgreSQL replication connections as well as tools such as
<span class="application">pg_basebackup</span> use internally, but it can
also be used by third-party applications. For a description of the
replication protocol, consult <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>.
</p><p>
The following values, which are case-insensitive, are supported:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="literal">true</code>, <code class="literal">on</code>,
<code class="literal">yes</code>, <code class="literal">1</code>
</span></dt><dd><p>
The connection goes into physical replication mode.
</p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>
The connection goes into logical replication mode, connecting to
the database specified in the <code class="literal">dbname</code> parameter.
</p></dd><dt><span class="term">
<code class="literal">false</code>, <code class="literal">off</code>,
<code class="literal">no</code>, <code class="literal">0</code>
</span></dt><dd><p>
The connection is a regular one, which is the default behavior.
</p></dd></dl></div><p>
</p><p>
In physical or logical replication mode, only the simple query protocol
can be used.
</p></dd><dt id="LIBPQ-CONNECT-GSSENCMODE"><span class="term"><code class="literal">gssencmode</code></span> <a href="#LIBPQ-CONNECT-GSSENCMODE" class="id_link">#</a></dt><dd><p>
This option determines whether or with what priority a secure
<acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the
server. There are three modes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection
</p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e.,
in a credentials cache), first try
a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or
there are no credentials, try a
non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection. This is the
default when <span class="productname">PostgreSQL</span> has been
compiled with <acronym class="acronym">GSSAPI</acronym> support.
</p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection
</p></dd></dl></div><p>
</p><p>
<code class="literal">gssencmode</code> is ignored for Unix domain socket
communication. If <span class="productname">PostgreSQL</span> is compiled
without GSSAPI support, using the <code class="literal">require</code> option
will cause an error, while <code class="literal">prefer</code> will be accepted
but <span class="application">libpq</span> will not actually attempt
a <acronym class="acronym">GSSAPI</acronym>-encrypted
connection.<a id="id-1.7.3.8.4.2.1.21.2.2.7" class="indexterm"></a>
</p></dd><dt id="LIBPQ-CONNECT-SSLMODE"><span class="term"><code class="literal">sslmode</code></span> <a href="#LIBPQ-CONNECT-SSLMODE" class="id_link">#</a></dt><dd><p>
This option determines whether or with what priority a secure
<acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the
server. There are six modes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
only try a non-<acronym class="acronym">SSL</acronym> connection
</p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p>
first try a non-<acronym class="acronym">SSL</acronym> connection; if that
fails, try an <acronym class="acronym">SSL</acronym> connection
</p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
first try an <acronym class="acronym">SSL</acronym> connection; if that fails,
try a non-<acronym class="acronym">SSL</acronym> connection
</p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
only try an <acronym class="acronym">SSL</acronym> connection. If a root CA
file is present, verify the certificate in the same way as
if <code class="literal">verify-ca</code> was specified
</p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p>
only try an <acronym class="acronym">SSL</acronym> connection, and verify that
the server certificate is issued by a trusted
certificate authority (<acronym class="acronym">CA</acronym>)
</p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p>
only try an <acronym class="acronym">SSL</acronym> connection, verify that the
server certificate is issued by a
trusted <acronym class="acronym">CA</acronym> and that the requested server host name
matches that in the certificate
</p></dd></dl></div><p>
See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a detailed description of how
these options work.
</p><p>
<code class="literal">sslmode</code> is ignored for Unix domain socket
communication.
If <span class="productname">PostgreSQL</span> is compiled without SSL support,
using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or
<code class="literal">verify-full</code> will cause an error, while
options <code class="literal">allow</code> and <code class="literal">prefer</code> will be
accepted but <span class="application">libpq</span> will not actually attempt
an <acronym class="acronym">SSL</acronym>
connection.<a id="id-1.7.3.8.4.2.1.22.2.2.10" class="indexterm"></a>
</p><p>
Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible,
that will be used in preference to <acronym class="acronym">SSL</acronym>
encryption, regardless of the value of <code class="literal">sslmode</code>.
To force use of <acronym class="acronym">SSL</acronym> encryption in an
environment that has working <acronym class="acronym">GSSAPI</acronym>
infrastructure (such as a Kerberos server), also
set <code class="literal">gssencmode</code> to <code class="literal">disable</code>.
</p></dd><dt id="LIBPQ-CONNECT-REQUIRESSL"><span class="term"><code class="literal">requiressl</code></span> <a href="#LIBPQ-CONNECT-REQUIRESSL" class="id_link">#</a></dt><dd><p>
This option is deprecated in favor of the <code class="literal">sslmode</code>
setting.
</p><p>
If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server
is required (this is equivalent to <code class="literal">sslmode</code>
<code class="literal">require</code>). <span class="application">libpq</span> will then refuse
to connect if the server does not accept an
<acronym class="acronym">SSL</acronym> connection. If set to 0 (default),
<span class="application">libpq</span> will negotiate the connection type with
the server (equivalent to <code class="literal">sslmode</code>
<code class="literal">prefer</code>). This option is only available if
<span class="productname">PostgreSQL</span> is compiled with SSL support.
</p></dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><span class="term"><code class="literal">sslcompression</code></span> <a href="#LIBPQ-CONNECT-SSLCOMPRESSION" class="id_link">#</a></dt><dd><p>
If set to 1, data sent over SSL connections will be compressed. If
set to 0, compression will be disabled. The default is 0. This
parameter is ignored if a connection without SSL is made.
</p><p>
SSL compression is nowadays considered insecure and its use is no
longer recommended. <span class="productname">OpenSSL</span> 1.1.0 disables
compression by default, and many operating system distributions
disable it in prior versions as well, so setting this parameter to on
will not have any effect if the server does not accept compression.
<span class="productname">PostgreSQL</span> 14 disables compression
completely in the backend.
</p><p>
If security is not a primary concern, compression can improve
throughput if the network is the bottleneck. Disabling compression
can improve response time and throughput if CPU performance is the
limiting factor.
</p></dd><dt id="LIBPQ-CONNECT-SSLCERT"><span class="term"><code class="literal">sslcert</code></span> <a href="#LIBPQ-CONNECT-SSLCERT" class="id_link">#</a></dt><dd><p>
This parameter specifies the file name of the client SSL
certificate, replacing the default
<code class="filename">~/.postgresql/postgresql.crt</code>.
This parameter is ignored if an SSL connection is not made.
</p></dd><dt id="LIBPQ-CONNECT-SSLKEY"><span class="term"><code class="literal">sslkey</code></span> <a href="#LIBPQ-CONNECT-SSLKEY" class="id_link">#</a></dt><dd><p>
This parameter specifies the location for the secret key used for
the client certificate. It can either specify a file name that will
be used instead of the default
<code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key
obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are
<span class="productname">OpenSSL</span> loadable modules). An external engine
specification should consist of a colon-separated engine name and
an engine-specific key identifier. This parameter is ignored if an
SSL connection is not made.
</p></dd><dt id="LIBPQ-CONNECT-SSLPASSWORD"><span class="term"><code class="literal">sslpassword</code></span> <a href="#LIBPQ-CONNECT-SSLPASSWORD" class="id_link">#</a></dt><dd><p>
This parameter specifies the password for the secret key specified in
<code class="literal">sslkey</code>, allowing client certificate private keys
to be stored in encrypted form on disk even when interactive passphrase
input is not practical.
</p><p>
Specifying this parameter with any non-empty value suppresses the
<code class="literal">Enter PEM pass phrase:</code>
prompt that <span class="productname">OpenSSL</span> will emit by default
when an encrypted client certificate key is provided to
<code class="literal">libpq</code>.
</p><p>
If the key is not encrypted this parameter is ignored. The parameter
has no effect on keys specified by <span class="productname">OpenSSL</span>
engines unless the engine uses the <span class="productname">OpenSSL</span>
password callback mechanism for prompts.
</p><p>
There is no environment variable equivalent to this option, and no
facility for looking it up in <code class="filename">.pgpass</code>. It can be
used in a service file connection definition. Users with
more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and
tools like PKCS#11 or USB crypto offload devices.
</p></dd><dt id="LIBPQ-CONNECT-SSLCERTMODE"><span class="term"><code class="literal">sslcertmode</code></span> <a href="#LIBPQ-CONNECT-SSLCERTMODE" class="id_link">#</a></dt><dd><p>
This option determines whether a client certificate may be sent to the
server, and whether the server is required to request one. There are
three modes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
A client certificate is never sent, even if one is available
(default location or provided via
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCERT">sslcert</a>).
</p></dd><dt><span class="term"><code class="literal">allow</code> (default)</span></dt><dd><p>
A certificate may be sent, if the server requests one and the
client has one to send.
</p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
The server <span class="emphasis"><em>must</em></span> request a certificate. The
connection will fail if the client does not send a certificate and
the server successfully authenticates the client anyway.
</p></dd></dl></div><p>
</p><div class="note"><h3 class="title">Note</h3><p>
<code class="literal">sslcertmode=require</code> doesn't add any additional
security, since there is no guarantee that the server is validating
the certificate correctly; PostgreSQL servers generally request TLS
certificates from clients whether they validate them or not. The
option may be useful when troubleshooting more complicated TLS
setups.
</p></div></dd><dt id="LIBPQ-CONNECT-SSLROOTCERT"><span class="term"><code class="literal">sslrootcert</code></span> <a href="#LIBPQ-CONNECT-SSLROOTCERT" class="id_link">#</a></dt><dd><p>
This parameter specifies the name of a file containing SSL
certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).
If the file exists, the server's certificate will be verified
to be signed by one of these authorities. The default is
<code class="filename">~/.postgresql/root.crt</code>.
</p><p>
The special value <code class="literal">system</code> may be specified instead, in
which case the system's trusted CA roots will be loaded. The exact
locations of these root certificates differ by SSL implementation and
platform. For <span class="productname">OpenSSL</span> in particular, the
locations may be further modified by the <code class="envar">SSL_CERT_DIR</code>
and <code class="envar">SSL_CERT_FILE</code> environment variables.
</p><div class="note"><h3 class="title">Note</h3><p>
When using <code class="literal">sslrootcert=system</code>, the default
<code class="literal">sslmode</code> is changed to <code class="literal">verify-full</code>,
and any weaker setting will result in an error. In most cases it is
trivial for anyone to obtain a certificate trusted by the system for a
hostname they control, rendering <code class="literal">verify-ca</code> and all
weaker modes useless.
</p><p>
The magic <code class="literal">system</code> value will take precedence over a
local certificate file with the same name. If for some reason you find
yourself in this situation, use an alternative path like
<code class="literal">sslrootcert=./system</code> instead.
</p></div></dd><dt id="LIBPQ-CONNECT-SSLCRL"><span class="term"><code class="literal">sslcrl</code></span> <a href="#LIBPQ-CONNECT-SSLCRL" class="id_link">#</a></dt><dd><p>
This parameter specifies the file name of the SSL server certificate
revocation list (CRL). Certificates listed in this file, if it
exists, will be rejected while attempting to authenticate the
server's certificate. If neither
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is
taken as
<code class="filename">~/.postgresql/root.crl</code>.
</p></dd><dt id="LIBPQ-CONNECT-SSLCRLDIR"><span class="term"><code class="literal">sslcrldir</code></span> <a href="#LIBPQ-CONNECT-SSLCRLDIR" class="id_link">#</a></dt><dd><p>
This parameter specifies the directory name of the SSL server certificate
revocation list (CRL). Certificates listed in the files in this
directory, if it exists, will be rejected while attempting to
authenticate the server's certificate.
</p><p>
The directory needs to be prepared with the
<span class="productname">OpenSSL</span> command
<code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See
its documentation for details.
</p><p>
Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be
specified together.
</p></dd><dt id="LIBPQ-CONNECT-SSLSNI"><span class="term"><code class="literal">sslsni</code><a id="id-1.7.3.8.4.2.1.32.1.2" class="indexterm"></a></span> <a href="#LIBPQ-CONNECT-SSLSNI" class="id_link">#</a></dt><dd><p>
If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name
Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections.
By setting this parameter to 0, this is turned off.
</p><p>
The Server Name Indication can be used by SSL-aware proxies to route
connections without having to decrypt the SSL stream. (Note that this
requires a proxy that is aware of the PostgreSQL protocol handshake,
not just any SSL proxy.) However, <acronym class="acronym">SNI</acronym> makes the
destination host name appear in cleartext in the network traffic, so
it might be undesirable in some cases.
</p></dd><dt id="LIBPQ-CONNECT-REQUIREPEER"><span class="term"><code class="literal">requirepeer</code></span> <a href="#LIBPQ-CONNECT-REQUIREPEER" class="id_link">#</a></dt><dd><p>
This parameter specifies the operating-system user name of the
server, for example <code class="literal">requirepeer=postgres</code>.
When making a Unix-domain socket connection, if this
parameter is set, the client checks at the beginning of the
connection that the server process is running under the specified
user name; if it is not, the connection is aborted with an error.
This parameter can be used to provide server authentication similar
to that available with SSL certificates on TCP/IP connections.
(Note that if the Unix-domain socket is in
<code class="filename">/tmp</code> or another publicly writable location,
any user could start a server listening there. Use this parameter
to ensure that you are connected to a server run by a trusted user.)
This option is only supported on platforms for which the
<code class="literal">peer</code> authentication method is implemented; see
<a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a>.
</p></dd><dt id="LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_min_protocol_version</code></span> <a href="#LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
This parameter specifies the minimum SSL/TLS protocol version to allow
for the connection. Valid values are <code class="literal">TLSv1</code>,
<code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
<code class="literal">TLSv1.3</code>. The supported protocols depend on the
version of <span class="productname">OpenSSL</span> used, older versions
not supporting the most modern protocol versions. If not specified,
the default is <code class="literal">TLSv1.2</code>, which satisfies industry
best practices as of this writing.
</p></dd><dt id="LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_max_protocol_version</code></span> <a href="#LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
This parameter specifies the maximum SSL/TLS protocol version to allow
for the connection. Valid values are <code class="literal">TLSv1</code>,
<code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
<code class="literal">TLSv1.3</code>. The supported protocols depend on the
version of <span class="productname">OpenSSL</span> used, older versions
not supporting the most modern protocol versions. If not set, this
parameter is ignored and the connection will use the maximum bound
defined by the backend, if set. Setting the maximum protocol version
is mainly useful for testing or if some component has issues working
with a newer protocol.
</p></dd><dt id="LIBPQ-CONNECT-KRBSRVNAME"><span class="term"><code class="literal">krbsrvname</code></span> <a href="#LIBPQ-CONNECT-KRBSRVNAME" class="id_link">#</a></dt><dd><p>
Kerberos service name to use when authenticating with GSSAPI.
This must match the service name specified in the server
configuration for Kerberos authentication to succeed. (See also
<a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>.)
The default value is normally <code class="literal">postgres</code>,
but that can be changed when
building <span class="productname">PostgreSQL</span> via
the <code class="option">--with-krb-srvnam</code> option
of <span class="application">configure</span>.
In most environments, this parameter never needs to be changed.
Some Kerberos implementations might require a different service name,
such as Microsoft Active Directory which requires the service name
to be in upper case (<code class="literal">POSTGRES</code>).
</p></dd><dt id="LIBPQ-CONNECT-GSSLIB"><span class="term"><code class="literal">gsslib</code></span> <a href="#LIBPQ-CONNECT-GSSLIB" class="id_link">#</a></dt><dd><p>
GSS library to use for GSSAPI authentication.
Currently this is disregarded except on Windows builds that include
both GSSAPI and SSPI support. In that case, set
this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI
library for authentication instead of the default SSPI.
</p></dd><dt id="LIBPQ-CONNECT-GSSDELEGATION"><span class="term"><code class="literal">gssdelegation</code></span> <a href="#LIBPQ-CONNECT-GSSDELEGATION" class="id_link">#</a></dt><dd><p>
Forward (delegate) GSS credentials to the server. The default is
<code class="literal">0</code> which means credentials will not be forwarded
to the server. Set this to <code class="literal">1</code> to have credentials
forwarded when possible.
</p></dd><dt id="LIBPQ-CONNECT-SERVICE"><span class="term"><code class="literal">service</code></span> <a href="#LIBPQ-CONNECT-SERVICE" class="id_link">#</a></dt><dd><p>
Service name to use for additional parameters. It specifies a service
name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.
This allows applications to specify only a service name so connection parameters
can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>.
</p></dd><dt id="LIBPQ-CONNECT-TARGET-SESSION-ATTRS"><span class="term"><code class="literal">target_session_attrs</code></span> <a href="#LIBPQ-CONNECT-TARGET-SESSION-ATTRS" class="id_link">#</a></dt><dd><p>
This option determines whether the session must have certain
properties to be acceptable. It's typically used in combination
with multiple host names to select the first acceptable alternative
among several hosts. There are six modes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">any</code> (default)</span></dt><dd><p>
any successful connection is acceptable
</p></dd><dt><span class="term"><code class="literal">read-write</code></span></dt><dd><p>
session must accept read-write transactions by default (that
is, the server must not be in hot standby mode and
the <code class="varname">default_transaction_read_only</code> parameter
must be <code class="literal">off</code>)
</p></dd><dt><span class="term"><code class="literal">read-only</code></span></dt><dd><p>
session must not accept read-write transactions by default (the
converse)
</p></dd><dt><span class="term"><code class="literal">primary</code></span></dt><dd><p>
server must not be in hot standby mode
</p></dd><dt><span class="term"><code class="literal">standby</code></span></dt><dd><p>
server must be in hot standby mode
</p></dd><dt><span class="term"><code class="literal">prefer-standby</code></span></dt><dd><p>
first try to find a standby server, but if none of the listed
hosts is a standby server, try again in <code class="literal">any</code>
mode
</p></dd></dl></div><p>
</p></dd><dt id="LIBPQ-CONNECT-LOAD-BALANCE-HOSTS"><span class="term"><code class="literal">load_balance_hosts</code></span> <a href="#LIBPQ-CONNECT-LOAD-BALANCE-HOSTS" class="id_link">#</a></dt><dd><p>
Controls the order in which the client tries to connect to the available
hosts and addresses. Once a connection attempt is successful no other
hosts and addresses will be tried. This parameter is typically used in
combination with multiple host names or a DNS record that returns
multiple IPs. This parameter can be used in combination with
<a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS">target_session_attrs</a>
to, for example, load balance over standby servers only. Once successfully
connected, subsequent queries on the returned connection will all be
sent to the same server. There are currently two modes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code> (default)</span></dt><dd><p>
No load balancing across hosts is performed. Hosts are tried in
the order in which they are provided and addresses are tried in
the order they are received from DNS or a hosts file.
</p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>
Hosts and addresses are tried in random order. This value is mostly
useful when opening multiple connections at the same time, possibly
from different machines. This way connections can be load balanced
across multiple <span class="productname">PostgreSQL</span> servers.
</p><p>
While random load balancing, due to its random nature, will almost
never result in a completely uniform distribution, it statistically
gets quite close. One important aspect here is that this algorithm
uses two levels of random choices: First the hosts
will be resolved in random order. Then secondly, before resolving
the next host, all resolved addresses for the current host will be
tried in random order. This behaviour can skew the amount of
connections each node gets greatly in certain cases, for instance
when some hosts resolve to more addresses than others. But such a
skew can also be used on purpose, e.g. to increase the number of
connections a larger server gets by providing its hostname multiple
times in the host string.
</p><p>
When using this value it's recommended to also configure a reasonable
value for <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">connect_timeout</a>. Because then,
if one of the nodes that are used for load balancing is not responding,
a new node will be tried.
</p></dd></dl></div><p>
</p></dd></dl></div><p>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. <span class="application">libpq</span> — C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.2. Connection Status Functions</td></tr></table></div></body></html>
|
