From 2d612abd4d330cd9d3f5a3f5936b20a6e837a69c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 28 May 2012 22:44:34 +0300 Subject: 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 --- doc/src/sgml/libpq.sgml | 219 ++++++++++++++++++++++++++---------------------- 1 file changed, 118 insertions(+), 101 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 8a820ac0074..ef1d95ed204 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -711,6 +711,124 @@ PGPing PQping(const char *conninfo); + + Connection Strings + + + conninfo + + + + URI + + + + Several libpq functions parse a user-specified string to obtain + connection parameters. There are two accepted formats for these strings: + plain keyword = value strings + and RFC + 3986 URIs. + + + + Keyword/Value Connection Strings + + + In the first format, each parameter setting is in the form + keyword = value. Spaces around the equal sign are + optional. To write an empty value, or a value containing spaces, surround it + with single quotes, e.g., keyword = 'a value'. Single + quotes and backslashes within + the value must be escaped with a backslash, i.e., \' and + \\. + + + + Example: + +host=localhost port=5432 dbname=mydb connect_timeout=10 + + + + + The recognized parameter key words are listed in . + + + + + Connection URIs + + + The general form for a connection URI is: + +postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] + + + + + The URI scheme designator can be either + postgresql:// or postgres://. Each + of the URI parts is optional. The following examples + illustrate valid URI syntax uses: + +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 + + Components of the hierarchical part of the URI can also + be given as parameters. For example: + +postgresql:///mydb?host=localhost&port=5433 + + + + + Percent-encoding may be used to include symbols with special meaning in any + of the URI parts. + + + + Any connection parameters not corresponding to key words listed in are ignored and a warning message about them + is sent to stderr. + + + + For improved compatibility with JDBC connection URIs, + instances of parameter ssl=true are translated into + sslmode=require. + + + + The host part may be either hostname or an IP address. To specify an + IPv6 host address, enclose it in square brackets: + +postgresql://[2001:db8::1234]/database + + + + + The host component is interpreted as described for the parameter . In particular, a Unix-domain socket + connection is chosen if the host part is either empty or starts with a + slash, 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 + specification in the URI and specify the host as a parameter, or + percent-encode the path in the host component of the URI: + +postgresql:///dbname?host=/var/lib/postgresql +postgresql://%2Fvar%2Flib%2Fpostgresql/dbname + + + + + Parameter Key Words @@ -1220,107 +1338,6 @@ PGPing PQping(const char *conninfo); - - - Connection Strings - - - conninfo - - - - URI - - - - Several libpq functions parse a user-specified string to obtain - connection parameters. There are two accepted formats for these strings: - plain keyword = value strings, and URIs. - - - - In the first format, each parameter setting is in the form - keyword = value. Spaces around the equal sign are - optional. To write an empty value, or a value containing spaces, surround it - with single quotes, e.g., keyword = 'a value'. Single - quotes and backslashes within - the value must be escaped with a backslash, i.e., \' and - \\. - - - - The currently recognized parameter key words are listed in - . - - - - The general form for connection URI is the - following: - -postgresql://[user[:password]@][unix-socket][:port[/dbname]][?param1=value1&...] -postgresql://[user[:password]@][net-location][:port][/dbname][?param1=value1&...] - - - - - The URI designator can be either - postgresql:// or postgres:// and - each of the URI parts is optional. The following - examples illustrate valid URI syntax uses: - -postgresql:// -postgresql://localhost -postgresql://localhost:5433 -postgresql://localhost/mydb -postgresql://user@localhost -postgresql://user:secret@localhost -postgresql://other@localhost/otherdb - - - - - Percent-encoding may be used to include a symbol with special meaning in - any of the URI parts. - - - - Additional connection parameters may optionally follow the base URI. - Any connection parameters not corresponding to key words listed - in are ignored and a warning message - about them is sent to stderr. - - - - For improved compatibility with JDBC connection URI - syntax, instances of parameter ssl=true are translated - into sslmode=require (see above.) - - - - The host part may be either hostname or an IP address. To specify an - IPv6 host address, enclose it in square brackets: - -postgresql://[2001:db8::1234]/database - - As a special case, a host part which starts with / is - treated as a local Unix socket directory to look for the connection - socket special file: - -postgresql:///path/to/pgsql/socket/dir - - The whole connection string up to the extra parameters designator - (?) or the port designator (:) is treated - as the absolute path to the socket directory - (/path/to/pgsql/socket/dir in this example.) To specify - a non-default database name in this case you can use either of the following - syntaxes: - -postgresql:///path/to/pgsql/socket/dir?dbname=otherdb -postgresql:///path/to/pgsql/socket/dir:5432/otherdb - - - - -- cgit v1.2.3