diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 0ec501e..568e456 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -119,7 +119,9 @@ PGconn *PQconnectdbParams(const char * const *keywords, When expand_dbname is non-zero, the dbname key word value is allowed to be recognized - as a conninfo string. See below for details. + as a connection string. More details on that, as well as a list of + currently recognized parameter key words, appears in + . @@ -130,507 +132,6 @@ PGconn *PQconnectdbParams(const char * const *keywords, - The currently recognized parameter key words are: - - - - host - - - Name of host to connect to.host name - If this begins with a slash, it specifies Unix-domain - communication rather than TCP/IP communication; the value is the - name of the directory in which the socket file is stored. The - default behavior when host is not specified - is to connect to a Unix-domain - socketUnix domain socket in - /tmp (or whatever socket directory was specified - when PostgreSQL was built). On machines without - Unix-domain sockets, the default is to connect to localhost. - - - - - - hostaddr - - - Numeric IP address of host to connect to. This should be in the - standard IPv4 address format, e.g., 172.28.40.9. If - your machine supports IPv6, you can also use those addresses. - TCP/IP communication is - always used when a nonempty string is specified for this parameter. - - - - Using hostaddr instead of host allows the - application to avoid a host name look-up, which might be important - in applications with time constraints. However, a host name is - required for Kerberos, GSSAPI, or SSPI authentication - methods, as well as for verify-full SSL - certificate verification. The following rules are used: - - - - If host is specified without hostaddr, - a host name lookup occurs. - - - - - If hostaddr is specified without host, - the value for hostaddr gives the server network address. - The connection attempt will fail if the authentication - method requires a host name. - - - - - If both host and hostaddr are specified, - the value for hostaddr gives the server network address. - The value for host is ignored unless the - authentication method requires it, in which case it will be - used as the host name. - - - - Note that authentication is likely to fail if host - is not the name of the server at network address hostaddr. - Also, note that host rather than hostaddr - is used to identify the connection in ~/.pgpass (see - ). - - - - Without either a host name or host address, - libpq will connect using a - local Unix-domain socket; or on machines without Unix-domain - sockets, it will attempt to connect to localhost. - - - - - - port - - - Port number to connect to at the server host, or socket file - name extension for Unix-domain - connections.port - - - - - - dbname - - - The database name. Defaults to be the same as the user name. - - - - - - user - - - PostgreSQL user name to connect as. - Defaults to be the same as the operating system name of the user - running the application. - - - - - - password - - - Password to be used if the server demands password authentication. - - - - - - connect_timeout - - - Maximum wait for connection, in seconds (write as a decimal integer - string). Zero or not specified means wait indefinitely. It is not - recommended to use a timeout of less than 2 seconds. - - - - - - client_encoding - - - This sets the client_encoding - configuration parameter for this connection. In addition to - the values accepted by the corresponding server option, you - can use auto to determine the right - encoding from the current locale in the client - (LC_CTYPE environment variable on Unix - systems). - - - - - - options - - - Adds command-line options to send to the server at run-time. - For example, setting this to -c geqo=off sets the - session's value of the geqo parameter to - off. For a detailed discussion of the available - options, consult . - - - - - - application_name - - - Specifies a value for the - configuration parameter. - - - - - - fallback_application_name - - - Specifies a fallback value for the configuration parameter. - This value will be used if no value has been given for - application_name via a connection parameter or the - PGAPPNAME environment variable. Specifying - a fallback name is useful in generic utility programs that - wish to set a default application name but allow it to be - overridden by the user. - - - - - - keepalives - - - Controls whether client-side TCP keepalives are used. The default - value is 1, meaning on, but you can change this to 0, meaning off, - if keepalives are not wanted. This parameter is ignored for - connections made via a Unix-domain socket. - - - - - - keepalives_idle - - - Controls the number of seconds of inactivity after which TCP should - send a keepalive message to the server. A value of zero uses the - system default. This parameter is ignored for connections made via a - Unix-domain socket, or if keepalives are disabled. It is only supported - on systems where the TCP_KEEPIDLE or TCP_KEEPALIVE - socket option is available, and on Windows; on other systems, it has no - effect. - - - - - - keepalives_interval - - - Controls the number of seconds after which a TCP keepalive message - that is not acknowledged by the server should be retransmitted. A - value of zero uses the system default. This parameter is ignored for - connections made via a Unix-domain socket, or if keepalives are disabled. - It is only supported on systems where the TCP_KEEPINTVL - socket option is available, and on Windows; on other systems, it has no - effect. - - - - - - keepalives_count - - - Controls the number of TCP keepalives that can be lost before the - client's connection to the server is considered dead. A value of - zero uses the system default. This parameter is ignored for - connections made via a Unix-domain socket, or if keepalives are disabled. - It is only supported on systems where the TCP_KEEPCNT - socket option is available; on other systems, it has no effect. - - - - - - tty - - - Ignored (formerly, this specified where to send server debug output). - - - - - - sslmode - - - This option determines whether or with what priority a secure - SSL TCP/IP connection will be negotiated with the - server. There are six modes: - - - - disable - - - only try a non-SSL connection - - - - - - allow - - - first try a non-SSL connection; if that - fails, try an SSL connection - - - - - - prefer (default) - - - first try an SSL connection; if that fails, - try a non-SSL connection - - - - - - require - - - only try an SSL connection. If a root CA - file is present, verify the certificate in the same way as - if verify-ca was specified - - - - - - verify-ca - - - only try an SSL connection, and verify that - the server certificate is issued by a trusted - certificate authority (CA) - - - - - - verify-full - - - only try an SSL connection, verify that the - server certificate is issued by a - trusted CA and that the server host name - matches that in the certificate - - - - - - See for a detailed description of how - these options work. - - - - sslmode is ignored for Unix domain socket - communication. - If PostgreSQL is compiled without SSL support, - using options require, verify-ca, or - verify-full will cause an error, while - options allow and prefer will be - accepted but libpq will not actually attempt - an SSL - connection.SSLwith libpq - - - - - - requiressl - - - This option is deprecated in favor of the sslmode - setting. - - - - If set to 1, an SSL connection to the server - is required (this is equivalent to sslmode - require). libpq will then refuse - to connect if the server does not accept an - SSL connection. If set to 0 (default), - libpq will negotiate the connection type with - the server (equivalent to sslmode - prefer). This option is only available if - PostgreSQL is compiled with SSL support. - - - - - - sslcompression - - - If set to 1 (default), data sent over SSL connections will be - compressed (this requires OpenSSL version - 0.9.8 or later). - If set to 0, compression will be disabled (this requires - OpenSSL 1.0.0 or later). - This parameter is ignored if a connection without SSL is made, - or if the version of OpenSSL used does not support - it. - - - Compression uses CPU time, but can improve throughput if - the network is the bottleneck. - Disabling compression can improve response time and throughput - if CPU performance is the limiting factor. - - - - - - sslcert - - - This parameter specifies the file name of the client SSL - certificate, replacing the default - ~/.postgresql/postgresql.crt. - This parameter is ignored if an SSL connection is not made. - - - - - - sslkey - - - This parameter specifies the location for the secret key used for - the client certificate. It can either specify a file name that will - be used instead of the default - ~/.postgresql/postgresql.key, or it can specify a key - obtained from an external engine (engines are - OpenSSL loadable modules). An external engine - specification should consist of a colon-separated engine name and - an engine-specific key identifier. This parameter is ignored if an - SSL connection is not made. - - - - - - sslrootcert - - - This parameter specifies the name of a file containing SSL - certificate authority (CA) certificate(s). - If the file exists, the server's certificate will be verified - to be signed by one of these authorities. The default is - ~/.postgresql/root.crt. - - - - - - sslcrl - - - This parameter specifies the file name of the SSL certificate - revocation list (CRL). Certificates listed in this file, if it - exists, will be rejected while attempting to authenticate the - server's certificate. The default is - ~/.postgresql/root.crl. - - - - - - requirepeer - - - This parameter specifies the operating-system user name of the - server, for example requirepeer=postgres. - When making a Unix-domain socket connection, if this - parameter is set, the client checks at the beginning of the - connection that the server process is running under the specified - user name; if it is not, the connection is aborted with an error. - This parameter can be used to provide server authentication similar - to that available with SSL certificates on TCP/IP connections. - (Note that if the Unix-domain socket is in - /tmp or another publicly writable location, - any user could start a server listening there. Use this parameter - to ensure that you are connected to a server run by a trusted user.) - This option is only supported on platforms for which the - peer authentication method is implemented; see - . - - - - - - krbsrvname - - - Kerberos service name to use when authenticating with Kerberos 5 - or GSSAPI. - This must match the service name specified in the server - configuration for Kerberos authentication to succeed. (See also - and .) - - - - - - gsslib - - - GSS library to use for GSSAPI authentication. Only used on Windows. - Set to gssapi to force libpq to use the GSSAPI - library for authentication instead of the default SSPI. - - - - - - service - - - Service name to use for additional parameters. It specifies a service - name in pg_service.conf that holds additional connection parameters. - This allows applications to specify only a service name so connection parameters - can be centrally maintained. See . - - - - - If any parameter is unspecified, then the corresponding environment variable (see ) is checked. If the environment variable is not set either, @@ -638,20 +139,11 @@ PGconn *PQconnectdbParams(const char * const *keywords, - If expand_dbname is non-zero and - dbname contains an = sign, it - is taken as a conninfo string in exactly the same way as - if it had been passed to PQconnectdb(see below). Previously - processed key words will be overridden by key words in the - conninfo string. - - - - 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 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. @@ -675,19 +167,13 @@ PGconn *PQconnectdb(const char *conninfo); The passed string can be empty to use all default parameters, or it can - contain one or more parameter settings separated by whitespace. - 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 \\. - + contain one or more parameter settings separated by whitespace, + or it can contain a URI. + See for details. + - - The currently recognized parameter key words are the same as above. - - + + @@ -714,10 +200,11 @@ PGconn *PQsetdbLogin(const char *pghost, - If the dbName contains an = sign, it + If the dbName contains + an = sign or has a valid connection URI prefix, it is taken as a conninfo string in exactly the same way as if it had been passed to PQconnectdb, and the remaining - parameters are then applied as above. + parameters are then applied as specified in . @@ -795,7 +282,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); The hostaddr and host parameters are used appropriately to ensure that name and reverse name queries are not made. See the documentation of - these parameters under PQconnectdbParams above for details. + these parameters in for details. @@ -6428,6 +5915,607 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + + 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 the same as listed below. + + + + The general form for connection URI is the + following: + +postgresql://username:password@hostname:port/database?param1=value1&param2=value2&... + + + + + 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 + + + + + Additional connection parameters may optionally follow the base URI. + Any connection parameters not corresponding to key words listed + below 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.) + + + + Percent-encoding may be used to include a symbol with special + meaning in any of the URI parts. + + + + The host part may be either hostname or an IP address. To specify an + IPv6 host address, enclose it in square brackets: + +postgresql://[::1]/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 + (?) 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 use the + following syntax: + +postgresql:///path/to/pgsql/socket/dir?dbname=other + + + + + The currently recognized parameter key words are: + + + + host + + + Name of host to connect to.host name + If this begins with a slash, it specifies Unix-domain + communication rather than TCP/IP communication; the value is the + name of the directory in which the socket file is stored. The + default behavior when host is not specified + is to connect to a Unix-domain + socketUnix domain socket in + /tmp (or whatever socket directory was specified + when PostgreSQL was built). On machines without + Unix-domain sockets, the default is to connect to localhost. + + + + + + hostaddr + + + Numeric IP address of host to connect to. This should be in the + standard IPv4 address format, e.g., 172.28.40.9. If + your machine supports IPv6, you can also use those addresses. + TCP/IP communication is + always used when a nonempty string is specified for this parameter. + + + + Using hostaddr instead of host allows the + application to avoid a host name look-up, which might be important + in applications with time constraints. However, a host name is + required for Kerberos, GSSAPI, or SSPI authentication + methods, as well as for verify-full SSL + certificate verification. The following rules are used: + + + + If host is specified without hostaddr, + a host name lookup occurs. + + + + + If hostaddr is specified without host, + the value for hostaddr gives the server network address. + The connection attempt will fail if the authentication + method requires a host name. + + + + + If both host and hostaddr are specified, + the value for hostaddr gives the server network address. + The value for host is ignored unless the + authentication method requires it, in which case it will be + used as the host name. + + + + Note that authentication is likely to fail if host + is not the name of the server at network address hostaddr. + Also, note that host rather than hostaddr + is used to identify the connection in ~/.pgpass (see + ). + + + + Without either a host name or host address, + libpq will connect using a + local Unix-domain socket; or on machines without Unix-domain + sockets, it will attempt to connect to localhost. + + + + + + port + + + Port number to connect to at the server host, or socket file + name extension for Unix-domain + connections.port + + + + + + dbname + + + The database name. Defaults to be the same as the user name. + See for more details. + + + + + + user + + + PostgreSQL user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. + + + + + + password + + + Password to be used if the server demands password authentication. + + + + + + connect_timeout + + + Maximum wait for connection, in seconds (write as a decimal integer + string). Zero or not specified means wait indefinitely. It is not + recommended to use a timeout of less than 2 seconds. + + + + + + client_encoding + + + This sets the client_encoding + configuration parameter for this connection. In addition to + the values accepted by the corresponding server option, you + can use auto to determine the right + encoding from the current locale in the client + (LC_CTYPE environment variable on Unix + systems). + + + + + + options + + + Adds command-line options to send to the server at run-time. + For example, setting this to -c geqo=off sets the + session's value of the geqo parameter to + off. For a detailed discussion of the available + options, consult . + + + + + + application_name + + + Specifies a value for the + configuration parameter. + + + + + + fallback_application_name + + + Specifies a fallback value for the configuration parameter. + This value will be used if no value has been given for + application_name via a connection parameter or the + PGAPPNAME environment variable. Specifying + a fallback name is useful in generic utility programs that + wish to set a default application name but allow it to be + overridden by the user. + + + + + + keepalives + + + Controls whether client-side TCP keepalives are used. The default + value is 1, meaning on, but you can change this to 0, meaning off, + if keepalives are not wanted. This parameter is ignored for + connections made via a Unix-domain socket. + + + + + + keepalives_idle + + + Controls the number of seconds of inactivity after which TCP should + send a keepalive message to the server. A value of zero uses the + system default. This parameter is ignored for connections made via a + Unix-domain socket, or if keepalives are disabled. It is only supported + on systems where the TCP_KEEPIDLE or TCP_KEEPALIVE + socket option is available, and on Windows; on other systems, it has no + effect. + + + + + + keepalives_interval + + + Controls the number of seconds after which a TCP keepalive message + that is not acknowledged by the server should be retransmitted. A + value of zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where the TCP_KEEPINTVL + socket option is available, and on Windows; on other systems, it has no + effect. + + + + + + keepalives_count + + + Controls the number of TCP keepalives that can be lost before the + client's connection to the server is considered dead. A value of + zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where the TCP_KEEPCNT + socket option is available; on other systems, it has no effect. + + + + + + tty + + + Ignored (formerly, this specified where to send server debug output). + + + + + + sslmode + + + This option determines whether or with what priority a secure + SSL TCP/IP connection will be negotiated with the + server. There are six modes: + + + + disable + + + only try a non-SSL connection + + + + + + allow + + + first try a non-SSL connection; if that + fails, try an SSL connection + + + + + + prefer (default) + + + first try an SSL connection; if that fails, + try a non-SSL connection + + + + + + require + + + only try an SSL connection. If a root CA + file is present, verify the certificate in the same way as + if verify-ca was specified + + + + + + verify-ca + + + only try an SSL connection, and verify that + the server certificate is issued by a trusted + certificate authority (CA) + + + + + + verify-full + + + only try an SSL connection, verify that the + server certificate is issued by a + trusted CA and that the server host name + matches that in the certificate + + + + + + See for a detailed description of how + these options work. + + + + sslmode is ignored for Unix domain socket + communication. + If PostgreSQL is compiled without SSL support, + using options require, verify-ca, or + verify-full will cause an error, while + options allow and prefer will be + accepted but libpq will not actually attempt + an SSL + connection.SSLwith libpq + + + + + + requiressl + + + This option is deprecated in favor of the sslmode + setting. + + + + If set to 1, an SSL connection to the server + is required (this is equivalent to sslmode + require). libpq will then refuse + to connect if the server does not accept an + SSL connection. If set to 0 (default), + libpq will negotiate the connection type with + the server (equivalent to sslmode + prefer). This option is only available if + PostgreSQL is compiled with SSL support. + + + + + + sslcompression + + + If set to 1 (default), data sent over SSL connections will be + compressed (this requires OpenSSL version + 0.9.8 or later). + If set to 0, compression will be disabled (this requires + OpenSSL 1.0.0 or later). + This parameter is ignored if a connection without SSL is made, + or if the version of OpenSSL used does not support + it. + + + Compression uses CPU time, but can improve throughput if + the network is the bottleneck. + Disabling compression can improve response time and throughput + if CPU performance is the limiting factor. + + + + + + sslcert + + + This parameter specifies the file name of the client SSL + certificate, replacing the default + ~/.postgresql/postgresql.crt. + This parameter is ignored if an SSL connection is not made. + + + + + + sslkey + + + This parameter specifies the location for the secret key used for + the client certificate. It can either specify a file name that will + be used instead of the default + ~/.postgresql/postgresql.key, or it can specify a key + obtained from an external engine (engines are + OpenSSL loadable modules). An external engine + specification should consist of a colon-separated engine name and + an engine-specific key identifier. This parameter is ignored if an + SSL connection is not made. + + + + + + sslrootcert + + + This parameter specifies the name of a file containing SSL + certificate authority (CA) certificate(s). + If the file exists, the server's certificate will be verified + to be signed by one of these authorities. The default is + ~/.postgresql/root.crt. + + + + + + sslcrl + + + This parameter specifies the file name of the SSL certificate + revocation list (CRL). Certificates listed in this file, if it + exists, will be rejected while attempting to authenticate the + server's certificate. The default is + ~/.postgresql/root.crl. + + + + + + requirepeer + + + This parameter specifies the operating-system user name of the + server, for example requirepeer=postgres. + When making a Unix-domain socket connection, if this + parameter is set, the client checks at the beginning of the + connection that the server process is running under the specified + user name; if it is not, the connection is aborted with an error. + This parameter can be used to provide server authentication similar + to that available with SSL certificates on TCP/IP connections. + (Note that if the Unix-domain socket is in + /tmp or another publicly writable location, + any user could start a server listening there. Use this parameter + to ensure that you are connected to a server run by a trusted user.) + This option is only supported on platforms for which the + peer authentication method is implemented; see + . + + + + + + krbsrvname + + + Kerberos service name to use when authenticating with Kerberos 5 + or GSSAPI. + This must match the service name specified in the server + configuration for Kerberos authentication to succeed. (See also + and .) + + + + + + gsslib + + + GSS library to use for GSSAPI authentication. Only used on Windows. + Set to gssapi to force libpq to use the GSSAPI + library for authentication instead of the default SSPI. + + + + + + service + + + Service name to use for additional parameters. It specifies a service + name in pg_service.conf that holds additional connection parameters. + This allows applications to specify only a service name so connection parameters + can be centrally maintained. See . + + + + + + + Environment Variables @@ -6832,6 +6920,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + The Connection Service File diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index b849101..bdcadf3 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -115,7 +115,10 @@ PostgreSQL documentation argument on the command line. - If this parameter contains an = sign, it is treated as a + If this parameter contains an = sign or starts + with a valid URI prefix + (postgresql:// + or postgres://), it is treated as a conninfo string. See for more information. @@ -596,11 +599,13 @@ PostgreSQL documentation An alternative way to specify connection parameters is in a - conninfo string, which is used instead of a - database name. This mechanism give you very wide control over the + conninfo string or + a URI, which is used instead of a database + name. This mechanism give you very wide control over the connection. For example: $ psql "service=myservice sslmode=require" +$ psql postgresql://dbmaster:5433/mydb?sslmode=require This way you can also use LDAP for connection parameter lookup as described in .