Connection Parameter Reference

Updated on 2025-02-27 GMT+08:00

View PDF

All connection properties of the info parameter are case-sensitive. Table 1 describes the common properties.

**Table 1** Connection properties of the info parameter
Property	Description	Value
PGDBNAME	Specifies the database name. You do not need to set this parameter in the URL because the database name is automatically parsed from the .properties file.	Property type: string
PGHOST	Specifies the host IP address.	Property type: string
PGPORT	Specifies the host port number.	Property type: integer
user	Specifies the database user who creates the connection.	Property type: string
password	Specifies the password of the database user.	Property type: string
driverInfoMode	Controls the output mode of the driver description information.	Property type: string Value range: postgresql or gaussdb. postgresql: The driver description related to PG is displayed. gaussdb: The driver description related to GaussDB is displayed. Default value: postgresql
loggerLevel	Specifies the logging level.	Property type: string Value range: The following logging levels are supported: OFF, INFO, DEBUG, and TRACE. OFF: The logging function is disabled. INFO, DEBUG, and TRACE logs record information of different levels. Default value: No default value is provided. If this property is not set, the value INFO is used.
loggerFile	Specifies the log output path (directory and file name). This parameter has been deprecated and does not take effect. To specify the log output path, you can configure the java.util.logging property file or system property.	Property type: string
logger	Specifies the log output framework used by the JDBC driver. The JDBC driver supports the log output framework used for interconnecting with user applications.	Property type: string Value range: Slf4JLogger If it is left empty, JDK LOGGER is used. Currently, only the Slf4j-API-based third-party log output framework is supported. For details, see Log Management.
allowEncodingChanges	If this parameter is set to true, the character set type can be changed. This parameter is used together with characterEncoding to set the character set. The two parameters are separated by ampersands (&). The value of characterEncoding can be UTF8, GBK, LATIN1, or GB18030. Example: allowEncodingChanges=true&characterEncoding=UTF8.	Property type: Boolean Value range: true: The character set type can be changed. false: The character set type cannot be changed. Default value: false
currentSchema	Specifies the schema of the current connection. You need to specify a schema in search-path. If the schema name contains special characters except letters, digits, and underscores (_), you are advised to enclose the schema name in quotation marks. Note that the schema name is case-sensitive after quotation marks are added. If multiple schemas need to be configured, separate them with commas (,). Schemas containing special characters also need to be enclosed in quotation marks. Example: currentSchema=schema_a,"schema-b","schema/c"	Property type: string Default value: If this parameter is not set, the default schema is the username used for the connection.
hostRecheckSeconds	After JDBC attempts to connect to a host, the host status is saved: connection success or connection failure. This status is trusted within the period specified by hostRecheckSeconds. After the period expires, the status becomes invalid.	Property type: integer Unit: s Value range: 0 to 2147483647. Default value: 10
ssl	Specifies that the database is connected in SSL mode. When ssl is set to true, the NonValidatingFactory channel and certificate mode are supported. 1. For the NonValidatingFactory channel, configure the username and password and set SSL to true. 2. In certification mode, configure the client certificate, key, and root certificate, and set SSL to true.	Property type: Boolean Value range: true: The database is connected in SSL mode. false: The database is not connected in SSL mode. Default value: No default value is provided. If this property is not set, the value false is used.
sslmode	This parameter specifies the SSL authentication mode.	Property type: string Value range: disable, allow, prefer, require, verify-ca, and verify-full. disable: SSL connection is disabled. allow: If the database server requires SSL connection, SSL connection can be enabled. However, authenticity of the database server will not be verified. prefer: If the database supports SSL connection, SSL connection is preferred. However, authenticity of the database server will not be verified. require: The system attempts to set up an SSL connection. If there is a CA file, the system performs verification as if the parameter was set to verify-ca. verify-ca: The system attempts to set up an SSL connection and checks whether the server certificate is issued by a trusted CA. verify-full: The system attempts to set up an SSL connection, checks whether the server certificate is issued by a trusted CA, and checks whether the host name of the server is the same as that in the certificate. Default value: No default value is provided. If this property is not set, the value require is used.
sslcert	Specifies the complete path of the certificate file. The certificate type is End Entity.	Property type: string Default value: No default value is provided. If this property is not set, the root directory of the user is read.
sslkey	Specifies the complete path of the key file. You need to convert the key to the DER format before using it. openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt	Property type: string Default value: No default value is provided. If this property is not set, the root directory of the user is read.
sslrootcert	Specifies the name of the SSL root certificate. The root certificate type is CA.	Property type: string Default value: No default value is provided. If this property is not set, the root directory of the user is read.
sslpassword	Specifies the SSL password, which is provided for ConsoleCallbackHandler.	Property type: string
sslpasswordcallback	Specifies the class name of the SSL password provider.	Property type: string Default value: No default value is provided.
sslfactory	Specifies the class name used by SSLSocketFactory to establish an SSL connection.	Property type: string Default value: No default value is provided.
sslprivatekeyfactory	This parameter specifies the fully qualified name of the implementation class of the org.postgresql.ssl.PrivateKeyFactory API that implements the private key decryption method. If this parameter is not specified, try the default JDK private key decryption algorithm. If the decryption fails, use org.postgresql.ssl.BouncyCastlePrivateKeyFactory. You need to provide the bcpkix-jdk15on.jar package. The recommended version is 1.65 or later.	Property type: string Default value: No default value is provided.
sslfactoryarg	The value is an optional parameter of the constructor function of the sslfactory class. (This parameter is not recommended.)	Property type: string Default value: No default value is provided.
sslhostnameverifier	Specifies the class name of the host name verifier. The API must implement javax.net.ssl.HostnameVerifier. The default value is com.huawei.opengauss.jdbc.ssl.PGjdbcHostnameVerifier.	Property type: string Default value: No default value is provided. If this property is not set, com.huawei.opengauss.jdbc.ssl.PGjdbcHostnameVerifier is used.
loginTimeout	Specifies the waiting time for establishing the database connection. When multiple IP addresses are configured in the URL, if the time for obtaining the connection exceeds the value of this parameter, the connection fails and the subsequent IP addresses are not tried. The value of loginTimeout is related to connectTimeout and socketTimeoutInConnecting. The calculation formula is as follows: loginTimeout = (connectTimeout + Connection authentication time + Initialization statement execution time) x Number of nodes. NOTICE: This parameter sets the time for attempting to connect to all IP addresses in a list. If this parameter is set to a small value, the subsequent IP addresses in the list may fail to be connected. For example, if three IP addresses are set, loginTimeout is set to 5s, and it takes 5s to connect to the first two IP addresses, the third IP address cannot be connected. In a centralized environment, the last IP address is the IP address of the primary node. As a result, the automatic search for the primary node may fail. When any of the CPU, memory, and I/O load approaches 100%, the connection is slow, which may cause connection timeout. You can locate the fault as follows: Log in to a physical machine with slow connections or use a management tool to query the resource load. You can run the top command to check the CPU usage, run the free command to check the memory usage, and run the iostat command to check the I/O load. In addition, you can check the monitoring logs in the CM Agent and the monitoring records on the database O&M platform. For peak load scenarios caused by a large number of slow queries in a short period of time, you can use the port specified by [Port number of the database server + 1] to query the pg_stat_activity view. For slow queries, you can use the system function pg_terminate_backend(pid int) to kill sessions. If service overloading exists for a long time (that is, there is no obvious slow query, or new queries still become slow after slow queries are killed), reduce the service load and increase database resources.	Property type: integer Unit: s Value range: 0 to 2147483647. The value 0 indicates that the timeout mechanism does not take effect. Default value: 0 Suggestion: After this parameter is set, an asynchronous thread is started each time a connection is established. If there are a large number of connections, the pressure on the client may increase. If this parameter needs to be set in a centralized environment, you are advised to set it as follows: max(connectTimeout, socketTimeoutInConnecting) x Number of nodes. This prevents connection failures when the network is abnormal and the nth IP address is the IP address of the primary node.
connectTimeout	Specifies the timeout interval for connecting to a server OS. If the time taken to connect to a server OS exceeds the value specified, the connection is interrupted. When multiple IP addresses are configured in the URL, this parameter indicates the timeout interval for connecting to a single IP address.	Property type: integer Unit: s Value range: 0 to 2147483647. The value 0 indicates that the timeout mechanism does not take effect. Default value: 0
socketTimeout	Specifies the timeout period for a socket read operation. If the time taken to read data streams from a server exceeds the value specified, the connection is closed. If this parameter is not set, the client waits for a long time when the database process is abnormal. You are advised to set this parameter based on the SQL execution time acceptable to services. NOTE: When the timeout is triggered on the JDBC side and the connection is closed, the running services delivered by the JDBC to the database are forcibly terminated. The capability of forcibly terminating a service is controlled by the GUC parameter check_disconnect_query. If this parameter is set to on, the capability is supported. If this parameter is set to off, the capability is not supported.	Property type: integer Unit: s Value range: 0 to 2147483647. The value 0 indicates that the timeout mechanism does not take effect. Default value: 0
socketTimeoutInConnecting	Specifies the timeout interval for a socket read operation during the connection establishment. If the time of reading data streams from the server exceeds the threshold, it attempts to search for the next node for connection.	Property type: integer Unit: s Value range: 0 to 2147483647. Default value: 5
cancelSignalTimeout	Controls "connect timeout" and "socket timeout" of a cancel command, which may cause blocking. If the cancel command does not respond within the specified time, the connection is interrupted to reduce the occupation of client resources.	Property type: integer Unit: s Value range: 0 to 2147483647. Default value: 10
tcpKeepAlive	Specifies whether to enable TCP keepalive detection.	Property type: Boolean Value range: true: TCP keepalive detection is enabled. false: TCP keepalive detection is disabled. Default value: false
logUnclosedConnections	The client may leak a connection object because it does not call the close() method to close the connection object. Such object will be recycled and finalized using the finalize() method.	Property type: Boolean Value range: true: If the close() method is not called, the finalize() method will be used to close the corresponding connection object. false: If the close() method is not called, the corresponding connection object will not be closed. Default value: false
assumeMinServerVersion (Deprecated)	Specifies the version of the server to be connected. If the value of assumeMinServerVersion is greater than or equal to 9.0, the number of packets to be sent are reduced during connection establishment. The client does not send a request to set the floating point to 3 (that is, retain the original floating point 2).	Property type: string Default value: No default value is provided.
ApplicationName	Specifies the name of the JDBC driver that is being connected. You can query the pg_stat_activity table on the primary database node to view information about the client that is being connected. The JDBC driver name is displayed in the application_name column.	Property type: string Default value: PostgreSQL JDBC Driver
connectionExtraInfo	Specifies whether the driver reports the driver deployment path, process owner, and URL connection configuration information to the database.	Property type: Boolean Value range: true: The JDBC driver reports the driver deployment path, process owner, and URL connection configuration information to the database and displays the information in the connection_info parameter. In this case, you can query the information from PG_STAT_ACTIVITY. false: The driver does not report the driver deployment path, process owner, and URL connection configuration information to the database. Default value: false
autosave	Specifies the action that the driver should perform upon a query failure.	Property type: string Value range: always, never, and conservative. always: The JDBC driver sets a savepoint before each query and rolls back to the savepoint if the query fails. never: There is no savepoint. conservative: A savepoint is set for each query. However, the system rolls back and retries only when there is an invalid statement. Default value: never
protocolVersion	Specifies the connection protocol version.	Property type: integer Value range: 1 and 3. If it is set to 1, only the V1 server is connected. If it is set to 3, only the V5 server is connected. Default value: No default value is provided. If this property is not set, the value 3 is used.
prepareThreshold	Specifies the number of times that the PreparedStatement object is executed before the parsed statement on the server is used. NOTE: You are advised not to use JDBC and prepareStatement to execute password-related statements (for example, CREATE USER user_name WITH PASSWORD '******'). This is because when the number of execution times reaches the value specified by prepareThreshold, the database caches SQL statements but does not cache the passwords for security purposes. When the prepareStatement is executed again, error message "Password must contain at least 8 characters" will be displayed.	Property type: integer Value range: 0 to 2147483647. Default value: 5. The default value indicates that when the same PreparedStatement object is executed for five or more times, the parse message is not sent to the server to parse the statement. Instead, the statement that has been parsed on the server is used.
preparedStatementCacheQueries	Specifies the maximum number of queries generated by caching preparedStatement objects in each connection.	Property type: integer Value range: 0 to 2147483647. The value 0 indicates that the cache function is disabled. Default value: 256. If more than 256 different queries are used in the prepareStatement() call, the least recently used query cache will be discarded. Suggestion: Set the value based on service requirements. This parameter is used together with prepareThreshold.
preparedStatementCacheSizeMiB	Specifies the maximum size of queries generated by caching preparedStatement objects in each connection.	Property type: integer Unit: MB Value range: 0 to 2147483647. The value 0 indicates that the cache function is disabled. Default value: 5. If the size of the cached queries exceeds 5 MB, the least recently used query cache will be discarded.
databaseMetadataCacheFields	Specifies the maximum number of columns that can be cached in each connection.	Property type: integer Value range: 0 to 2147483647. The value 0 indicates that the cache function is disabled. Default value: 65536
databaseMetadataCacheFieldsMiB	Specifies the maximum size of columns that can be cached in each connection.	Property type: integer Unit: MB Value range: 0 to 2147483647. The value 0 indicates that the cache function is disabled. Default value: 5
stringtype	Specifies the type of the parameter transferred to the database when the java.sql.PreparedStatement#setString method is called.	Property type: string Value range: unspecified and varchar. varchar: Parameters are sent to the server as varchar parameters. unspecified: Parameters are sent to the server without their types specified, and the server will attempt to infer the appropriate types. Default value: varchar
batchMode	Specifies whether to use the batch mode. NOTE: If batchMode is set to on, the data type of each column is the same as that specified by the first data record. If the data types are mixed, an error may be reported or the inserted data may be abnormal.	Property type: string Value range: on: The batch mode is enabled to improve the batch update performance. If batchMode is set to on, the returned result is [count, 0, 0...0]. The first element in the array is the total number of records affected in batches. off: The batch mode is disabled. If batchMode is set to off, the returned result is [1, 1, 1...1]. Each element in the array corresponds to the number of affected records in a single modification. Default value: on
fetchsize	Specifies the default fetchsize for statements in the created connection. Specifies the number of rows fetched from ResultSet each time. It has the same function as defaultRowFetchSize. If fetchsize and defaultRowFetchSize are set at the same time, fetchsize prevails.	Property type: integer Value range: 0 to 2147483647. Default value: 0 It indicates that all results are obtained from the database at a time. Suggestion: You are advised to set this parameter based on the amount of data queried by services and the memory of the client. When setting fetchsize, disable automatic commit (set autocommit to false). Otherwise, the setting of fetchsize does not take effect.
defaultRowFetchSize	Specifies the number of rows fetched from ResultSet each time. Limiting the number of rows read each time in a database access request can avoid unnecessary memory consumption, thereby avoiding the out of memory exception.	Property type: integer Value range: 0 to 2147483647. Default value: 0. It indicates that all results are obtained from the database at a time.
reWriteBatchedInserts	Specifies whether to rewrite SQL statements during batch insertion. When this parameter is used, batchMode must be set to off.	Property type: Boolean Value range: true: N insert statements can be combined into one: insert into TABLE_NAME values(values1, ..., valuesN), ..., (values1, ..., valuesN) false: SQL statements are not rewritten during batch insertion. Default value: false
unknownLength	Specifies the length of some GaussDB types (such as TEXT) whose length is unknown and not defined when they are returned by functions such as ResultSetMetaData.getColumnDisplaySize and ResultSetMetaData.getPrecision.	Property type: integer Value range: 0 to 2147483647. Default value: Integer.MAX_VALUE
uppercaseAttributeName	Converts the query result of the API for obtaining metadata to uppercase letters. The application scenario is as follows: All metadata stored in the database is in lowercase, but they must be used as the input and output parameters in uppercase. For details about the involved APIs, see java.sql.DatabaseMetaData and java.sql.ResultSetMetaData. NOTE: After the uppercaseAttributeName parameter is enabled, if the database contains metadata with a mixture of uppercase and lowercase letters, only the metadata in lowercase letters can be queried and output in uppercase letters. Before using the metadata, ensure that the metadata is stored in lowercase letters to prevent data errors.	Property type: string Value range: true: Metadata is converted to uppercase letters. false: GUC parameter configuration is used. Default value: false
binaryTransfer	Specifies whether data is sent and received in binary format.	Property type: Boolean Value range: true: enabled. false: disabled. Default value: false
binaryTransferEnable	Specifies types for which binary transmission is enabled. Types are separated by commas (,), for example, binaryTransferEnable=Integer4_ARRAY,Integer8_ARRAY. You can select either the OID or name. For example, if the name is BLOB and the OID is 88, set binaryTransferEnable to BLOB or 88.	Property type: string Default value: No default value is provided.
binaryTransferDisable	Specifies types for which binary transmission is disabled. Types are separated by commas (,). You can select either the OID or name. If binaryTransferDisable and binaryTransferEnable have the same value, the disabling function is used.	Property type: string Default value: No default value is provided.
blobMode	Sets the setBinaryStream() method to assign values to different types of data. You are advised to set this parameter to on for systems migrated from database A or B and to off for systems migrated from database PG.	Property type: string Value range: on: Values are assigned to BLOB data. off: Values are assigned to bytea data. Default value: on
socketFactory	Specifies the name of the class used to create a socket connection with the server. This class must implement the javax.net.SocketFactory API and define a constructor with no parameter or a single string parameter.	Property type: string
socketFactoryArg	The value is an optional parameter of the constructor function of the socketFactory class and is not recommended.	Property type: string
receiveBufferSize	Sets SO_RCVBUF on a connection stream.	Property type: integer Unit: byte Value range: –1 to 2147483647 Default value: –1. It indicates that the buffer size is not set.
sendBufferSize	Sets SO_SNDBUF on a connection stream.	Property type: integer Unit: byte Value range: –1 to 2147483647 Default value: –1. It indicates that the buffer size is not set.
preferQueryMode	Specifies the query mode.	Property type: string Value range: simple, extended, extendedForPrepared, and extendedCacheEverything. In simple mode, the query is executed without parsing or binding. In extended mode, the query is executed and bound. The extendedForPrepared mode is used for prepared statement extension. In extendedCacheEverything mode, each statement is cached. Default value: extended
targetServerType	Identifies the primary DN and standby DN by querying whether a DN allows the write operation in the URL connection string.	Property type: string Value range: any, master, slave, preferSlave, and clusterMainNode. master: The system attempts to connect to the IP addresses configured in the URL connection string in sequence until the primary DN in the database instance is connected. If the primary DN cannot be found, an exception is thrown. slave: The system attempts to connect to the IP addresses configured in the URL connection string in sequence until a standby DN in the database instance is connected. If no standby DN can be found, an exception is thrown. preferSlave: The system prefers to connect to a standby DN (if available) in the URL connection string; if no standby DN can be found, it connects to the primary DN. any: The system attempts to connect to any DN in the URL connection string. clusterMainNode: The system attempts to connect to the primary DN or main standby DN in the URL string. If the primary DN or main standby DN cannot be found, an exception is thrown. Default value: any Query statement: select local_role, db_state from pg_stat_get_stream_replications(); Suggestion: You are advised to set this parameter to master for services with write operations to ensure that the primary DN can be properly connected after a switchover. However, if the standby DN is not completely promoted to primary during the switchover, the connection cannot be established. As a result, service statements cannot be executed.
priorityServers	Specifies the first n nodes configured in the URL as the primary database instance to be connected preferentially. It is used in streaming DR scenarios. Example: jdbc:opengauss://host1:port1,host2:port2,host3:port3,host4:port4/database?priorityServers=2. That is, host1 and host2 are primary database instance nodes, and host3 and host4 are DR database instance nodes.	Property type: integer Value range: a number greater than 0 and less than the number of DNs configured in the URL. Default value: NULL
forceTargetServerSlave	Specifies whether to enable the function of forcibly connecting to the standby node and forbid the existing connections to the standby node that is promoted to primary after a switchover of the database instance.	Property type: Boolean Value range: false: The function of forcibly connecting to the standby node is disabled. true: The function of forcibly connecting to the standby node is enabled. Default value: false
traceInterfaceClass	Specifies the fully qualified name of the implementation class of the com.huawei.opengauss.jdbc.log.Tracer API that implements the method for obtaining traceId.	Property type: string Default value: NULL
use_boolean	Sets the OID type bound to the setBoolean() method in extended mode.	Property type: Boolean Value range: false: The int2 type is bound. true: The Boolean type is bound. Default value: false
allowReadOnly	Specifies whether to enable the read-only mode for a connection.	Property type: Boolean Value range: true: The read-only mode is enabled. false: The read-only mode is disabled. In this case, calling connection.setReadOnly(true) does not take effect, and data can still be modified. Default value: true
TLSCiphersSupperted	Specifies the supported TLS cipher suite.	Property type: string Default value: TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
stripTrailingZeros	Specifies whether trailing 0s of the numeric type are removed. It is valid only for ResultSet.getObject(int columnIndex).	Property type: Boolean Value range: true: Trailing 0s of the numeric type are removed. false: Trailing 0s of the numeric type are not removed. Default value: false
enableTimeZone	Specifies whether to enable the time zone setting on the client.	Property type: Boolean Value range: true: The time zone setting on the client is enabled. The JVM time zone is obtained to specify the database time zone. false: The time zone setting on the client is disabled. Instead, the database time zone is used. Default value: true
loadBalanceHosts	Specifies whether to enable the load balancing function. In a centralized environment, ensure that no write operation is in services when using this parameter.	Property type: Boolean Value range: true: The shuffle algorithm is used to randomly select a host from the candidates to establish a connection. false: Multiple hosts specified in the URL are connected in sequence. Default value: false