Skip to content

Commit 2d612ab

Browse files
peterepetere
committed
libpq: URI parsing fixes
Drop special handling of host component with slashes to mean Unix-domain socket. Specify it as separate parameter or using percent-encoding now. Allow omitting username, password, and port even if the corresponding designators are present in URI. Handle percent-encoding in query parameter keywords. Alex Shulgin some documentation improvements by myself
1 parent 388d251 commit 2d612ab

File tree

4 files changed

+269
-256
lines changed

4 files changed

+269
-256
lines changed

‎doc/src/sgml/libpq.sgml‎

Lines changed: 118 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -711,6 +711,124 @@ PGPing PQping(const char *conninfo);
711711
</variablelist>
712712
</para>
713713

714+
<sect2 id="libpq-connstring">
715+
<title>Connection Strings</title>
716+
717+
<indexterm zone="libpq-connstring">
718+
<primary><literal>conninfo</literal></primary>
719+
</indexterm>
720+
721+
<indexterm zone="libpq-connstring">
722+
<primary><literal>URI</literal></primary>
723+
</indexterm>
724+
725+
<para>
726+
Several <application>libpq</> functions parse a user-specified string to obtain
727+
connection parameters. There are two accepted formats for these strings:
728+
plain <literal>keyword = value</literal> strings
729+
and <ulink url="http://www.ietf.org/rfc/rfc3986.txt">RFC
730+
3986</ulink> URIs.
731+
</para>
732+
733+
<sect3>
734+
<title>Keyword/Value Connection Strings</title>
735+
736+
<para>
737+
In the first format, each parameter setting is in the form
738+
<literal>keyword = value</literal>. Spaces around the equal sign are
739+
optional. To write an empty value, or a value containing spaces, surround it
740+
with single quotes, e.g., <literal>keyword = 'a value'</literal>. Single
741+
quotes and backslashes within
742+
the value must be escaped with a backslash, i.e., <literal>\'</literal> and
743+
<literal>\\</literal>.
744+
</para>
745+
746+
<para>
747+
Example:
748+
<programlisting>
749+
host=localhost port=5432 dbname=mydb connect_timeout=10
750+
</programlisting>
751+
</para>
752+
753+
<para>
754+
The recognized parameter key words are listed in <xref
755+
linkend="libpq-paramkeywords">.
756+
</para>
757+
</sect3>
758+
759+
<sect3>
760+
<title>Connection URIs</title>
761+
762+
<para>
763+
The general form for a connection <acronym>URI</acronym> is:
764+
<synopsis>
765+
postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&amp;...]
766+
</synopsis>
767+
</para>
768+
769+
<para>
770+
The <acronym>URI</acronym> scheme designator can be either
771+
<literal>postgresql://</literal> or <literal>postgres://</literal>. Each
772+
of the <acronym>URI</acronym> parts is optional. The following examples
773+
illustrate valid <acronym>URI</acronym> syntax uses:
774+
<programlisting>
775+
postgresql://
776+
postgresql://localhost
777+
postgresql://localhost:5433
778+
postgresql://localhost/mydb
779+
postgresql://user@localhost
780+
postgresql://user:secret@localhost
781+
postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
782+
</programlisting>
783+
Components of the hierarchical part of the <acronym>URI</acronym> can also
784+
be given as parameters. For example:
785+
<programlisting>
786+
postgresql:///mydb?host=localhost&amp;port=5433
787+
</programlisting>
788+
</para>
789+
790+
<para>
791+
Percent-encoding may be used to include symbols with special meaning in any
792+
of the <acronym>URI</acronym> parts.
793+
</para>
794+
795+
<para>
796+
Any connection parameters not corresponding to key words listed in <xref
797+
linkend="libpq-paramkeywords"> are ignored and a warning message about them
798+
is sent to <filename>stderr</filename>.
799+
</para>
800+
801+
<para>
802+
For improved compatibility with JDBC connection <acronym>URI</acronym>s,
803+
instances of parameter <literal>ssl=true</literal> are translated into
804+
<literal>sslmode=require</literal>.
805+
</para>
806+
807+
<para>
808+
The host part may be either hostname or an IP address. To specify an
809+
IPv6 host address, enclose it in square brackets:
810+
<synopsis>
811+
postgresql://[2001:db8::1234]/database
812+
</synopsis>
813+
</para>
814+
815+
<para>
816+
The host component is interpreted as described for the parameter <xref
817+
linkend="libpq-connect-host">. In particular, a Unix-domain socket
818+
connection is chosen if the host part is either empty or starts with a
819+
slash, otherwise a TCP/IP connection is initiated. Note, however, that the
820+
slash is a reserved character in the hierarchical part of the URI. So, to
821+
specify a non-standard Unix-domain socket directory, either omit the host
822+
specification in the URI and specify the host as a parameter, or
823+
percent-encode the path in the host component of the URI:
824+
<programlisting>
825+
postgresql:///dbname?host=/var/lib/postgresql
826+
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
827+
</programlisting>
828+
</para>
829+
</sect3>
830+
</sect2>
831+
714832
<sect2 id="libpq-paramkeywords">
715833
<title>Parameter Key Words</title>
716834

@@ -1220,107 +1338,6 @@ PGPing PQping(const char *conninfo);
12201338
</variablelist>
12211339
</para>
12221340
</sect2>
1223-
1224-
<sect2 id="libpq-connstring">
1225-
<title>Connection Strings</title>
1226-
1227-
<indexterm zone="libpq-connstring">
1228-
<primary><literal>conninfo</literal></primary>
1229-
</indexterm>
1230-
1231-
<indexterm zone="libpq-connstring">
1232-
<primary><literal>URI</literal></primary>
1233-
</indexterm>
1234-
1235-
<para>
1236-
Several <application>libpq</> functions parse a user-specified string to obtain
1237-
connection parameters. There are two accepted formats for these strings:
1238-
plain <literal>keyword = value</literal> strings, and URIs.
1239-
</para>
1240-
1241-
<para>
1242-
In the first format, each parameter setting is in the form
1243-
<literal>keyword = value</literal>. Spaces around the equal sign are
1244-
optional. To write an empty value, or a value containing spaces, surround it
1245-
with single quotes, e.g., <literal>keyword = 'a value'</literal>. Single
1246-
quotes and backslashes within
1247-
the value must be escaped with a backslash, i.e., <literal>\'</literal> and
1248-
<literal>\\</literal>.
1249-
</para>
1250-
1251-
<para>
1252-
The currently recognized parameter key words are listed in
1253-
<xref linkend="libpq-paramkeywords">.
1254-
</para>
1255-
1256-
<para>
1257-
The general form for connection <acronym>URI</acronym> is the
1258-
following:
1259-
<synopsis>
1260-
postgresql://[user[:password]@][unix-socket][:port[/dbname]][?param1=value1&amp;...]
1261-
postgresql://[user[:password]@][net-location][:port][/dbname][?param1=value1&amp;...]
1262-
</synopsis>
1263-
</para>
1264-
1265-
<para>
1266-
The <acronym>URI</acronym> designator can be either
1267-
<literal>postgresql://</literal> or <literal>postgres://</literal> and
1268-
each of the <acronym>URI</acronym> parts is optional. The following
1269-
examples illustrate valid <acronym>URI</acronym> syntax uses:
1270-
<synopsis>
1271-
postgresql://
1272-
postgresql://localhost
1273-
postgresql://localhost:5433
1274-
postgresql://localhost/mydb
1275-
postgresql://user@localhost
1276-
postgresql://user:secret@localhost
1277-
postgresql://other@localhost/otherdb
1278-
</synopsis>
1279-
</para>
1280-
1281-
<para>
1282-
Percent-encoding may be used to include a symbol with special meaning in
1283-
any of the <acronym>URI</acronym> parts.
1284-
</para>
1285-
1286-
<para>
1287-
Additional connection parameters may optionally follow the base <acronym>URI</acronym>.
1288-
Any connection parameters not corresponding to key words listed
1289-
in <xref linkend="libpq-paramkeywords"> are ignored and a warning message
1290-
about them is sent to <filename>stderr</filename>.
1291-
</para>
1292-
1293-
<para>
1294-
For improved compatibility with JDBC connection <acronym>URI</acronym>
1295-
syntax, instances of parameter <literal>ssl=true</literal> are translated
1296-
into <literal>sslmode=require</literal> (see above.)
1297-
</para>
1298-
1299-
<para>
1300-
The host part may be either hostname or an IP address. To specify an
1301-
IPv6 host address, enclose it in square brackets:
1302-
<synopsis>
1303-
postgresql://[2001:db8::1234]/database
1304-
</synopsis>
1305-
As a special case, a host part which starts with <symbol>/</symbol> is
1306-
treated as a local Unix socket directory to look for the connection
1307-
socket special file:
1308-
<synopsis>
1309-
postgresql:///path/to/pgsql/socket/dir
1310-
</synopsis>
1311-
The whole connection string up to the extra parameters designator
1312-
(<symbol>?</symbol>) or the port designator (<symbol>:</symbol>) is treated
1313-
as the absolute path to the socket directory
1314-
(<literal>/path/to/pgsql/socket/dir</literal> in this example.) To specify
1315-
a non-default database name in this case you can use either of the following
1316-
syntaxes:
1317-
<synopsis>
1318-
postgresql:///path/to/pgsql/socket/dir?dbname=otherdb
1319-
postgresql:///path/to/pgsql/socket/dir:5432/otherdb
1320-
</synopsis>
1321-
</para>
1322-
</sect2>
1323-
13241341
</sect1>
13251342

13261343
<sect1 id="libpq-status">

0 commit comments

Comments
 (0)