database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

Doc: further clarify libpq's description of connection string URIs.

Browse Source 
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
This commit is contained in:
Tom Lane 2021-02-26 15:24:00 -05:00
parent 49076fd3ba
commit 5744931830
1 changed files with 26 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/src/sgml/libpq.sgml
View File

@ -865,7 +865,7 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
<para> <para>
Several <application>libpq</application> functions parse a user-specified string to obtain Several <application>libpq</application> functions parse a user-specified string to obtain
connection parameters. There are two accepted formats for these strings: connection parameters. There are two accepted formats for these strings:
plain <literal>keyword = value</literal> strings plain keyword/value strings
and URIs. URIs generally follow and URIs. URIs generally follow
<ulink url="https://tools.ietf.org/html/rfc3986">RFC <ulink url="https://tools.ietf.org/html/rfc3986">RFC
3986</ulink>, except that multi-host connection strings are allowed 3986</ulink>, except that multi-host connection strings are allowed
@ -876,12 +876,14 @@ PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
<title>Keyword/Value Connection Strings</title> <title>Keyword/Value Connection Strings</title>
<para> <para>
In the first format, each parameter setting is in the form In the keyword/value format, each parameter setting is in the form
<literal>keyword = value</literal>. Spaces around the equal sign are <replaceable>keyword</replaceable> <literal>=</literal>
<replaceable>value</replaceable>, 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 optional. To write an empty value, or a value containing spaces, surround it
with single quotes, e.g., <literal>keyword = 'a value'</literal>. Single with single quotes, for example <literal>keyword = 'a value'</literal>.
quotes and backslashes within Single quotes and backslashes within
the value must be escaped with a backslash, i.e., <literal>\'</literal> and a value must be escaped with a backslash, i.e., <literal>\'</literal> and
<literal>\\</literal>. <literal>\\</literal>.
</para> </para>
@ -904,7 +906,19 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
<para> <para>
The general form for a connection <acronym>URI</acronym> is: The general form for a connection <acronym>URI</acronym> is:
<synopsis> <synopsis>
postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&amp;...] postgresql://<optional><replaceable>userspec</replaceable>@</optional><optional><replaceable>hostspec</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>paramspec</replaceable></optional>
<phrase>where <replaceable>userspec</replaceable> is:</phrase>
<replaceable>user</replaceable><optional>:<replaceable>password</replaceable></optional>
<phrase>and <replaceable>hostspec</replaceable> is:</phrase>
<optional><replaceable>host</replaceable></optional><optional>:<replaceable>port</replaceable></optional><optional>,...</optional>
<phrase>and <replaceable>paramspec</replaceable> is:</phrase>
<replaceable>name</replaceable>=<replaceable>value</replaceable><optional>&amp;...</optional>
</synopsis> </synopsis>
</para> </para>
@ -977,7 +991,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
port component, in a single URI. A URI of the form port component, in a single URI. A URI of the form
<literal>postgresql://host1:port1,host2:port2,host3:port3/</literal> <literal>postgresql://host1:port1,host2:port2,host3:port3/</literal>
is equivalent to a connection string of the form is equivalent to a connection string of the form
<literal>host=host1,host2,host3 port=port1,port2,port3</literal>. Each <literal>host=host1,host2,host3 port=port1,port2,port3</literal>.
As further described below, each
host will be tried in turn until a connection is successfully established. host will be tried in turn until a connection is successfully established.
</para> </para>
</sect3> </sect3>
@ -988,8 +1003,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<para> <para>
It is possible to specify multiple hosts to connect to, so that they are 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 <literal>host</literal>, tried in the given order. In the Keyword/Value format, the <literal>host</literal>,
<literal>hostaddr</literal>, and <literal>port</literal> options accept a comma-separated <literal>hostaddr</literal>, and <literal>port</literal> options accept comma-separated
list of values. The same number of elements must be given in each lists of values. The same number of elements must be given in each
option that is specified, such option that is specified, such
that e.g., the first <literal>hostaddr</literal> corresponds to the first host name, that e.g., the first <literal>hostaddr</literal> corresponds to the first host name,
the second <literal>hostaddr</literal> corresponds to the second host name, and so the second <literal>hostaddr</literal> corresponds to the second host name, and so
@ -999,7 +1014,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<para> <para>
In the connection URI format, you can list multiple <literal>host:port</literal> pairs In the connection URI format, you can list multiple <literal>host:port</literal> pairs
separated by commas, in the <literal>host</literal> component of the URI. separated by commas in the <literal>host</literal> component of the URI.
</para> </para>
<para> <para>