diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index c43cd9e4a7..aa246e6447 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -122,36 +122,54 @@ PGconn *PQconnectdbParams(const char * const *keywords,
.
-
- When expand_dbname is non-zero, the
- dbname key word value is allowed to be recognized
- as a connection string. Only the first occurrence of
- dbname is expanded this way, any subsequent
- dbname value is processed as plain database name. More
- details on the possible connection string formats appear in
- .
-
-
The passed arrays can be empty to use all default parameters, or can
- contain one or more parameter settings. They should be matched in length.
- Processing will stop at the first NULL element
+ contain one or more parameter settings. They must be matched in length.
+ Processing will stop at the first NULL entry
in the keywords array.
+ Also, if the values entry associated with a
+ non-NULL keywords entry is
+ NULL or an empty string, that entry is ignored and
+ processing continues with the next pair of array entries.
- If any parameter is NULL or an empty string, the corresponding
- environment variable (see ) is checked.
- If the environment variable is not set either, then the indicated
- built-in defaults are used.
+ When expand_dbname is non-zero, the value for
+ the first dbname key word is checked to see
+ if it is a connection string. If so, it
+ is expanded
into the individual connection
+ parameters extracted from the string. The value is considered to
+ be a connection string, rather than just a database name, if it
+ contains an equal sign (=) or it begins with a
+ URI scheme designator. (More details on connection string formats
+ appear in .) Only the first
+ occurrence of dbname is treated in this way;
+ any subsequent dbname parameter is processed
+ as a plain database name.
- In general key words are processed from the beginning of these arrays in index
- order. The effect of this is that when key words are repeated, the last processed
- value is retained. Therefore, through careful placement of the
- dbname key word, it is possible to determine what may
- be overridden by a conninfo string, and what may not.
+ In general the parameter arrays are processed from start to end.
+ If any key word is repeated, the last value (that is
+ not NULL or empty) is used. This rule applies in
+ particular when a key word found in a connection string conflicts
+ with one appearing in the keywords array. Thus,
+ the programmer may determine whether array entries can override or
+ be overridden by values taken from a connection string. Array
+ entries appearing before an expanded dbname
+ entry can be overridden by fields of the connection string, and in
+ turn those fields are overridden by array entries appearing
+ after dbname (but, again, only if those
+ entries supply non-empty values).
+
+
+
+ After processing all the array entries and any expanded connection
+ string, any connection parameters that remain unset are filled with
+ default values. If an unset parameter's corresponding environment
+ variable (see ) is set, its value is
+ used. If the environment variable is not set either, then the
+ parameter's built-in default value is used.
@@ -886,15 +904,15 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
The general form for a connection URI is:
-postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
+postgresql://[user[:password]@][host][: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:
+ of the remaining URI parts is optional. The
+ following examples illustrate valid URI syntax:
postgresql://
postgresql://localhost
@@ -905,11 +923,17 @@ postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
- Components of the hierarchical part of the URI can also
- be given as parameters. For example:
+ Values that would normally appear in the hierarchical part of
+ the URI can alternatively be given as named
+ parameters. For example:
postgresql:///mydb?host=localhost&port=5433
+ All named parameters must match key words listed in
+ , except that for compatibility
+ with JDBC connection URIs, instances
+ of ssl=true are translated into
+ sslmode=require.
@@ -925,35 +949,23 @@ postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
- 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 host name or an IP address. To specify an
- IPv6 host address, enclose it in square brackets:
+ The host part may be either a host name or an IP address. To specify an
+ IPv6 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 looks like an
absolute path name,
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:
+ part of the URI and specify the host as a named parameter, or
+ percent-encode the path in the host part of the URI:
postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname