@@ -796,7 +796,7 @@ PGPing PQping(const char *conninfo);
796
796
<para>
797
797
Several <application>libpq</application> functions parse a user-specified string to obtain
798
798
connection parameters. There are two accepted formats for these strings:
799
- plain <literal> keyword = value</literal> strings
799
+ plain keyword/value strings
800
800
and URIs. URIs generally follow
801
801
<ulink url="https://tools.ietf.org/html/rfc3986">RFC
802
802
3986</ulink>, except that multi-host connection strings are allowed
@@ -807,12 +807,14 @@ PGPing PQping(const char *conninfo);
807
807
<title>Keyword/Value Connection Strings</title>
808
808
809
809
<para>
810
- In the first format, each parameter setting is in the form
811
- <literal>keyword = value</literal>. Spaces around the equal sign are
810
+ In the keyword/value format, each parameter setting is in the form
811
+ <replaceable>keyword</replaceable> <literal>=</literal>
812
+ <replaceable>value</replaceable>, with space(s) between settings.
813
+ Spaces around a setting's equal sign are
812
814
optional. To write an empty value, or a value containing spaces, surround it
813
- with single quotes, e.g., <literal>keyword = 'a value'</literal>. Single
814
- quotes and backslashes within
815
- the value must be escaped with a backslash, i.e., <literal>\'</literal> and
815
+ with single quotes, for example <literal>keyword = 'a value'</literal>.
816
+ Single quotes and backslashes within
817
+ a value must be escaped with a backslash, i.e., <literal>\'</literal> and
816
818
<literal>\\</literal>.
817
819
</para>
818
820
@@ -835,7 +837,19 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
835
837
<para>
836
838
The general form for a connection <acronym>URI</acronym> is:
837
839
<synopsis>
838
- postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]
840
+ postgresql://<optional><replaceable>userspec</replaceable>@</optional><optional><replaceable>hostspec</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>paramspec</replaceable></optional>
841
+
842
+ <phrase>where <replaceable>userspec</replaceable> is:</phrase>
843
+
844
+ <replaceable>user</replaceable><optional>:<replaceable>password</replaceable></optional>
845
+
846
+ <phrase>and <replaceable>hostspec</replaceable> is:</phrase>
847
+
848
+ <optional><replaceable>host</replaceable></optional><optional>:<replaceable>port</replaceable></optional><optional>,...</optional>
849
+
850
+ <phrase>and <replaceable>paramspec</replaceable> is:</phrase>
851
+
852
+ <replaceable>name</replaceable>=<replaceable>value</replaceable><optional>&...</optional>
839
853
</synopsis>
840
854
</para>
841
855
@@ -903,7 +917,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
903
917
port component, in a single URI. A URI of the form
904
918
<literal>postgresql://host1:port1,host2:port2,host3:port3/</literal>
905
919
is equivalent to a connection string of the form
906
- <literal>host=host1,host2,host3 port=port1,port2,port3</literal>. Each
920
+ <literal>host=host1,host2,host3 port=port1,port2,port3</literal>.
921
+ As further described below, each
907
922
host will be tried in turn until a connection is successfully established.
908
923
</para>
909
924
</sect3>
@@ -914,8 +929,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
914
929
<para>
915
930
It is possible to specify multiple hosts to connect to, so that they are
916
931
tried in the given order. In the Keyword/Value format, the <literal>host</literal>,
917
- <literal>hostaddr</literal>, and <literal>port</literal> options accept a comma-separated
918
- list of values. The same number of elements must be given in each
932
+ <literal>hostaddr</literal>, and <literal>port</literal> options accept comma-separated
933
+ lists of values. The same number of elements must be given in each
919
934
option that is specified, such
920
935
that e.g., the first <literal>hostaddr</literal> corresponds to the first host name,
921
936
the second <literal>hostaddr</literal> corresponds to the second host name, and so
@@ -925,7 +940,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
925
940
926
941
<para>
927
942
In the connection URI format, you can list multiple <literal>host:port</literal> pairs
928
- separated by commas, in the <literal>host</literal> component of the URI.
943
+ separated by commas in the <literal>host</literal> component of the URI.
929
944
</para>
930
945
931
946
<para>
0 commit comments