Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit fb1e218

Browse files
committed
Doc: further clarify libpq's description of connection string URIs.
Break the synopsis into named parts to make it less confusing. Make more than zero effort at applying SGML markup. Do a bit of copy-editing of nearby text. The synopsis revision is by Alvaro Herrera and Paul Förster, the rest is my fault. Back-patch to v10 where multi-host connection strings appeared. Discussion: https://postgr.es/m/6E752D6B-487C-463E-B6E2-C32E7FB007EA@gmail.com
1 parent 9e9b5c0 commit fb1e218

File tree

1 file changed

+26
-11
lines changed

1 file changed

+26
-11
lines changed

doc/src/sgml/libpq.sgml

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -796,7 +796,7 @@ PGPing PQping(const char *conninfo);
796796
<para>
797797
Several <application>libpq</application> functions parse a user-specified string to obtain
798798
connection parameters. There are two accepted formats for these strings:
799-
plain <literal>keyword = value</literal> strings
799+
plain keyword/value strings
800800
and URIs. URIs generally follow
801801
<ulink url="https://tools.ietf.org/html/rfc3986">RFC
802802
3986</ulink>, except that multi-host connection strings are allowed
@@ -807,12 +807,14 @@ PGPing PQping(const char *conninfo);
807807
<title>Keyword/Value Connection Strings</title>
808808

809809
<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
812814
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
816818
<literal>\\</literal>.
817819
</para>
818820

@@ -835,7 +837,19 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
835837
<para>
836838
The general form for a connection <acronym>URI</acronym> is:
837839
<synopsis>
838-
postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&amp;...]
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>&amp;...</optional>
839853
</synopsis>
840854
</para>
841855

@@ -903,7 +917,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
903917
port component, in a single URI. A URI of the form
904918
<literal>postgresql://host1:port1,host2:port2,host3:port3/</literal>
905919
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
907922
host will be tried in turn until a connection is successfully established.
908923
</para>
909924
</sect3>
@@ -914,8 +929,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
914929
<para>
915930
It is possible to specify multiple hosts to connect to, so that they are
916931
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
919934
option that is specified, such
920935
that e.g., the first <literal>hostaddr</literal> corresponds to the first host name,
921936
the second <literal>hostaddr</literal> corresponds to the second host name, and so
@@ -925,7 +940,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
925940

926941
<para>
927942
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.
929944
</para>
930945

931946
<para>

0 commit comments

Comments
 (0)