From 27ef266400eb73a213f028cf5e2391e01fa6c83c Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Sat, 16 Jul 2022 10:34:10 -0400 Subject: [PATCH 1/6] set a timeout to get the return from requesting SSL upgrade. --- .../java/org/postgresql/core/v3/ConnectionFactoryImpl.java | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java index 0e10796863..6eebd92790 100644 --- a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java +++ b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java @@ -532,6 +532,9 @@ private PGStream enableSSL(PGStream pgStream, SslMode sslMode, Properties info, LOGGER.log(Level.FINEST, " FE=> SSLRequest"); + // set the time out to 2seconds + int currentTimeout = pgStream.getSocket().getSoTimeout(); + pgStream.getSocket().setSoTimeout(2000); // Send SSL request packet pgStream.sendInteger4(8); pgStream.sendInteger2(1234); @@ -540,6 +543,8 @@ private PGStream enableSSL(PGStream pgStream, SslMode sslMode, Properties info, // Now get the response from the backend, one of N, E, S. int beresp = pgStream.receiveChar(); + pgStream.getSocket().setSoTimeout(currentTimeout); + switch (beresp) { case 'E': LOGGER.log(Level.FINEST, " <=BE SSLError"); From 27deb41a207398c34b1f8bb83aef4b309bfd2cbf Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Mon, 18 Jul 2022 11:28:57 -0400 Subject: [PATCH 2/6] Make the SSL Response timeout a configurable property --- README.md | 109 ++++----- docs/documentation/head/connect.md | 226 +++++++++--------- .../main/java/org/postgresql/PGProperty.java | 9 + .../core/v3/ConnectionFactoryImpl.java | 5 +- .../postgresql/ds/common/BaseDataSource.java | 18 ++ 5 files changed, 200 insertions(+), 167 deletions(-) diff --git a/README.md b/README.md index 46dbfd180d..6d0c060bf0 100644 --- a/README.md +++ b/README.md @@ -88,61 +88,62 @@ Note that the most detailed log levels, "`FINEST`", may include sensitive inform #### Connection Properties In addition to the standard connection parameters the driver supports a number of additional properties which can be used to specify additional driver behaviour specific to PostgreSQL™. These properties may be specified in either the connection URL or an additional Properties object parameter to DriverManager.getConnection. -| Property | Type | Default | Description | -| ----------------------------- | ------- | :-----: | ------------- | -| user | String | null | The database user on whose behalf the connection is being made. | -| password | String | null | The database user's password. | -| options | String | null | Specify 'options' connection initialization parameter. | +| Property | Type | Default | Description | +|-------------------------------| ------- | :-----: |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| user | String | null | The database user on whose behalf the connection is being made. | +| password | String | null | The database user's password. | +| options | String | null | Specify 'options' connection initialization parameter. | | service | String | null | Specify 'service' name described in pg_service.conf file. References: [The Connection Service File](https://www.postgresql.org/docs/current/libpq-pgservice.html) and [The Password File](https://www.postgresql.org/docs/current/libpq-pgpass.html). 'service' file can provide all properties including 'hostname=', 'port=' and 'dbname='. | -| ssl | Boolean | false | Control use of SSL (true value causes SSL to be required) | -| sslfactory | String | null | Provide a SSLSocketFactory class when using SSL. | -| sslfactoryarg (deprecated) | String | null | Argument forwarded to constructor of SSLSocketFactory class. | -| sslmode | String | prefer | Controls the preference for opening using an SSL encrypted connection. | -| sslcert | String | null | The location of the client's SSL certificate | -| sslkey | String | null | The location of the client's PKCS#8 SSL key | -| sslrootcert | String | null | The location of the root certificate for authenticating the server. | -| sslhostnameverifier | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.net.ssl.HostnameVerifier and can verify the server hostname. | -| sslpasswordcallback | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.security.auth.callback.CallbackHandler and can handle PasswordCallback for the ssl password. | -| sslpassword | String | null | The password for the client's ssl key (ignored if sslpasswordcallback is set) | -| sendBufferSize | Integer | -1 | Socket write buffer size | -| receiveBufferSize | Integer | -1 | Socket read buffer size | -| logServerErrorDetail | Boolean | true | Allows server error detail (such as sql statements and values) to be logged and passed on in exceptions. Setting to false will mask these errors so they won't be exposed to users, or logs. | -| allowEncodingChanges | Boolean | false | Allow for changes in client_encoding | -| logUnclosedConnections | Boolean | false | When connections that are not explicitly closed are garbage collected, log the stacktrace from the opening of the connection to trace the leak source | -| binaryTransferEnable | String | "" | Comma separated list of types to enable binary transfer. Either OID numbers or names | -| binaryTransferDisable | String | "" | Comma separated list of types to disable binary transfer. Either OID numbers or names. Overrides values in the driver default set and values set with binaryTransferEnable. | -| prepareThreshold | Integer | 5 | Statement prepare threshold. A value of -1 stands for forceBinary | -| preparedStatementCacheQueries | Integer | 256 | Specifies the maximum number of entries in per-connection cache of prepared statements. A value of 0 disables the cache. | -| preparedStatementCacheSizeMiB | Integer | 5 | Specifies the maximum size (in megabytes) of a per-connection prepared statement cache. A value of 0 disables the cache. | -| defaultRowFetchSize | Integer | 0 | Positive number of rows that should be fetched from the database when more rows are needed for ResultSet by each fetch iteration | -| loginTimeout | Integer | 0 | Specify how long to wait for establishment of a database connection.| -| connectTimeout | Integer | 10 | The timeout value used for socket connect operations. | -| socketTimeout | Integer | 0 | The timeout value used for socket read operations. | -| tcpKeepAlive | Boolean | false | Enable or disable TCP keep-alive. | -| tcpNoDelay | Boolean | true | Enable or disable TCP no delay. | -| ApplicationName | String | PostgreSQL JDBC Driver | The application name (require server version >= 9.0). If assumeMinServerVersion is set to >= 9.0 this will be sent in the startup packets, otherwise after the connection is made | -| readOnly | Boolean | false | Puts this connection in read-only mode | -| disableColumnSanitiser | Boolean | false | Enable optimization that disables column name sanitiser | -| assumeMinServerVersion | String | null | Assume the server is at least that version | -| currentSchema | String | null | Specify the schema (or several schema separated by commas) to be set in the search-path | -| targetServerType | String | any | Specifies what kind of server to connect, possible values: any, master, slave (deprecated), secondary, preferSlave (deprecated), preferSecondary, preferPrimary | -| hostRecheckSeconds | Integer | 10 | Specifies period (seconds) after which the host status is checked again in case it has changed | -| loadBalanceHosts | Boolean | false | If disabled hosts are connected in the given order. If enabled hosts are chosen randomly from the set of suitable candidates | -| socketFactory | String | null | Specify a socket factory for socket creation | -| socketFactoryArg (deprecated) | String | null | Argument forwarded to constructor of SocketFactory class. | -| autosave | String | never | Specifies what the driver should do if a query fails, possible values: always, never, conservative | -| cleanupSavepoints | Boolean | false | In Autosave mode the driver sets a SAVEPOINT for every query. It is possible to exhaust the server shared buffers. Setting this to true will release each SAVEPOINT at the cost of an additional round trip. | -| preferQueryMode | String | extended | Specifies which mode is used to execute queries to database, possible values: extended, extendedForPrepared, extendedCacheEverything, simple | -| reWriteBatchedInserts | Boolean | false | Enable optimization to rewrite and collapse compatible INSERT statements that are batched. | -| escapeSyntaxCallMode | String | select | Specifies how JDBC escape call syntax is transformed into underlying SQL (CALL/SELECT), for invoking procedures or functions (requires server version >= 11), possible values: select, callIfNoReturn, call | -| maxResultBuffer | String | null | Specifies size of result buffer in bytes, which can't be exceeded during reading result set. Can be specified as particular size (i.e. "100", "200M" "2G") or as percent of max heap memory (i.e. "10p", "20pct", "50percent") | -| gssEncMode | String | allow | Controls the preference for using GSSAPI encryption for the connection, values are disable, allow, prefer, and require | -| adaptiveFetch | Boolean | false | Specifies if number of rows fetched in ResultSet by each fetch iteration should be dynamic. Number of rows will be calculated by dividing maxResultBuffer size into max row size observed so far. Requires declaring maxResultBuffer and defaultRowFetchSize for first iteration. -| adaptiveFetchMinimum | Integer | 0 | Specifies minimum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go below this value. -| adaptiveFetchMaximum | Integer | -1 | Specifies maximum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go above this value. Any negative number set as adaptiveFetchMaximum is used by adaptiveFetch as infinity number of rows. -| localSocketAddress | String | null | Hostname or IP address given to explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. -| quoteReturningIdentifiers | Boolean | true | By default we double quote returning identifiers. Some ORM's already quote them. Switch allows them to turn this off -| authenticationPluginClassName | String | null | Fully qualified class name of the class implementing the AuthenticationPlugin interface. If this is null, the password value in the connection properties will be used. +| ssl | Boolean | false | Control use of SSL (true value causes SSL to be required) | +| sslfactory | String | null | Provide a SSLSocketFactory class when using SSL. | +| sslfactoryarg (deprecated) | String | null | Argument forwarded to constructor of SSLSocketFactory class. | +| sslmode | String | prefer | Controls the preference for opening using an SSL encrypted connection. | +| sslcert | String | null | The location of the client's SSL certificate | +| sslkey | String | null | The location of the client's PKCS#8 SSL key | +| sslrootcert | String | null | The location of the root certificate for authenticating the server. | +| sslhostnameverifier | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.net.ssl.HostnameVerifier and can verify the server hostname. | +| sslpasswordcallback | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.security.auth.callback.CallbackHandler and can handle PasswordCallback for the ssl password. | +| sslpassword | String | null | The password for the client's ssl key (ignored if sslpasswordcallback is set) | +| sendBufferSize | Integer | -1 | Socket write buffer size | +| receiveBufferSize | Integer | -1 | Socket read buffer size | +| logServerErrorDetail | Boolean | true | Allows server error detail (such as sql statements and values) to be logged and passed on in exceptions. Setting to false will mask these errors so they won't be exposed to users, or logs. | +| allowEncodingChanges | Boolean | false | Allow for changes in client_encoding | +| logUnclosedConnections | Boolean | false | When connections that are not explicitly closed are garbage collected, log the stacktrace from the opening of the connection to trace the leak source | +| binaryTransferEnable | String | "" | Comma separated list of types to enable binary transfer. Either OID numbers or names | +| binaryTransferDisable | String | "" | Comma separated list of types to disable binary transfer. Either OID numbers or names. Overrides values in the driver default set and values set with binaryTransferEnable. | +| prepareThreshold | Integer | 5 | Statement prepare threshold. A value of -1 stands for forceBinary | +| preparedStatementCacheQueries | Integer | 256 | Specifies the maximum number of entries in per-connection cache of prepared statements. A value of 0 disables the cache. | +| preparedStatementCacheSizeMiB | Integer | 5 | Specifies the maximum size (in megabytes) of a per-connection prepared statement cache. A value of 0 disables the cache. | +| defaultRowFetchSize | Integer | 0 | Positive number of rows that should be fetched from the database when more rows are needed for ResultSet by each fetch iteration | +| loginTimeout | Integer | 0 | Specify how long to wait for establishment of a database connection. | +| connectTimeout | Integer | 10 | The timeout value used for socket connect operations. | +| socketTimeout | Integer | 0 | The timeout value used for socket read operations. | +| sslResponseTimeout | Integer | 5000 | Socket timeout waiting for a response from a request for SSL upgrade from the server. | | +| tcpKeepAlive | Boolean | false | Enable or disable TCP keep-alive. | +| tcpNoDelay | Boolean | true | Enable or disable TCP no delay. | +| ApplicationName | String | PostgreSQL JDBC Driver | The application name (require server version >= 9.0). If assumeMinServerVersion is set to >= 9.0 this will be sent in the startup packets, otherwise after the connection is made | +| readOnly | Boolean | false | Puts this connection in read-only mode | +| disableColumnSanitiser | Boolean | false | Enable optimization that disables column name sanitiser | +| assumeMinServerVersion | String | null | Assume the server is at least that version | +| currentSchema | String | null | Specify the schema (or several schema separated by commas) to be set in the search-path | +| targetServerType | String | any | Specifies what kind of server to connect, possible values: any, master, slave (deprecated), secondary, preferSlave (deprecated), preferSecondary, preferPrimary | +| hostRecheckSeconds | Integer | 10 | Specifies period (seconds) after which the host status is checked again in case it has changed | +| loadBalanceHosts | Boolean | false | If disabled hosts are connected in the given order. If enabled hosts are chosen randomly from the set of suitable candidates | +| socketFactory | String | null | Specify a socket factory for socket creation | +| socketFactoryArg (deprecated) | String | null | Argument forwarded to constructor of SocketFactory class. | +| autosave | String | never | Specifies what the driver should do if a query fails, possible values: always, never, conservative | +| cleanupSavepoints | Boolean | false | In Autosave mode the driver sets a SAVEPOINT for every query. It is possible to exhaust the server shared buffers. Setting this to true will release each SAVEPOINT at the cost of an additional round trip. | +| preferQueryMode | String | extended | Specifies which mode is used to execute queries to database, possible values: extended, extendedForPrepared, extendedCacheEverything, simple | +| reWriteBatchedInserts | Boolean | false | Enable optimization to rewrite and collapse compatible INSERT statements that are batched. | +| escapeSyntaxCallMode | String | select | Specifies how JDBC escape call syntax is transformed into underlying SQL (CALL/SELECT), for invoking procedures or functions (requires server version >= 11), possible values: select, callIfNoReturn, call | +| maxResultBuffer | String | null | Specifies size of result buffer in bytes, which can't be exceeded during reading result set. Can be specified as particular size (i.e. "100", "200M" "2G") or as percent of max heap memory (i.e. "10p", "20pct", "50percent") | +| gssEncMode | String | allow | Controls the preference for using GSSAPI encryption for the connection, values are disable, allow, prefer, and require | +| adaptiveFetch | Boolean | false | Specifies if number of rows fetched in ResultSet by each fetch iteration should be dynamic. Number of rows will be calculated by dividing maxResultBuffer size into max row size observed so far. Requires declaring maxResultBuffer and defaultRowFetchSize for first iteration. +| adaptiveFetchMinimum | Integer | 0 | Specifies minimum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go below this value. +| adaptiveFetchMaximum | Integer | -1 | Specifies maximum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go above this value. Any negative number set as adaptiveFetchMaximum is used by adaptiveFetch as infinity number of rows. +| localSocketAddress | String | null | Hostname or IP address given to explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. +| quoteReturningIdentifiers | Boolean | true | By default we double quote returning identifiers. Some ORM's already quote them. Switch allows them to turn this off +| authenticationPluginClassName | String | null | Fully qualified class name of the class implementing the AuthenticationPlugin interface. If this is null, the password value in the connection properties will be used. ## Contributing For information on how to contribute to the project see the [Contributing Guidelines](CONTRIBUTING.md) diff --git a/docs/documentation/head/connect.md b/docs/documentation/head/connect.md index c1eb81ffb0..c5e45bcefc 100644 --- a/docs/documentation/head/connect.md +++ b/docs/documentation/head/connect.md @@ -71,20 +71,20 @@ Connection conn = DriverManager.getConnection(url); * **user** = String - The database user on whose behalf the connection is being made. + The database user on whose behalf the connection is being made. * **password** = String - The database user's password. + The database user's password. * **options** = String - Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. + Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. - The value of this property may contain spaces or other special characters, - and it should be properly encoded if provided in the connection URL. Spaces - are considered to separate command-line arguments, unless escaped with - a backslash (`\`); `\\` represents a literal backslash. + The value of this property may contain spaces or other special characters, + and it should be properly encoded if provided in the connection URL. Spaces + are considered to separate command-line arguments, unless escaped with + a backslash (`\`); `\\` represents a literal backslash. ```java Properties props = new Properties(); @@ -97,55 +97,55 @@ Connection conn = DriverManager.getConnection(url); * **ssl** = boolean - Connect using SSL. The server must have been compiled with SSL support. - This property does not need a value associated with it. The mere presence - of it specifies a SSL connection. However, for compatibility with future - versions, the value "true" is preferred. For more information see [Chapter - 4, *Using SSL*](ssl.html). + Connect using SSL. The server must have been compiled with SSL support. + This property does not need a value associated with it. The mere presence + of it specifies a SSL connection. However, for compatibility with future + versions, the value "true" is preferred. For more information see [Chapter + 4, *Using SSL*](ssl.html). Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples. * **sslfactory** = String - The provided value is a class name to use as the `SSLSocketFactory` when - establishing a SSL connection. For more information see the section - called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory + The provided value is a class name to use as the `SSLSocketFactory` when + establishing a SSL connection. For more information see the section + called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory * **sslfactoryarg** (deprecated) = String - This value is an optional argument to the constructor of the sslfactory - class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). + This value is an optional argument to the constructor of the sslfactory + class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). * **sslmode** = String - possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` - . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the - validity of the certificate or the host name. `verify-ca` validates the certificate, but does not - verify the hostname. `verify-full` will validate that the certificate is correct and verify the - host connected to has the same hostname as the certificate. Default is `prefer` + possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` + . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the + validity of the certificate or the host name. `verify-ca` validates the certificate, but does not + verify the hostname. `verify-full` will validate that the certificate is correct and verify the + host connected to has the same hostname as the certificate. Default is `prefer` - Setting these will necessitate storing the server certificate on the client machine see - ["Configuring the client"](ssl-client.html) for details. + Setting these will necessitate storing the server certificate on the client machine see + ["Configuring the client"](ssl-client.html) for details. * **sslcert** = String - Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. + Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. It can be a PEM encoded X509v3 certificate - *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. + *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. * **sslkey** = String - Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. + Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. - *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: + *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: - `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` + `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` - PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. + PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. - If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. + If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected by other means (e.g. access control of the OS), or the key file is transmitted in untrusted channels. @@ -155,62 +155,62 @@ Connection conn = DriverManager.getConnection(url); * **sslrootcert** = String - File name of the SSL root certificate. Defaults to defaultdir/root.crt + File name of the SSL root certificate. Defaults to defaultdir/root.crt It can be a PEM encoded X509v3 certificate * **sslhostnameverifier** = String - Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` + Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` * **sslpasswordcallback** = String - Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` + Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` * **sslpassword** = String - If provided will be used by ConsoleCallbackHandler + If provided will be used by ConsoleCallbackHandler * **protocolVersion** = int - The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and - the driver will by default try to connect using the V3 protocol. + The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and + the driver will by default try to connect using the V3 protocol. * **loggerLevel** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **loggerFile** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **allowEncodingChanges** = boolean - When using the V3 protocol the driver monitors changes in certain server - configuration parameters that should not be touched by end users. The - `client_encoding` setting is set by the driver and should not be altered. - If the driver detects a change it will abort the connection. There is - one legitimate exception to this behaviour though, using the `COPY` command - on a file residing on the server's filesystem. The only means of specifying - the encoding of this file is by altering the `client_encoding` setting. - The JDBC team considers this a failing of the `COPY` command and hopes to - provide an alternate means of specifying the encoding in the future, but - for now there is this URL parameter. Enable this only if you need to - override the client encoding when doing a copy. + When using the V3 protocol the driver monitors changes in certain server + configuration parameters that should not be touched by end users. The + `client_encoding` setting is set by the driver and should not be altered. + If the driver detects a change it will abort the connection. There is + one legitimate exception to this behaviour though, using the `COPY` command + on a file residing on the server's filesystem. The only means of specifying + the encoding of this file is by altering the `client_encoding` setting. + The JDBC team considers this a failing of the `COPY` command and hopes to + provide an alternate means of specifying the encoding in the future, but + for now there is this URL parameter. Enable this only if you need to + override the client encoding when doing a copy. * **logUnclosedConnections** = boolean - Clients may leak `Connection` objects by failing to call its `close()` - method. Eventually these objects will be garbage collected and the - `finalize()` method will be called which will close the `Connection` if - caller has neglected to do this himself. The usage of a finalizer is just - a stopgap solution. To help developers detect and correct the source of - these leaks the `logUnclosedConnections` URL parameter has been added. - It captures a stacktrace at each `Connection` opening and if the `finalize()` - method is reached without having been closed the stacktrace is printed - to the log. + Clients may leak `Connection` objects by failing to call its `close()` + method. Eventually these objects will be garbage collected and the + `finalize()` method will be called which will close the `Connection` if + caller has neglected to do this himself. The usage of a finalizer is just + a stopgap solution. To help developers detect and correct the source of + these leaks the `logUnclosedConnections` URL parameter has been added. + It captures a stacktrace at each `Connection` opening and if the `finalize()` + method is reached without having been closed the stacktrace is printed + to the log. * **autosave** = String @@ -231,62 +231,62 @@ Connection conn = DriverManager.getConnection(url); * **binaryTransfer** = boolean - Use binary format for sending and receiving data if possible. + Use binary format for sending and receiving data if possible. - The default is 'true' + The default is 'true' * **binaryTransferEnable** = String - A comma separated list of types to enable binary transfer. Either OID numbers or names. + A comma separated list of types to enable binary transfer. Either OID numbers or names. * **binaryTransferDisable** = String - A comma separated list of types to disable binary transfer. Either OID numbers or names. - Overrides values in the driver default set and values set with binaryTransferEnable. + A comma separated list of types to disable binary transfer. Either OID numbers or names. + Overrides values in the driver default set and values set with binaryTransferEnable. * **databaseMetadataCacheFields** = int - Specifies the maximum number of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum number of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 65536. + Defaults to 65536. * **databaseMetadataCacheFieldsMiB** = int - Specifies the maximum size (in megabytes) of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum size (in megabytes) of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 5. + Defaults to 5. * **prepareThreshold** = int - Determine the number of `PreparedStatement` executions required before - switching over to use server side prepared statements. The default is - five, meaning start using server side prepared statements on the fifth - execution of the same `PreparedStatement` object. More information on - server side prepared statements is available in the section called - [“Server Prepared Statements”](server-prepare.html). + Determine the number of `PreparedStatement` executions required before + switching over to use server side prepared statements. The default is + five, meaning start using server side prepared statements on the fifth + execution of the same `PreparedStatement` object. More information on + server side prepared statements is available in the section called + [“Server Prepared Statements”](server-prepare.html). * **preparedStatementCacheQueries** = int - Determine the number of queries that are cached in each connection. - The default is 256, meaning if you use more than 256 different queries - in `prepareStatement()` calls, the least recently used ones - will be discarded. The cache allows application to benefit from - [“Server Prepared Statements”](server-prepare.html) - (see `prepareThreshold`) even if the prepared statement is - closed after each execution. The value of 0 disables the cache. + Determine the number of queries that are cached in each connection. + The default is 256, meaning if you use more than 256 different queries + in `prepareStatement()` calls, the least recently used ones + will be discarded. The cache allows application to benefit from + [“Server Prepared Statements”](server-prepare.html) + (see `prepareThreshold`) even if the prepared statement is + closed after each execution. The value of 0 disables the cache. - N.B.Each connection has its own statement cache. + N.B.Each connection has its own statement cache. * **preparedStatementCacheSizeMiB** = int - Determine the maximum size (in mebibytes) of the prepared queries cache - (see `preparedStatementCacheQueries`). - The default is 5, meaning if you happen to cache more than 5 MiB of queries - the least recently used ones will be discarded. - The main aim of this setting is to prevent `OutOfMemoryError`. - The value of 0 disables the cache. + Determine the maximum size (in mebibytes) of the prepared queries cache + (see `preparedStatementCacheQueries`). + The default is 5, meaning if you happen to cache more than 5 MiB of queries + the least recently used ones will be discarded. + The main aim of this setting is to prevent `OutOfMemoryError`. + The value of 0 disables the cache. * **preferQueryMode** = String @@ -300,38 +300,42 @@ Connection conn = DriverManager.getConnection(url); * **defaultRowFetchSize** = int - Determine the number of rows fetched in `ResultSet` - by one fetch with trip to the database. Limiting the number of rows are fetch with - each trip to the database allow avoids unnecessary memory consumption - and as a consequence `OutOfMemoryError`. + Determine the number of rows fetched in `ResultSet` + by one fetch with trip to the database. Limiting the number of rows are fetch with + each trip to the database allow avoids unnecessary memory consumption + and as a consequence `OutOfMemoryError`. - The default is zero, meaning that in `ResultSet` will be fetch all rows at once. - Negative number is not available. + The default is zero, meaning that in `ResultSet` will be fetch all rows at once. + Negative number is not available. * **loginTimeout** = int - Specify how long to wait for establishment of a database connection. The - timeout is specified in seconds. + Specify how long to wait for establishment of a database connection. The + timeout is specified in seconds. * **connectTimeout** = int - The timeout value used for socket connect operations. If connecting to the server - takes longer than this value, the connection is broken. - The timeout is specified in seconds and a value of zero means that it is disabled. + The timeout value used for socket connect operations. If connecting to the server + takes longer than this value, the connection is broken. + The timeout is specified in seconds and a value of zero means that it is disabled. * **socketTimeout** = int - The timeout value used for socket read operations. If reading from the - server takes longer than this value, the connection is closed. This can - be used as both a brute force global query timeout and a method of - detecting network problems. The timeout is specified in seconds and a - value of zero means that it is disabled. + The timeout value used for socket read operations. If reading from the + server takes longer than this value, the connection is closed. This can + be used as both a brute force global query timeout and a method of + detecting network problems. The timeout is specified in seconds and a + value of zero means that it is disabled. + +* **sslResponseTikmeout** = int + The timeout value in milliseconds that we wait for a response from the server + after requesting the connection be upgraded to SSL. * **cancelSignalTimeout** = int - Cancel command is sent out of band over its own connection, so cancel message can itself get - stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. - The timeout is specified in seconds. Default value is 10 seconds. + Cancel command is sent out of band over its own connection, so cancel message can itself get + stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. + The timeout is specified in seconds. Default value is 10 seconds. * **tcpKeepAlive** = boolean diff --git a/pgjdbc/src/main/java/org/postgresql/PGProperty.java b/pgjdbc/src/main/java/org/postgresql/PGProperty.java index b683e68c37..fe83ff3dd4 100644 --- a/pgjdbc/src/main/java/org/postgresql/PGProperty.java +++ b/pgjdbc/src/main/java/org/postgresql/PGProperty.java @@ -165,6 +165,15 @@ public enum PGProperty { "10", "The timeout value used for socket connect operations."), + /** + *

After requesting an upgrade to SSL from the server there are reports of the server not responding due to a failover + * without a timeout here, the client can wait forever. This timeout will be set before the request and reset after

+ */ + SSL_RESPONSE_TIMEOUT( + "sslResponseTimeout", + "5000", + "Time in milliseconds we wait for a response from the server after requesting SSL upgrade"), + /** * Specify the schema (or several schema separated by commas) to be set in the search-path. This schema will be used to resolve * unqualified object names used in statements over this connection. diff --git a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java index 6eebd92790..c165016600 100644 --- a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java +++ b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java @@ -532,9 +532,10 @@ private PGStream enableSSL(PGStream pgStream, SslMode sslMode, Properties info, LOGGER.log(Level.FINEST, " FE=> SSLRequest"); - // set the time out to 2seconds + int sslTimeout = PGProperty.SSL_RESPONSE_TIMEOUT.getInt(info); int currentTimeout = pgStream.getSocket().getSoTimeout(); - pgStream.getSocket().setSoTimeout(2000); + + pgStream.getSocket().setSoTimeout(sslTimeout); // Send SSL request packet pgStream.sendInteger4(8); pgStream.sendInteger2(1234); diff --git a/pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java b/pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java index 8fc68cd926..4a75fdc736 100644 --- a/pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java +++ b/pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java @@ -354,6 +354,24 @@ public void setConnectTimeout(int connectTimeout) { PGProperty.CONNECT_TIMEOUT.set(properties, connectTimeout); } + /** + * + * @return SSL ResponseTimeout + * @see PGProperty#SSL_RESPONSE_TIMEOUT + */ + public int getSslResponseTimeout() { + return PGProperty.SSL_RESPONSE_TIMEOUT.getIntNoCheck(properties); + } + + /** + * + * @param sslResponseTimeout ssl response timeout + * @see PGProperty#SSL_RESPONSE_TIMEOUT + */ + public void setSslResponseTimeout(int sslResponseTimeout) { + PGProperty.SSL_RESPONSE_TIMEOUT.set(properties,sslResponseTimeout); + } + /** * @return protocol version * @see PGProperty#PROTOCOL_VERSION From 574b763419b2cd2c5fe94abebf4e10cdb1c21a8a Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Mon, 18 Jul 2022 12:38:06 -0400 Subject: [PATCH 3/6] fix docs and change logic to use lesser of current socket timeout or sslresponse timeout --- docs/documentation/head/connect.md | 2 +- .../java/org/postgresql/core/v3/ConnectionFactoryImpl.java | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/documentation/head/connect.md b/docs/documentation/head/connect.md index c5e45bcefc..0067913928 100644 --- a/docs/documentation/head/connect.md +++ b/docs/documentation/head/connect.md @@ -327,7 +327,7 @@ Connection conn = DriverManager.getConnection(url); detecting network problems. The timeout is specified in seconds and a value of zero means that it is disabled. -* **sslResponseTikmeout** = int +* **sslResponseTimeout** = int The timeout value in milliseconds that we wait for a response from the server after requesting the connection be upgraded to SSL. diff --git a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java index c165016600..6ef64db941 100644 --- a/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java +++ b/pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java @@ -535,6 +535,13 @@ private PGStream enableSSL(PGStream pgStream, SslMode sslMode, Properties info, int sslTimeout = PGProperty.SSL_RESPONSE_TIMEOUT.getInt(info); int currentTimeout = pgStream.getSocket().getSoTimeout(); + // if the current timeout is less than sslTimeout then + // use the smaller timeout. We could do something tricky + // here to not set it in that case but this is pretty readable + if (currentTimeout > 0 && currentTimeout < sslTimeout) { + sslTimeout = currentTimeout; + } + pgStream.getSocket().setSoTimeout(sslTimeout); // Send SSL request packet pgStream.sendInteger4(8); From 957d8a0cf2b72f254e7b49e231534f83d07698d6 Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Mon, 18 Jul 2022 12:46:11 -0400 Subject: [PATCH 4/6] restore spacing --- docs/documentation/head/connect.md | 364 ++++++++++++++--------------- 1 file changed, 182 insertions(+), 182 deletions(-) diff --git a/docs/documentation/head/connect.md b/docs/documentation/head/connect.md index 0067913928..c68b9a50d0 100644 --- a/docs/documentation/head/connect.md +++ b/docs/documentation/head/connect.md @@ -71,271 +71,271 @@ Connection conn = DriverManager.getConnection(url); * **user** = String - The database user on whose behalf the connection is being made. + The database user on whose behalf the connection is being made. * **password** = String - The database user's password. + The database user's password. * **options** = String - Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. + Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. - The value of this property may contain spaces or other special characters, - and it should be properly encoded if provided in the connection URL. Spaces - are considered to separate command-line arguments, unless escaped with - a backslash (`\`); `\\` represents a literal backslash. + The value of this property may contain spaces or other special characters, + and it should be properly encoded if provided in the connection URL. Spaces + are considered to separate command-line arguments, unless escaped with + a backslash (`\`); `\\` represents a literal backslash. - ```java - Properties props = new Properties(); - props.setProperty("options","-c search_path=test,public,pg_catalog -c statement_timeout=90000"); - Connection conn = DriverManager.getConnection(url, props); + ```java + Properties props = new Properties(); + props.setProperty("options","-c search_path=test,public,pg_catalog -c statement_timeout=90000"); + Connection conn = DriverManager.getConnection(url, props); - String url = "jdbc:postgresql://localhost:5432/postgres?options=-c%20search_path=test,public,pg_catalog%20-c%20statement_timeout=90000"; - Connection conn = DriverManager.getConnection(url); - ``` + String url = "jdbc:postgresql://localhost:5432/postgres?options=-c%20search_path=test,public,pg_catalog%20-c%20statement_timeout=90000"; + Connection conn = DriverManager.getConnection(url); + ``` * **ssl** = boolean - Connect using SSL. The server must have been compiled with SSL support. - This property does not need a value associated with it. The mere presence - of it specifies a SSL connection. However, for compatibility with future - versions, the value "true" is preferred. For more information see [Chapter - 4, *Using SSL*](ssl.html). + Connect using SSL. The server must have been compiled with SSL support. + This property does not need a value associated with it. The mere presence + of it specifies a SSL connection. However, for compatibility with future + versions, the value "true" is preferred. For more information see [Chapter + 4, *Using SSL*](ssl.html). - Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples. + Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples. * **sslfactory** = String - - The provided value is a class name to use as the `SSLSocketFactory` when - establishing a SSL connection. For more information see the section - called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory + + The provided value is a class name to use as the `SSLSocketFactory` when + establishing a SSL connection. For more information see the section + called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory * **sslfactoryarg** (deprecated) = String - This value is an optional argument to the constructor of the sslfactory - class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). + This value is an optional argument to the constructor of the sslfactory + class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). * **sslmode** = String - possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` - . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the - validity of the certificate or the host name. `verify-ca` validates the certificate, but does not - verify the hostname. `verify-full` will validate that the certificate is correct and verify the - host connected to has the same hostname as the certificate. Default is `prefer` + possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` + . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the + validity of the certificate or the host name. `verify-ca` validates the certificate, but does not + verify the hostname. `verify-full` will validate that the certificate is correct and verify the + host connected to has the same hostname as the certificate. Default is `prefer` - Setting these will necessitate storing the server certificate on the client machine see - ["Configuring the client"](ssl-client.html) for details. + Setting these will necessitate storing the server certificate on the client machine see + ["Configuring the client"](ssl-client.html) for details. * **sslcert** = String - Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. + Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. - It can be a PEM encoded X509v3 certificate + It can be a PEM encoded X509v3 certificate - *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. + *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. * **sslkey** = String - Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. + Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. - *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: + *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: - `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` + `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` - PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. + PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. - If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. + If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. - *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected - by other means (e.g. access control of the OS), or the key file is transmitted in untrusted channels. - We are depending on the cryptography providers provided by the java runtime. The solution documented here is known to work at - the time of writing. If you have stricter security needs, please see https://stackoverflow.com/questions/58488774/configure-tomcat-hibernate-to-have-a-cryptographic-provider-supporting-1-2-840-1 - for a discussion of the problem and information on choosing a better cipher suite. + *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected + by other means (e.g. access control of the OS), or the key file is transmitted in untrusted channels. + We are depending on the cryptography providers provided by the java runtime. The solution documented here is known to work at + the time of writing. If you have stricter security needs, please see https://stackoverflow.com/questions/58488774/configure-tomcat-hibernate-to-have-a-cryptographic-provider-supporting-1-2-840-1 + for a discussion of the problem and information on choosing a better cipher suite. * **sslrootcert** = String - File name of the SSL root certificate. Defaults to defaultdir/root.crt + File name of the SSL root certificate. Defaults to defaultdir/root.crt - It can be a PEM encoded X509v3 certificate + It can be a PEM encoded X509v3 certificate * **sslhostnameverifier** = String - Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` + Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` * **sslpasswordcallback** = String - Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` + Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` * **sslpassword** = String - If provided will be used by ConsoleCallbackHandler + If provided will be used by ConsoleCallbackHandler * **protocolVersion** = int - The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and - the driver will by default try to connect using the V3 protocol. + The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and + the driver will by default try to connect using the V3 protocol. * **loggerLevel** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **loggerFile** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **allowEncodingChanges** = boolean - When using the V3 protocol the driver monitors changes in certain server - configuration parameters that should not be touched by end users. The - `client_encoding` setting is set by the driver and should not be altered. - If the driver detects a change it will abort the connection. There is - one legitimate exception to this behaviour though, using the `COPY` command - on a file residing on the server's filesystem. The only means of specifying - the encoding of this file is by altering the `client_encoding` setting. - The JDBC team considers this a failing of the `COPY` command and hopes to - provide an alternate means of specifying the encoding in the future, but - for now there is this URL parameter. Enable this only if you need to - override the client encoding when doing a copy. + When using the V3 protocol the driver monitors changes in certain server + configuration parameters that should not be touched by end users. The + `client_encoding` setting is set by the driver and should not be altered. + If the driver detects a change it will abort the connection. There is + one legitimate exception to this behaviour though, using the `COPY` command + on a file residing on the server's filesystem. The only means of specifying + the encoding of this file is by altering the `client_encoding` setting. + The JDBC team considers this a failing of the `COPY` command and hopes to + provide an alternate means of specifying the encoding in the future, but + for now there is this URL parameter. Enable this only if you need to + override the client encoding when doing a copy. * **logUnclosedConnections** = boolean - Clients may leak `Connection` objects by failing to call its `close()` - method. Eventually these objects will be garbage collected and the - `finalize()` method will be called which will close the `Connection` if - caller has neglected to do this himself. The usage of a finalizer is just - a stopgap solution. To help developers detect and correct the source of - these leaks the `logUnclosedConnections` URL parameter has been added. - It captures a stacktrace at each `Connection` opening and if the `finalize()` - method is reached without having been closed the stacktrace is printed - to the log. + Clients may leak `Connection` objects by failing to call its `close()` + method. Eventually these objects will be garbage collected and the + `finalize()` method will be called which will close the `Connection` if + caller has neglected to do this himself. The usage of a finalizer is just + a stopgap solution. To help developers detect and correct the source of + these leaks the `logUnclosedConnections` URL parameter has been added. + It captures a stacktrace at each `Connection` opening and if the `finalize()` + method is reached without having been closed the stacktrace is printed + to the log. * **autosave** = String - Specifies what the driver should do if a query fails. In `autosave=always` mode, JDBC driver sets a savepoint before each query, - and rolls back to that savepoint in case of failure. In `autosave=never` mode (default), no savepoint dance is made ever. - In `autosave=conservative` mode, savepoint is set for each query, however the rollback is done only for rare cases - like 'cached statement cannot change return type' or 'statement XXX is not valid' so JDBC driver rollsback and retries + Specifies what the driver should do if a query fails. In `autosave=always` mode, JDBC driver sets a savepoint before each query, + and rolls back to that savepoint in case of failure. In `autosave=never` mode (default), no savepoint dance is made ever. + In `autosave=conservative` mode, savepoint is set for each query, however the rollback is done only for rare cases + like 'cached statement cannot change return type' or 'statement XXX is not valid' so JDBC driver rollsback and retries - The default is `never` + The default is `never` * **cleanupSavepoints** = boolean - Determines if the SAVEPOINT created in autosave mode is released prior to the statement. This is - done to avoid running out of shared buffers on the server in the case where 1000's of queries are - performed. - - The default is 'false' + Determines if the SAVEPOINT created in autosave mode is released prior to the statement. This is + done to avoid running out of shared buffers on the server in the case where 1000's of queries are + performed. + + The default is 'false' * **binaryTransfer** = boolean - Use binary format for sending and receiving data if possible. + Use binary format for sending and receiving data if possible. - The default is 'true' + The default is 'true' * **binaryTransferEnable** = String - A comma separated list of types to enable binary transfer. Either OID numbers or names. + A comma separated list of types to enable binary transfer. Either OID numbers or names. * **binaryTransferDisable** = String - A comma separated list of types to disable binary transfer. Either OID numbers or names. - Overrides values in the driver default set and values set with binaryTransferEnable. + A comma separated list of types to disable binary transfer. Either OID numbers or names. + Overrides values in the driver default set and values set with binaryTransferEnable. * **databaseMetadataCacheFields** = int - Specifies the maximum number of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum number of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 65536. + Defaults to 65536. * **databaseMetadataCacheFieldsMiB** = int - Specifies the maximum size (in megabytes) of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum size (in megabytes) of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 5. + Defaults to 5. * **prepareThreshold** = int - Determine the number of `PreparedStatement` executions required before - switching over to use server side prepared statements. The default is - five, meaning start using server side prepared statements on the fifth - execution of the same `PreparedStatement` object. More information on - server side prepared statements is available in the section called - [“Server Prepared Statements”](server-prepare.html). + Determine the number of `PreparedStatement` executions required before + switching over to use server side prepared statements. The default is + five, meaning start using server side prepared statements on the fifth + execution of the same `PreparedStatement` object. More information on + server side prepared statements is available in the section called + [“Server Prepared Statements”](server-prepare.html). * **preparedStatementCacheQueries** = int - Determine the number of queries that are cached in each connection. - The default is 256, meaning if you use more than 256 different queries - in `prepareStatement()` calls, the least recently used ones - will be discarded. The cache allows application to benefit from - [“Server Prepared Statements”](server-prepare.html) - (see `prepareThreshold`) even if the prepared statement is - closed after each execution. The value of 0 disables the cache. + Determine the number of queries that are cached in each connection. + The default is 256, meaning if you use more than 256 different queries + in `prepareStatement()` calls, the least recently used ones + will be discarded. The cache allows application to benefit from + [“Server Prepared Statements”](server-prepare.html) + (see `prepareThreshold`) even if the prepared statement is + closed after each execution. The value of 0 disables the cache. - N.B.Each connection has its own statement cache. + N.B.Each connection has its own statement cache. * **preparedStatementCacheSizeMiB** = int - Determine the maximum size (in mebibytes) of the prepared queries cache - (see `preparedStatementCacheQueries`). - The default is 5, meaning if you happen to cache more than 5 MiB of queries - the least recently used ones will be discarded. - The main aim of this setting is to prevent `OutOfMemoryError`. - The value of 0 disables the cache. + Determine the maximum size (in mebibytes) of the prepared queries cache + (see `preparedStatementCacheQueries`). + The default is 5, meaning if you happen to cache more than 5 MiB of queries + the least recently used ones will be discarded. + The main aim of this setting is to prevent `OutOfMemoryError`. + The value of 0 disables the cache. * **preferQueryMode** = String - Specifies which mode is used to execute queries to database: simple means ('Q' execute, no parse, no bind, text mode only), - extended means always use bind/execute messages, extendedForPrepared means extended for prepared statements only, - extendedCacheEverything means use extended protocol and try cache every statement - (including Statement.execute(String sql)) in a query cache. - extended | extendedForPrepared | extendedCacheEverything | simple + Specifies which mode is used to execute queries to database: simple means ('Q' execute, no parse, no bind, text mode only), + extended means always use bind/execute messages, extendedForPrepared means extended for prepared statements only, + extendedCacheEverything means use extended protocol and try cache every statement + (including Statement.execute(String sql)) in a query cache. + extended | extendedForPrepared | extendedCacheEverything | simple - The default is extended + The default is extended * **defaultRowFetchSize** = int - Determine the number of rows fetched in `ResultSet` - by one fetch with trip to the database. Limiting the number of rows are fetch with - each trip to the database allow avoids unnecessary memory consumption - and as a consequence `OutOfMemoryError`. + Determine the number of rows fetched in `ResultSet` + by one fetch with trip to the database. Limiting the number of rows are fetch with + each trip to the database allow avoids unnecessary memory consumption + and as a consequence `OutOfMemoryError`. - The default is zero, meaning that in `ResultSet` will be fetch all rows at once. - Negative number is not available. + The default is zero, meaning that in `ResultSet` will be fetch all rows at once. + Negative number is not available. * **loginTimeout** = int - Specify how long to wait for establishment of a database connection. The - timeout is specified in seconds. + Specify how long to wait for establishment of a database connection. The + timeout is specified in seconds. * **connectTimeout** = int - The timeout value used for socket connect operations. If connecting to the server - takes longer than this value, the connection is broken. - The timeout is specified in seconds and a value of zero means that it is disabled. + The timeout value used for socket connect operations. If connecting to the server + takes longer than this value, the connection is broken. + The timeout is specified in seconds and a value of zero means that it is disabled. * **socketTimeout** = int - The timeout value used for socket read operations. If reading from the - server takes longer than this value, the connection is closed. This can - be used as both a brute force global query timeout and a method of - detecting network problems. The timeout is specified in seconds and a - value of zero means that it is disabled. + The timeout value used for socket read operations. If reading from the + server takes longer than this value, the connection is closed. This can + be used as both a brute force global query timeout and a method of + detecting network problems. The timeout is specified in seconds and a + value of zero means that it is disabled. * **sslResponseTimeout** = int - The timeout value in milliseconds that we wait for a response from the server - after requesting the connection be upgraded to SSL. + The timeout value in milliseconds that we wait for a response from the server + after requesting the connection be upgraded to SSL. * **cancelSignalTimeout** = int - Cancel command is sent out of band over its own connection, so cancel message can itself get - stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. - The timeout is specified in seconds. Default value is 10 seconds. + Cancel command is sent out of band over its own connection, so cancel message can itself get + stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. + The timeout is specified in seconds. Default value is 10 seconds. * **tcpKeepAlive** = boolean @@ -369,9 +369,9 @@ Connection conn = DriverManager.getConnection(url); * **ApplicationName** = String - Specifies the name of the application that is using the connection. - This allows a database administrator to see what applications are - connected to the server and what resources they are using through views like pg_stat_activity. + Specifies the name of the application that is using the connection. + This allows a database administrator to see what applications are + connected to the server and what resources they are using through views like pg_stat_activity. * **kerberosServerName** = String @@ -393,14 +393,14 @@ Connection conn = DriverManager.getConnection(url); * **gssEncMode** = String - PostgreSQL 12 and later now allow GSSAPI encrypted connections. This parameter controls whether to - enforce using GSSAPI encryption or not. The options are `disable`, `allow`, `prefer` and `require` - `disable` is obvious and disables any attempt to connect using GSS encrypted mode - `allow` will connect in plain text then if the server requests it will switch to encrypted mode - `prefer` will attempt connect in encrypted mode and fall back to plain text if it fails to acquire - an encrypted connection - `require` attempts to connect in encrypted mode and will fail to connect if that is not possible. - The default is `allow`. + PostgreSQL 12 and later now allow GSSAPI encrypted connections. This parameter controls whether to + enforce using GSSAPI encryption or not. The options are `disable`, `allow`, `prefer` and `require` + `disable` is obvious and disables any attempt to connect using GSS encrypted mode + `allow` will connect in plain text then if the server requests it will switch to encrypted mode + `prefer` will attempt connect in encrypted mode and fall back to plain text if it fails to acquire + an encrypted connection + `require` attempts to connect in encrypted mode and will fail to connect if that is not possible. + The default is `allow`. * **gsslib** = String @@ -418,10 +418,10 @@ Connection conn = DriverManager.getConnection(url); On non-Windows platforms or where SSPI is unavailable, forcing sspi mode will fail with a PSQLException. - To use SSPI with PgJDBC you must ensure that - [the `waffle-jna` library](https://mvnrepository.com/artifact/com.github.waffle/waffle-jna/) + To use SSPI with PgJDBC you must ensure that + [the `waffle-jna` library](https://mvnrepository.com/artifact/com.github.waffle/waffle-jna/) and its dependencies are present on the `CLASSPATH`. PgJDBC does *not* - bundle `waffle-jna` in the PgJDBC jar. + bundle `waffle-jna` in the PgJDBC jar. Since: 9.4 @@ -540,43 +540,43 @@ Connection conn = DriverManager.getConnection(url); * **maxResultBuffer** = String - Specifies size of result buffer in bytes, which can't be exceeded during reading result set. - Property can be specified in two styles: - - as size of bytes (i.e. 100, 150M, 300K, 400G, 1T); - - as percent of max heap memory (i.e. 10p, 15pct, 20percent); - - A limit during setting of property is 90% of max heap memory. All given values, which gonna be higher than limit, gonna lowered to the limit. - + Specifies size of result buffer in bytes, which can't be exceeded during reading result set. + Property can be specified in two styles: + - as size of bytes (i.e. 100, 150M, 300K, 400G, 1T); + - as percent of max heap memory (i.e. 10p, 15pct, 20percent); + + A limit during setting of property is 90% of max heap memory. All given values, which gonna be higher than limit, gonna lowered to the limit. + By default, maxResultBuffer is not set (is null), what means that reading of results gonna be performed without limits. * **adaptiveFetch** = boolean - Specifies if number of rows, fetched in `ResultSet` by one fetch with trip to the database, should be dynamic. - Using dynamic number of rows, computed by adaptive fetch, allows to use most of the buffer declared in `maxResultBuffer` property. - Number of rows would be calculated by dividing `maxResultBuffer` size into max row size observed so far, rounded down. - First fetch will have number of rows declared in `defaultRowFetchSize`. - Number of rows can be limited by `adaptiveFetchMinimum` and `adaptiveFetchMaximum`. - Requires declaring of `maxResultBuffer` and `defaultRowFetchSize` to work. - - By default, adaptiveFetch is false. - + Specifies if number of rows, fetched in `ResultSet` by one fetch with trip to the database, should be dynamic. + Using dynamic number of rows, computed by adaptive fetch, allows to use most of the buffer declared in `maxResultBuffer` property. + Number of rows would be calculated by dividing `maxResultBuffer` size into max row size observed so far, rounded down. + First fetch will have number of rows declared in `defaultRowFetchSize`. + Number of rows can be limited by `adaptiveFetchMinimum` and `adaptiveFetchMaximum`. + Requires declaring of `maxResultBuffer` and `defaultRowFetchSize` to work. + + By default, adaptiveFetch is false. + * **adaptiveFetchMinimum** = int - Specifies the lowest number of rows which can be calculated by `adaptiveFetch`. - Requires `adaptiveFetch` set to true to work. - - By default, minimum of rows calculated by `adaptiveFetch` is 0. + Specifies the lowest number of rows which can be calculated by `adaptiveFetch`. + Requires `adaptiveFetch` set to true to work. + + By default, minimum of rows calculated by `adaptiveFetch` is 0. * **adaptiveFetchMaximum** = int Specifies the highest number of rows which can be calculated by `adaptiveFetch`. - Requires `adaptiveFetch` set to true to work. + Requires `adaptiveFetch` set to true to work. - By default, maximum of rows calculated by `adaptiveFetch` is -1, which is understood as infinite. + By default, maximum of rows calculated by `adaptiveFetch` is -1, which is understood as infinite. * **logServerErrorDetail** == boolean - Whether to include server error details in exceptions and log messages (for example inlined query parameters). + Whether to include server error details in exceptions and log messages (for example inlined query parameters). Setting to false will only include minimal, not sensitive messages. By default this is set to true, server error details are propagated. This may include sensitive details such as query parameters. From 67c0e52432d3e868dd16d380462b2b3caf0ddf71 Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Mon, 18 Jul 2022 14:55:10 -0400 Subject: [PATCH 5/6] fix spacing --- README.md | 110 ++++----- docs/documentation/head/connect.md | 364 ++++++++++++++--------------- 2 files changed, 237 insertions(+), 237 deletions(-) diff --git a/README.md b/README.md index 6d0c060bf0..8263f5a1fc 100644 --- a/README.md +++ b/README.md @@ -88,62 +88,62 @@ Note that the most detailed log levels, "`FINEST`", may include sensitive inform #### Connection Properties In addition to the standard connection parameters the driver supports a number of additional properties which can be used to specify additional driver behaviour specific to PostgreSQL™. These properties may be specified in either the connection URL or an additional Properties object parameter to DriverManager.getConnection. -| Property | Type | Default | Description | -|-------------------------------| ------- | :-----: |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| user | String | null | The database user on whose behalf the connection is being made. | -| password | String | null | The database user's password. | -| options | String | null | Specify 'options' connection initialization parameter. | +| Property | Type | Default | Description | +| ----------------------------- | ------- | :-----: | ------------- | +| user | String | null | The database user on whose behalf the connection is being made. | +| password | String | null | The database user's password. | +| options | String | null | Specify 'options' connection initialization parameter. | | service | String | null | Specify 'service' name described in pg_service.conf file. References: [The Connection Service File](https://www.postgresql.org/docs/current/libpq-pgservice.html) and [The Password File](https://www.postgresql.org/docs/current/libpq-pgpass.html). 'service' file can provide all properties including 'hostname=', 'port=' and 'dbname='. | -| ssl | Boolean | false | Control use of SSL (true value causes SSL to be required) | -| sslfactory | String | null | Provide a SSLSocketFactory class when using SSL. | -| sslfactoryarg (deprecated) | String | null | Argument forwarded to constructor of SSLSocketFactory class. | -| sslmode | String | prefer | Controls the preference for opening using an SSL encrypted connection. | -| sslcert | String | null | The location of the client's SSL certificate | -| sslkey | String | null | The location of the client's PKCS#8 SSL key | -| sslrootcert | String | null | The location of the root certificate for authenticating the server. | -| sslhostnameverifier | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.net.ssl.HostnameVerifier and can verify the server hostname. | -| sslpasswordcallback | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.security.auth.callback.CallbackHandler and can handle PasswordCallback for the ssl password. | -| sslpassword | String | null | The password for the client's ssl key (ignored if sslpasswordcallback is set) | -| sendBufferSize | Integer | -1 | Socket write buffer size | -| receiveBufferSize | Integer | -1 | Socket read buffer size | -| logServerErrorDetail | Boolean | true | Allows server error detail (such as sql statements and values) to be logged and passed on in exceptions. Setting to false will mask these errors so they won't be exposed to users, or logs. | -| allowEncodingChanges | Boolean | false | Allow for changes in client_encoding | -| logUnclosedConnections | Boolean | false | When connections that are not explicitly closed are garbage collected, log the stacktrace from the opening of the connection to trace the leak source | -| binaryTransferEnable | String | "" | Comma separated list of types to enable binary transfer. Either OID numbers or names | -| binaryTransferDisable | String | "" | Comma separated list of types to disable binary transfer. Either OID numbers or names. Overrides values in the driver default set and values set with binaryTransferEnable. | -| prepareThreshold | Integer | 5 | Statement prepare threshold. A value of -1 stands for forceBinary | -| preparedStatementCacheQueries | Integer | 256 | Specifies the maximum number of entries in per-connection cache of prepared statements. A value of 0 disables the cache. | -| preparedStatementCacheSizeMiB | Integer | 5 | Specifies the maximum size (in megabytes) of a per-connection prepared statement cache. A value of 0 disables the cache. | -| defaultRowFetchSize | Integer | 0 | Positive number of rows that should be fetched from the database when more rows are needed for ResultSet by each fetch iteration | -| loginTimeout | Integer | 0 | Specify how long to wait for establishment of a database connection. | -| connectTimeout | Integer | 10 | The timeout value used for socket connect operations. | -| socketTimeout | Integer | 0 | The timeout value used for socket read operations. | -| sslResponseTimeout | Integer | 5000 | Socket timeout waiting for a response from a request for SSL upgrade from the server. | | -| tcpKeepAlive | Boolean | false | Enable or disable TCP keep-alive. | -| tcpNoDelay | Boolean | true | Enable or disable TCP no delay. | -| ApplicationName | String | PostgreSQL JDBC Driver | The application name (require server version >= 9.0). If assumeMinServerVersion is set to >= 9.0 this will be sent in the startup packets, otherwise after the connection is made | -| readOnly | Boolean | false | Puts this connection in read-only mode | -| disableColumnSanitiser | Boolean | false | Enable optimization that disables column name sanitiser | -| assumeMinServerVersion | String | null | Assume the server is at least that version | -| currentSchema | String | null | Specify the schema (or several schema separated by commas) to be set in the search-path | -| targetServerType | String | any | Specifies what kind of server to connect, possible values: any, master, slave (deprecated), secondary, preferSlave (deprecated), preferSecondary, preferPrimary | -| hostRecheckSeconds | Integer | 10 | Specifies period (seconds) after which the host status is checked again in case it has changed | -| loadBalanceHosts | Boolean | false | If disabled hosts are connected in the given order. If enabled hosts are chosen randomly from the set of suitable candidates | -| socketFactory | String | null | Specify a socket factory for socket creation | -| socketFactoryArg (deprecated) | String | null | Argument forwarded to constructor of SocketFactory class. | -| autosave | String | never | Specifies what the driver should do if a query fails, possible values: always, never, conservative | -| cleanupSavepoints | Boolean | false | In Autosave mode the driver sets a SAVEPOINT for every query. It is possible to exhaust the server shared buffers. Setting this to true will release each SAVEPOINT at the cost of an additional round trip. | -| preferQueryMode | String | extended | Specifies which mode is used to execute queries to database, possible values: extended, extendedForPrepared, extendedCacheEverything, simple | -| reWriteBatchedInserts | Boolean | false | Enable optimization to rewrite and collapse compatible INSERT statements that are batched. | -| escapeSyntaxCallMode | String | select | Specifies how JDBC escape call syntax is transformed into underlying SQL (CALL/SELECT), for invoking procedures or functions (requires server version >= 11), possible values: select, callIfNoReturn, call | -| maxResultBuffer | String | null | Specifies size of result buffer in bytes, which can't be exceeded during reading result set. Can be specified as particular size (i.e. "100", "200M" "2G") or as percent of max heap memory (i.e. "10p", "20pct", "50percent") | -| gssEncMode | String | allow | Controls the preference for using GSSAPI encryption for the connection, values are disable, allow, prefer, and require | -| adaptiveFetch | Boolean | false | Specifies if number of rows fetched in ResultSet by each fetch iteration should be dynamic. Number of rows will be calculated by dividing maxResultBuffer size into max row size observed so far. Requires declaring maxResultBuffer and defaultRowFetchSize for first iteration. -| adaptiveFetchMinimum | Integer | 0 | Specifies minimum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go below this value. -| adaptiveFetchMaximum | Integer | -1 | Specifies maximum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go above this value. Any negative number set as adaptiveFetchMaximum is used by adaptiveFetch as infinity number of rows. -| localSocketAddress | String | null | Hostname or IP address given to explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. -| quoteReturningIdentifiers | Boolean | true | By default we double quote returning identifiers. Some ORM's already quote them. Switch allows them to turn this off -| authenticationPluginClassName | String | null | Fully qualified class name of the class implementing the AuthenticationPlugin interface. If this is null, the password value in the connection properties will be used. +| ssl | Boolean | false | Control use of SSL (true value causes SSL to be required) | +| sslfactory | String | null | Provide a SSLSocketFactory class when using SSL. | +| sslfactoryarg (deprecated) | String | null | Argument forwarded to constructor of SSLSocketFactory class. | +| sslmode | String | prefer | Controls the preference for opening using an SSL encrypted connection. | +| sslcert | String | null | The location of the client's SSL certificate | +| sslkey | String | null | The location of the client's PKCS#8 SSL key | +| sslrootcert | String | null | The location of the root certificate for authenticating the server. | +| sslhostnameverifier | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.net.ssl.HostnameVerifier and can verify the server hostname. | +| sslpasswordcallback | String | null | The name of a class (for use in [Class.forName(String)](https://docs.oracle.com/javase/6/docs/api/java/lang/Class.html#forName%28java.lang.String%29)) that implements javax.security.auth.callback.CallbackHandler and can handle PasswordCallback for the ssl password. | +| sslpassword | String | null | The password for the client's ssl key (ignored if sslpasswordcallback is set) | +| sendBufferSize | Integer | -1 | Socket write buffer size | +| receiveBufferSize | Integer | -1 | Socket read buffer size | +| logServerErrorDetail | Boolean | true | Allows server error detail (such as sql statements and values) to be logged and passed on in exceptions. Setting to false will mask these errors so they won't be exposed to users, or logs. | +| allowEncodingChanges | Boolean | false | Allow for changes in client_encoding | +| logUnclosedConnections | Boolean | false | When connections that are not explicitly closed are garbage collected, log the stacktrace from the opening of the connection to trace the leak source | +| binaryTransferEnable | String | "" | Comma separated list of types to enable binary transfer. Either OID numbers or names | +| binaryTransferDisable | String | "" | Comma separated list of types to disable binary transfer. Either OID numbers or names. Overrides values in the driver default set and values set with binaryTransferEnable. | +| prepareThreshold | Integer | 5 | Statement prepare threshold. A value of -1 stands for forceBinary | +| preparedStatementCacheQueries | Integer | 256 | Specifies the maximum number of entries in per-connection cache of prepared statements. A value of 0 disables the cache. | +| preparedStatementCacheSizeMiB | Integer | 5 | Specifies the maximum size (in megabytes) of a per-connection prepared statement cache. A value of 0 disables the cache. | +| defaultRowFetchSize | Integer | 0 | Positive number of rows that should be fetched from the database when more rows are needed for ResultSet by each fetch iteration | +| loginTimeout | Integer | 0 | Specify how long to wait for establishment of a database connection.| +| connectTimeout | Integer | 10 | The timeout value used for socket connect operations. | +| socketTimeout | Integer | 0 | The timeout value used for socket read operations. | +| sslResponseTimeout | Integer | 5000 | Socket timeout waiting for a response from a request for SSL upgrade from the server. | +| tcpKeepAlive | Boolean | false | Enable or disable TCP keep-alive. | +| tcpNoDelay | Boolean | true | Enable or disable TCP no delay. | +| ApplicationName | String | PostgreSQL JDBC Driver | The application name (require server version >= 9.0). If assumeMinServerVersion is set to >= 9.0 this will be sent in the startup packets, otherwise after the connection is made | +| readOnly | Boolean | false | Puts this connection in read-only mode | +| disableColumnSanitiser | Boolean | false | Enable optimization that disables column name sanitiser | +| assumeMinServerVersion | String | null | Assume the server is at least that version | +| currentSchema | String | null | Specify the schema (or several schema separated by commas) to be set in the search-path | +| targetServerType | String | any | Specifies what kind of server to connect, possible values: any, master, slave (deprecated), secondary, preferSlave (deprecated), preferSecondary, preferPrimary | +| hostRecheckSeconds | Integer | 10 | Specifies period (seconds) after which the host status is checked again in case it has changed | +| loadBalanceHosts | Boolean | false | If disabled hosts are connected in the given order. If enabled hosts are chosen randomly from the set of suitable candidates | +| socketFactory | String | null | Specify a socket factory for socket creation | +| socketFactoryArg (deprecated) | String | null | Argument forwarded to constructor of SocketFactory class. | +| autosave | String | never | Specifies what the driver should do if a query fails, possible values: always, never, conservative | +| cleanupSavepoints | Boolean | false | In Autosave mode the driver sets a SAVEPOINT for every query. It is possible to exhaust the server shared buffers. Setting this to true will release each SAVEPOINT at the cost of an additional round trip. | +| preferQueryMode | String | extended | Specifies which mode is used to execute queries to database, possible values: extended, extendedForPrepared, extendedCacheEverything, simple | +| reWriteBatchedInserts | Boolean | false | Enable optimization to rewrite and collapse compatible INSERT statements that are batched. | +| escapeSyntaxCallMode | String | select | Specifies how JDBC escape call syntax is transformed into underlying SQL (CALL/SELECT), for invoking procedures or functions (requires server version >= 11), possible values: select, callIfNoReturn, call | +| maxResultBuffer | String | null | Specifies size of result buffer in bytes, which can't be exceeded during reading result set. Can be specified as particular size (i.e. "100", "200M" "2G") or as percent of max heap memory (i.e. "10p", "20pct", "50percent") | +| gssEncMode | String | allow | Controls the preference for using GSSAPI encryption for the connection, values are disable, allow, prefer, and require | +| adaptiveFetch | Boolean | false | Specifies if number of rows fetched in ResultSet by each fetch iteration should be dynamic. Number of rows will be calculated by dividing maxResultBuffer size into max row size observed so far. Requires declaring maxResultBuffer and defaultRowFetchSize for first iteration. +| adaptiveFetchMinimum | Integer | 0 | Specifies minimum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go below this value. +| adaptiveFetchMaximum | Integer | -1 | Specifies maximum number of rows, which can be calculated by adaptiveFetch. Number of rows used by adaptiveFetch cannot go above this value. Any negative number set as adaptiveFetchMaximum is used by adaptiveFetch as infinity number of rows. +| localSocketAddress | String | null | Hostname or IP address given to explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. +| quoteReturningIdentifiers | Boolean | true | By default we double quote returning identifiers. Some ORM's already quote them. Switch allows them to turn this off +| authenticationPluginClassName | String | null | Fully qualified class name of the class implementing the AuthenticationPlugin interface. If this is null, the password value in the connection properties will be used. ## Contributing For information on how to contribute to the project see the [Contributing Guidelines](CONTRIBUTING.md) diff --git a/docs/documentation/head/connect.md b/docs/documentation/head/connect.md index c68b9a50d0..4ae093a8f7 100644 --- a/docs/documentation/head/connect.md +++ b/docs/documentation/head/connect.md @@ -71,271 +71,271 @@ Connection conn = DriverManager.getConnection(url); * **user** = String - The database user on whose behalf the connection is being made. + The database user on whose behalf the connection is being made. * **password** = String - The database user's password. + The database user's password. * **options** = String - Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. + Specify 'options' connection initialization parameter. For example setting this to `-c statement_timeout=5min` would set the statement timeout parameter for this session to 5 minutes. - The value of this property may contain spaces or other special characters, - and it should be properly encoded if provided in the connection URL. Spaces - are considered to separate command-line arguments, unless escaped with - a backslash (`\`); `\\` represents a literal backslash. + The value of this property may contain spaces or other special characters, + and it should be properly encoded if provided in the connection URL. Spaces + are considered to separate command-line arguments, unless escaped with + a backslash (`\`); `\\` represents a literal backslash. - ```java - Properties props = new Properties(); - props.setProperty("options","-c search_path=test,public,pg_catalog -c statement_timeout=90000"); - Connection conn = DriverManager.getConnection(url, props); + ```java + Properties props = new Properties(); + props.setProperty("options","-c search_path=test,public,pg_catalog -c statement_timeout=90000"); + Connection conn = DriverManager.getConnection(url, props); - String url = "jdbc:postgresql://localhost:5432/postgres?options=-c%20search_path=test,public,pg_catalog%20-c%20statement_timeout=90000"; - Connection conn = DriverManager.getConnection(url); - ``` + String url = "jdbc:postgresql://localhost:5432/postgres?options=-c%20search_path=test,public,pg_catalog%20-c%20statement_timeout=90000"; + Connection conn = DriverManager.getConnection(url); + ``` * **ssl** = boolean - Connect using SSL. The server must have been compiled with SSL support. - This property does not need a value associated with it. The mere presence - of it specifies a SSL connection. However, for compatibility with future - versions, the value "true" is preferred. For more information see [Chapter - 4, *Using SSL*](ssl.html). + Connect using SSL. The server must have been compiled with SSL support. + This property does not need a value associated with it. The mere presence + of it specifies a SSL connection. However, for compatibility with future + versions, the value "true" is preferred. For more information see [Chapter + 4, *Using SSL*](ssl.html). - Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples. + Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples. * **sslfactory** = String - - The provided value is a class name to use as the `SSLSocketFactory` when - establishing a SSL connection. For more information see the section - called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory + + The provided value is a class name to use as the `SSLSocketFactory` when + establishing a SSL connection. For more information see the section + called [“Custom SSLSocketFactory”](ssl-factory.html). defaults to LibPQFactory * **sslfactoryarg** (deprecated) = String - This value is an optional argument to the constructor of the sslfactory - class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). + This value is an optional argument to the constructor of the sslfactory + class provided above. For more information see the section called [“Custom SSLSocketFactory”](ssl-factory.html). * **sslmode** = String - possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` - . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the - validity of the certificate or the host name. `verify-ca` validates the certificate, but does not - verify the hostname. `verify-full` will validate that the certificate is correct and verify the - host connected to has the same hostname as the certificate. Default is `prefer` + possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full` + . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the + validity of the certificate or the host name. `verify-ca` validates the certificate, but does not + verify the hostname. `verify-full` will validate that the certificate is correct and verify the + host connected to has the same hostname as the certificate. Default is `prefer` - Setting these will necessitate storing the server certificate on the client machine see - ["Configuring the client"](ssl-client.html) for details. + Setting these will necessitate storing the server certificate on the client machine see + ["Configuring the client"](ssl-client.html) for details. * **sslcert** = String - Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. + Provide the full path for the certificate file. Defaults to /defaultdir/postgresql.crt, where defaultdir is ${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows. - It can be a PEM encoded X509v3 certificate + It can be a PEM encoded X509v3 certificate - *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. + *Note:* This parameter is ignored when using PKCS-12 keys, since in that case the certificate is also retrieved from the same keyfile. * **sslkey** = String - Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. + Provide the full path for the key file. Defaults to /defaultdir/postgresql.pk8. - *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: + *Note:* The key file **must** be in [PKCS-12](https://en.wikipedia.org/wiki/PKCS_12) or in [PKCS-8](https://en.wikipedia.org/wiki/PKCS_8) [DER format](https://wiki.openssl.org/index.php/DER). A PEM key can be converted to DER format using the openssl command: - `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` + `openssl pkcs8 -topk8 -inform PEM -in postgresql.key -outform DER -out postgresql.pk8 -v1 PBE-MD5-DES` - PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. + PKCS-12 key files are only recognized if they have the ".p12" (42.2.9+) or the ".pfx" (42.2.16+) extension. - If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. + If your key has a password, provide it using the `sslpassword` connection parameter described below. Otherwise, you can add the flag `-nocrypt` to the above command to prevent the driver from requesting a password. - *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected - by other means (e.g. access control of the OS), or the key file is transmitted in untrusted channels. - We are depending on the cryptography providers provided by the java runtime. The solution documented here is known to work at - the time of writing. If you have stricter security needs, please see https://stackoverflow.com/questions/58488774/configure-tomcat-hibernate-to-have-a-cryptographic-provider-supporting-1-2-840-1 - for a discussion of the problem and information on choosing a better cipher suite. + *Note:* The use of -v1 PBE-MD5-DES might be inadequate in environments where high level of security is needed and the key is not protected + by other means (e.g. access control of the OS), or the key file is transmitted in untrusted channels. + We are depending on the cryptography providers provided by the java runtime. The solution documented here is known to work at + the time of writing. If you have stricter security needs, please see https://stackoverflow.com/questions/58488774/configure-tomcat-hibernate-to-have-a-cryptographic-provider-supporting-1-2-840-1 + for a discussion of the problem and information on choosing a better cipher suite. * **sslrootcert** = String - File name of the SSL root certificate. Defaults to defaultdir/root.crt + File name of the SSL root certificate. Defaults to defaultdir/root.crt - It can be a PEM encoded X509v3 certificate + It can be a PEM encoded X509v3 certificate * **sslhostnameverifier** = String - Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` + Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier` * **sslpasswordcallback** = String - Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` + Class name of the SSL password provider. Defaults to `org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler` * **sslpassword** = String - If provided will be used by ConsoleCallbackHandler + If provided will be used by ConsoleCallbackHandler * **protocolVersion** = int - The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and - the driver will by default try to connect using the V3 protocol. + The driver supports the V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and + the driver will by default try to connect using the V3 protocol. * **loggerLevel** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **loggerFile** = String - This property is no longer used by the driver and will be ignored. - All logging configuration is handled by java.util.logging. + This property is no longer used by the driver and will be ignored. + All logging configuration is handled by java.util.logging. * **allowEncodingChanges** = boolean - When using the V3 protocol the driver monitors changes in certain server - configuration parameters that should not be touched by end users. The - `client_encoding` setting is set by the driver and should not be altered. - If the driver detects a change it will abort the connection. There is - one legitimate exception to this behaviour though, using the `COPY` command - on a file residing on the server's filesystem. The only means of specifying - the encoding of this file is by altering the `client_encoding` setting. - The JDBC team considers this a failing of the `COPY` command and hopes to - provide an alternate means of specifying the encoding in the future, but - for now there is this URL parameter. Enable this only if you need to - override the client encoding when doing a copy. + When using the V3 protocol the driver monitors changes in certain server + configuration parameters that should not be touched by end users. The + `client_encoding` setting is set by the driver and should not be altered. + If the driver detects a change it will abort the connection. There is + one legitimate exception to this behaviour though, using the `COPY` command + on a file residing on the server's filesystem. The only means of specifying + the encoding of this file is by altering the `client_encoding` setting. + The JDBC team considers this a failing of the `COPY` command and hopes to + provide an alternate means of specifying the encoding in the future, but + for now there is this URL parameter. Enable this only if you need to + override the client encoding when doing a copy. * **logUnclosedConnections** = boolean - Clients may leak `Connection` objects by failing to call its `close()` - method. Eventually these objects will be garbage collected and the - `finalize()` method will be called which will close the `Connection` if - caller has neglected to do this himself. The usage of a finalizer is just - a stopgap solution. To help developers detect and correct the source of - these leaks the `logUnclosedConnections` URL parameter has been added. - It captures a stacktrace at each `Connection` opening and if the `finalize()` - method is reached without having been closed the stacktrace is printed - to the log. + Clients may leak `Connection` objects by failing to call its `close()` + method. Eventually these objects will be garbage collected and the + `finalize()` method will be called which will close the `Connection` if + caller has neglected to do this himself. The usage of a finalizer is just + a stopgap solution. To help developers detect and correct the source of + these leaks the `logUnclosedConnections` URL parameter has been added. + It captures a stacktrace at each `Connection` opening and if the `finalize()` + method is reached without having been closed the stacktrace is printed + to the log. * **autosave** = String - Specifies what the driver should do if a query fails. In `autosave=always` mode, JDBC driver sets a savepoint before each query, - and rolls back to that savepoint in case of failure. In `autosave=never` mode (default), no savepoint dance is made ever. - In `autosave=conservative` mode, savepoint is set for each query, however the rollback is done only for rare cases - like 'cached statement cannot change return type' or 'statement XXX is not valid' so JDBC driver rollsback and retries + Specifies what the driver should do if a query fails. In `autosave=always` mode, JDBC driver sets a savepoint before each query, + and rolls back to that savepoint in case of failure. In `autosave=never` mode (default), no savepoint dance is made ever. + In `autosave=conservative` mode, savepoint is set for each query, however the rollback is done only for rare cases + like 'cached statement cannot change return type' or 'statement XXX is not valid' so JDBC driver rollsback and retries - The default is `never` + The default is `never` * **cleanupSavepoints** = boolean - Determines if the SAVEPOINT created in autosave mode is released prior to the statement. This is - done to avoid running out of shared buffers on the server in the case where 1000's of queries are - performed. - - The default is 'false' + Determines if the SAVEPOINT created in autosave mode is released prior to the statement. This is + done to avoid running out of shared buffers on the server in the case where 1000's of queries are + performed. + + The default is 'false' * **binaryTransfer** = boolean - Use binary format for sending and receiving data if possible. + Use binary format for sending and receiving data if possible. - The default is 'true' + The default is 'true' * **binaryTransferEnable** = String - A comma separated list of types to enable binary transfer. Either OID numbers or names. + A comma separated list of types to enable binary transfer. Either OID numbers or names. * **binaryTransferDisable** = String - A comma separated list of types to disable binary transfer. Either OID numbers or names. - Overrides values in the driver default set and values set with binaryTransferEnable. + A comma separated list of types to disable binary transfer. Either OID numbers or names. + Overrides values in the driver default set and values set with binaryTransferEnable. * **databaseMetadataCacheFields** = int - Specifies the maximum number of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum number of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 65536. + Defaults to 65536. * **databaseMetadataCacheFieldsMiB** = int - Specifies the maximum size (in megabytes) of fields to be cached per connection. - A value of 0 disables the cache. + Specifies the maximum size (in megabytes) of fields to be cached per connection. + A value of 0 disables the cache. - Defaults to 5. + Defaults to 5. * **prepareThreshold** = int - Determine the number of `PreparedStatement` executions required before - switching over to use server side prepared statements. The default is - five, meaning start using server side prepared statements on the fifth - execution of the same `PreparedStatement` object. More information on - server side prepared statements is available in the section called - [“Server Prepared Statements”](server-prepare.html). + Determine the number of `PreparedStatement` executions required before + switching over to use server side prepared statements. The default is + five, meaning start using server side prepared statements on the fifth + execution of the same `PreparedStatement` object. More information on + server side prepared statements is available in the section called + [“Server Prepared Statements”](server-prepare.html). * **preparedStatementCacheQueries** = int - Determine the number of queries that are cached in each connection. - The default is 256, meaning if you use more than 256 different queries - in `prepareStatement()` calls, the least recently used ones - will be discarded. The cache allows application to benefit from - [“Server Prepared Statements”](server-prepare.html) - (see `prepareThreshold`) even if the prepared statement is - closed after each execution. The value of 0 disables the cache. + Determine the number of queries that are cached in each connection. + The default is 256, meaning if you use more than 256 different queries + in `prepareStatement()` calls, the least recently used ones + will be discarded. The cache allows application to benefit from + [“Server Prepared Statements”](server-prepare.html) + (see `prepareThreshold`) even if the prepared statement is + closed after each execution. The value of 0 disables the cache. - N.B.Each connection has its own statement cache. + N.B.Each connection has its own statement cache. * **preparedStatementCacheSizeMiB** = int - Determine the maximum size (in mebibytes) of the prepared queries cache - (see `preparedStatementCacheQueries`). - The default is 5, meaning if you happen to cache more than 5 MiB of queries - the least recently used ones will be discarded. - The main aim of this setting is to prevent `OutOfMemoryError`. - The value of 0 disables the cache. + Determine the maximum size (in mebibytes) of the prepared queries cache + (see `preparedStatementCacheQueries`). + The default is 5, meaning if you happen to cache more than 5 MiB of queries + the least recently used ones will be discarded. + The main aim of this setting is to prevent `OutOfMemoryError`. + The value of 0 disables the cache. * **preferQueryMode** = String - Specifies which mode is used to execute queries to database: simple means ('Q' execute, no parse, no bind, text mode only), - extended means always use bind/execute messages, extendedForPrepared means extended for prepared statements only, - extendedCacheEverything means use extended protocol and try cache every statement - (including Statement.execute(String sql)) in a query cache. - extended | extendedForPrepared | extendedCacheEverything | simple + Specifies which mode is used to execute queries to database: simple means ('Q' execute, no parse, no bind, text mode only), + extended means always use bind/execute messages, extendedForPrepared means extended for prepared statements only, + extendedCacheEverything means use extended protocol and try cache every statement + (including Statement.execute(String sql)) in a query cache. + extended | extendedForPrepared | extendedCacheEverything | simple - The default is extended + The default is extended * **defaultRowFetchSize** = int - Determine the number of rows fetched in `ResultSet` - by one fetch with trip to the database. Limiting the number of rows are fetch with - each trip to the database allow avoids unnecessary memory consumption - and as a consequence `OutOfMemoryError`. + Determine the number of rows fetched in `ResultSet` + by one fetch with trip to the database. Limiting the number of rows are fetch with + each trip to the database allow avoids unnecessary memory consumption + and as a consequence `OutOfMemoryError`. - The default is zero, meaning that in `ResultSet` will be fetch all rows at once. - Negative number is not available. + The default is zero, meaning that in `ResultSet` will be fetch all rows at once. + Negative number is not available. * **loginTimeout** = int - Specify how long to wait for establishment of a database connection. The - timeout is specified in seconds. + Specify how long to wait for establishment of a database connection. The + timeout is specified in seconds. * **connectTimeout** = int - The timeout value used for socket connect operations. If connecting to the server - takes longer than this value, the connection is broken. - The timeout is specified in seconds and a value of zero means that it is disabled. + The timeout value used for socket connect operations. If connecting to the server + takes longer than this value, the connection is broken. + The timeout is specified in seconds and a value of zero means that it is disabled. * **socketTimeout** = int - The timeout value used for socket read operations. If reading from the - server takes longer than this value, the connection is closed. This can - be used as both a brute force global query timeout and a method of - detecting network problems. The timeout is specified in seconds and a - value of zero means that it is disabled. + The timeout value used for socket read operations. If reading from the + server takes longer than this value, the connection is closed. This can + be used as both a brute force global query timeout and a method of + detecting network problems. The timeout is specified in seconds and a + value of zero means that it is disabled. * **sslResponseTimeout** = int - The timeout value in milliseconds that we wait for a response from the server - after requesting the connection be upgraded to SSL. + The timeout value in milliseconds that we wait for a response from the server + after requesting the connection be upgraded to SSL. * **cancelSignalTimeout** = int - Cancel command is sent out of band over its own connection, so cancel message can itself get - stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. - The timeout is specified in seconds. Default value is 10 seconds. + Cancel command is sent out of band over its own connection, so cancel message can itself get + stuck. This property controls "connect timeout" and "socket timeout" used for cancel commands. + The timeout is specified in seconds. Default value is 10 seconds. * **tcpKeepAlive** = boolean @@ -369,9 +369,9 @@ Connection conn = DriverManager.getConnection(url); * **ApplicationName** = String - Specifies the name of the application that is using the connection. - This allows a database administrator to see what applications are - connected to the server and what resources they are using through views like pg_stat_activity. + Specifies the name of the application that is using the connection. + This allows a database administrator to see what applications are + connected to the server and what resources they are using through views like pg_stat_activity. * **kerberosServerName** = String @@ -393,14 +393,14 @@ Connection conn = DriverManager.getConnection(url); * **gssEncMode** = String - PostgreSQL 12 and later now allow GSSAPI encrypted connections. This parameter controls whether to - enforce using GSSAPI encryption or not. The options are `disable`, `allow`, `prefer` and `require` - `disable` is obvious and disables any attempt to connect using GSS encrypted mode - `allow` will connect in plain text then if the server requests it will switch to encrypted mode - `prefer` will attempt connect in encrypted mode and fall back to plain text if it fails to acquire - an encrypted connection - `require` attempts to connect in encrypted mode and will fail to connect if that is not possible. - The default is `allow`. + PostgreSQL 12 and later now allow GSSAPI encrypted connections. This parameter controls whether to + enforce using GSSAPI encryption or not. The options are `disable`, `allow`, `prefer` and `require` + `disable` is obvious and disables any attempt to connect using GSS encrypted mode + `allow` will connect in plain text then if the server requests it will switch to encrypted mode + `prefer` will attempt connect in encrypted mode and fall back to plain text if it fails to acquire + an encrypted connection + `require` attempts to connect in encrypted mode and will fail to connect if that is not possible. + The default is `allow`. * **gsslib** = String @@ -418,10 +418,10 @@ Connection conn = DriverManager.getConnection(url); On non-Windows platforms or where SSPI is unavailable, forcing sspi mode will fail with a PSQLException. - To use SSPI with PgJDBC you must ensure that - [the `waffle-jna` library](https://mvnrepository.com/artifact/com.github.waffle/waffle-jna/) + To use SSPI with PgJDBC you must ensure that + [the `waffle-jna` library](https://mvnrepository.com/artifact/com.github.waffle/waffle-jna/) and its dependencies are present on the `CLASSPATH`. PgJDBC does *not* - bundle `waffle-jna` in the PgJDBC jar. + bundle `waffle-jna` in the PgJDBC jar. Since: 9.4 @@ -540,43 +540,43 @@ Connection conn = DriverManager.getConnection(url); * **maxResultBuffer** = String - Specifies size of result buffer in bytes, which can't be exceeded during reading result set. - Property can be specified in two styles: - - as size of bytes (i.e. 100, 150M, 300K, 400G, 1T); - - as percent of max heap memory (i.e. 10p, 15pct, 20percent); - - A limit during setting of property is 90% of max heap memory. All given values, which gonna be higher than limit, gonna lowered to the limit. - + Specifies size of result buffer in bytes, which can't be exceeded during reading result set. + Property can be specified in two styles: + - as size of bytes (i.e. 100, 150M, 300K, 400G, 1T); + - as percent of max heap memory (i.e. 10p, 15pct, 20percent); + + A limit during setting of property is 90% of max heap memory. All given values, which gonna be higher than limit, gonna lowered to the limit. + By default, maxResultBuffer is not set (is null), what means that reading of results gonna be performed without limits. * **adaptiveFetch** = boolean - Specifies if number of rows, fetched in `ResultSet` by one fetch with trip to the database, should be dynamic. - Using dynamic number of rows, computed by adaptive fetch, allows to use most of the buffer declared in `maxResultBuffer` property. - Number of rows would be calculated by dividing `maxResultBuffer` size into max row size observed so far, rounded down. - First fetch will have number of rows declared in `defaultRowFetchSize`. - Number of rows can be limited by `adaptiveFetchMinimum` and `adaptiveFetchMaximum`. - Requires declaring of `maxResultBuffer` and `defaultRowFetchSize` to work. - - By default, adaptiveFetch is false. - + Specifies if number of rows, fetched in `ResultSet` by one fetch with trip to the database, should be dynamic. + Using dynamic number of rows, computed by adaptive fetch, allows to use most of the buffer declared in `maxResultBuffer` property. + Number of rows would be calculated by dividing `maxResultBuffer` size into max row size observed so far, rounded down. + First fetch will have number of rows declared in `defaultRowFetchSize`. + Number of rows can be limited by `adaptiveFetchMinimum` and `adaptiveFetchMaximum`. + Requires declaring of `maxResultBuffer` and `defaultRowFetchSize` to work. + + By default, adaptiveFetch is false. + * **adaptiveFetchMinimum** = int - Specifies the lowest number of rows which can be calculated by `adaptiveFetch`. - Requires `adaptiveFetch` set to true to work. - - By default, minimum of rows calculated by `adaptiveFetch` is 0. + Specifies the lowest number of rows which can be calculated by `adaptiveFetch`. + Requires `adaptiveFetch` set to true to work. + + By default, minimum of rows calculated by `adaptiveFetch` is 0. * **adaptiveFetchMaximum** = int Specifies the highest number of rows which can be calculated by `adaptiveFetch`. - Requires `adaptiveFetch` set to true to work. + Requires `adaptiveFetch` set to true to work. - By default, maximum of rows calculated by `adaptiveFetch` is -1, which is understood as infinite. + By default, maximum of rows calculated by `adaptiveFetch` is -1, which is understood as infinite. * **logServerErrorDetail** == boolean - Whether to include server error details in exceptions and log messages (for example inlined query parameters). + Whether to include server error details in exceptions and log messages (for example inlined query parameters). Setting to false will only include minimal, not sensitive messages. By default this is set to true, server error details are propagated. This may include sensitive details such as query parameters. From 7f63448463453a38e61a25768512b8107cddc7df Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Tue, 19 Jul 2022 07:39:10 -0400 Subject: [PATCH 6/6] Fix sort order by moving SSL_RESPONSE_TIMEOUT to correct location --- .../main/java/org/postgresql/PGProperty.java | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pgjdbc/src/main/java/org/postgresql/PGProperty.java b/pgjdbc/src/main/java/org/postgresql/PGProperty.java index fe83ff3dd4..d7851d4271 100644 --- a/pgjdbc/src/main/java/org/postgresql/PGProperty.java +++ b/pgjdbc/src/main/java/org/postgresql/PGProperty.java @@ -165,15 +165,6 @@ public enum PGProperty { "10", "The timeout value used for socket connect operations."), - /** - *

After requesting an upgrade to SSL from the server there are reports of the server not responding due to a failover - * without a timeout here, the client can wait forever. This timeout will be set before the request and reset after

- */ - SSL_RESPONSE_TIMEOUT( - "sslResponseTimeout", - "5000", - "Time in milliseconds we wait for a response from the server after requesting SSL upgrade"), - /** * Specify the schema (or several schema separated by commas) to be set in the search-path. This schema will be used to resolve * unqualified object names used in statements over this connection. @@ -681,6 +672,15 @@ public enum PGProperty { null, "A class, implementing javax.security.auth.callback.CallbackHandler that can handle PassworCallback for the ssl password."), + /** + *

After requesting an upgrade to SSL from the server there are reports of the server not responding due to a failover + * without a timeout here, the client can wait forever. This timeout will be set before the request and reset after

+ */ + SSL_RESPONSE_TIMEOUT( + "sslResponseTimeout", + "5000", + "Time in milliseconds we wait for a response from the server after requesting SSL upgrade"), + /** * File containing the root certificate when validating server ({@code sslmode} = {@code * verify-ca} or {@code verify-full}). Default will be the file {@code root.crt} in {@code