Connection Parameter Reference

PGDBNAME

Specifies the database name. You do not need to set this parameter in the URL because it is automatically parsed from the .properties file.

Property type: string

PGHOST

Specifies the IP address of the host. You do not need to set this parameter in the URL because it is automatically parsed from the .properties file. Both IPv4 and IPv6 addresses are supported. If multiple CNs are configured, use colons (:) to separate their IP addresses and port numbers, and use commas (,) to separate CNs.

Property type: string

PGPORT

Specifies the port number of the host. You do not need to set this parameter in the URL because it is automatically parsed from the .properties file.

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 indicates that the driver description related to PG is displayed.
• gaussdb indicates that the driver description related to GaussDB is displayed.

Default value: postgresql

enable_ce

Specifies the encrypted equality query capability.

Property type: string

Value range:

• enable_ce=1 indicates that JDBC supports the basic capability of encrypted equality query.
• enable_ce=3 indicates that JDBC supports the basic capability of encrypted equality query.

Default value: No default value is provided. If this property is not set, encrypted equality query is disabled.

key_info

This parameter is used together with enable_ce to set parameters for accessing an external key manager in an encrypted database.

Property type: string

Default value: No default value is provided.

refreshClientEncryption

Specifies whether the encrypted database supports cache update on the client.

Property type: string

Value range:

• The value 1 or NULL indicates that the encrypted database supports cache update on the client.
• Other character strings indicate that the encrypted database does not support cache update on the client.

Default value: NULL

loggerLevel

Specifies the logging level.

Property type: string

Value range: OFF, INFO, DEBUG, and TRACE (case-insensitive).

• OFF: The log function is disabled.
• INFO, DEBUG, and TRACE logs record information of different levels.

Default value: OFF

loggerFile

Specifies the log output path (directory and file name). Generally, the log directory and file name must be specified.

It is used to specify the path for exporting monitoring logs only when the connection monitoring function is enabled. To export JDBC logs to a specified path, configure it in the java.util.logging .properties file or system properties. This command can be used only when connection monitoring is enabled.

Property type: string

Default value: No default value is provided. If no directory is specified, log files are generated in the directory where the client program is running.

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, the JDBC driver uses JdkLogger.
• 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 (&). 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

characterEncoding

It must be used together with allowEncodingChanges. When allowEncodingChanges is set to false, characterEncoding can be set only to UTF8. When allowEncodingChanges is set to true, set characterEncoding as permitted.

Property type: string

Value range: UTF8, GBK, LATIN1, GB18030, GB18030_2022, or ZHS16GBK.

Default value: UTF8

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 need 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 (,).

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.

loadBalanceHosts

Specifies whether to enable the load balancing function.

Property type: Boolean

Value range:

• true: The shuffle algorithm is used to randomly select a host from the candidate hosts to establish a connection.
• false: Multiple hosts specified in the URL are connected in sequence.

Default value: false

autoBalance

Specifies a load balancing policy.

Property type: string

Value range:

• If this parameter is set to true, balance, or roundrobin, the JDBC load balancing function is enabled to balance multiple connections of an application to each CN available in the database cluster.

  Example:

  jdbc:gaussdb://host1:port1,host2:port2/database?autoBalance=true

  JDBC periodically updates the list of available CNs in the entire cluster (data IP addresses of hosts in the CN list). The update interval can be configured using the refreshCNIpListTime parameter. The default value is 10 seconds. For example, the obtained list is as follows:

  host1:port1,host2:port2,host3:port3,host4:port4

  When load balancing is enabled, host1 and host2 ensure high availability only when they are connected for the first time. Then, the driver selects available CNs from host1, host2, host3, and host4 in sequence to refresh the available CN list. New connections will use the round robin algorithm to select CNs from host1, host2, host3, and host4 for connection.

• If this parameter is set to priorityn, the JDBC-based load balancing function is enabled. Multiple connections of an application are balanced to the first n available CNs configured in the URL. When the first n CNs are unavailable, connections are randomly allocated to other available CNs in the database cluster. n is a positive integer and is less than the number of CNs configured in the URL. When parseCandidatesByDomain is set to true, the priority configuration of priorityn does not take effect. In this scenario, the priority is specified by priorityDomains. When priorityn is used for load balancing, the host cannot use an IPv6 address. In the scenario where multiple processes establish connections, this policy may cause load imbalance.

  For example:

  jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=priority2

  JDBC periodically obtains the list of all available CNs in the entire cluster.

  host1:port1,host2:port2,host3:port3,host4:port4,host5:port5,host6:port6

  host1 and host2 are in AZ1, and host3 and host4 are in AZ2. The driver preferentially selects host1 and host2 for load balancing. If both host1 and host2 are unavailable, the driver randomly selects a CN from host3, host4, host5, and host6 for connection.

• If this parameter is set to shuffle, JDBC random load balancing is enabled to randomly and evenly distribute multiple connections of the application to available CNs in the database cluster.

  For example:

  jdbc:gaussdb://host1:port1,host2:port2,host3:port3/database?autoBalance=shuffle

  JDBC periodically obtains the list of all available CNs in the entire cluster.

  host1:port1,host2:port2,host3:port3,host4:port4

  host1, host2, and host3 ensure high availability only when they are connected for the first time. Later, they use the shuffle algorithm to randomly select a CN from the refreshed CN list for connection.

• If this parameter is set to specified, the JDBC load balancing function is enabled and connections are established only on nodes specified in the user URL.

  For example:

  jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=specified&priorityServers=2

  JDBC identifies host1 and host2 as the nodes for establishing connections in the primary cluster, and identifies host3 and host4 as the nodes for establishing connections in the standby cluster. When a connection is set up, JDBC evenly distributes the connections to host1 and host2. If all the nodes (host1 and host2) in the primary cluster are faulty, JDBC does not attempt to connect to the remaining nodes. After a switchover, JDBC evenly distributes connections to host3 and host4. If all nodes (host3 and host4) in the standby cluster are faulty, JDBC does not attempt to connect to the remaining nodes.

• If this parameter is set to shufflen, the JDBC random load balancing function preferred on specified nodes is enabled. Multiple connections of an application are balanced to the first n available CNs configured in the URL. When the first n CNs are unavailable, connections are randomly allocated to other available CNs in the database cluster. n is a positive integer and is less than or equal to the number of CNs configured in the URL.

  When parseCandidatesByDomain is set to true, the priority configuration of shufflen does not take effect. In this scenario, the priority is specified by priorityDomains. When shufflen is used for load balancing, the host cannot use an IPv6 address. In the scenario where multiple processes establish connections, this policy can be used to implement load balancing for connections to specified preferred nodes.

  For example:

  jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=shuffle2

  JDBC periodically obtains the list of all available CNs in the entire cluster.

  host1:port1,host2:port2,host3:port3,host4:port4,host5:port5,host6:port6

  The driver preferentially selects host1 and host2 for random load balancing. If both host1 and host2 are unavailable, the driver randomly selects a CN from host3, host4, host5, and host6 for connection.

  • When parseCandidatesByDomain is set to true, the priority configuration of shufflen does not take effect. In this scenario, the priority is specified by priorityDomains. When shufflen is used for load balancing, the host cannot use an IPv6 address. In the scenario where multiple processes establish connections, this policy can be used to implement load balancing for connections to specified preferred nodes.
  • Example:

• If this parameter is set to false, the JDBC load balancing and priority-based load balancing functions are disabled.

Default value: false

refreshCNIpListTime

Obtains the cache validity period of the CNs. During connection establishment, the CN status in the database cluster is checked and is reliable within the period specified by refreshCNIpListTime. After the period expires, the status becomes invalid. The IP address list of available CNs is obtained again during the next connection establishment.

Property type: integer

Unit: s

The value ranges from 1 to 9999.

Default value: 10

Suggestion: Adjust the value based on service requirements and use it together with autoBalance.

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 duration specified by hostRecheckSeconds. After the period expires, the status becomes invalid.

Property type: integer

Unit: s

Value range: The minimum value is 0 and the maximum value is unlimited.

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.

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

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 only attempts to set up an SSL connection. It neither checks whether the server certificate is issued by a trusted CA, nor checks whether the host name of the server is the same as that in the certificate.
• 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.

sslgmcipher

Specifies the encryption algorithm suite used by SM-based TLS.

Property type: string

Value range:

• ECC_SM4_SM3: SM-based one-way and two-way authentication modes are supported.
• ECDHE_SM4_SM3: Only SM-based two-way authentication is supported.

sslcert

Specifies the complete path of the client 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.

sslenccert

Specifies the complete path of the encryption certificate for the SM-based TLS client. 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.

sslenckey

Specifies the complete path of the SM-based TLS encryption key file. You need to convert the key to the DER format before using it.

openssl pkcs8 -topk8 -outform DER -in client_enc.key -out client_enc.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: com.huawei.gaussdb.jdbc.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler

sslfactory

Specifies the class name used by SSLSocketFactory to establish an SSL connection.

Property type: string

Default value: No default value is provided.

sslprivatekeyfactory

Specifies the fully qualified name of the implementation class of the com.huawei.gaussdb.jdbc.ssl.PrivateKeyFactory API that implements the private key decryption method. If it is not provided, try the default JDK private key decryption algorithm. If the decryption fails, use com.huawei.gaussdb.jdbc.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. If this property is not set, the system attempts to use the default JDK private key decryption algorithm for decryption.

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.gaussdb.jdbc.ssl.PGjdbcHostnameVerifier.

Property type: string

Default value: No default value is provided. If this property is not set, com.huawei.gaussdb.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 this value, 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.

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. 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. You can adjust it based on the actual service situation.

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, it 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 interval 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.

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

statementTimeout

Specifies the timeout interval for executing a statement in a connection. If the execution time of a statement exceeds this value, the statement execution is canceled.

Property type: integer

Unit: ms

Value range: 0 to 2147483647. The value 0 indicates that the timeout mechanism does not take effect.

Default value: 0

cancelSignalTimeout

A cancel message may cause a block. This property controls "connect timeout" and "socket timeout" in a cancel command. 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 connection object's close() method. These objects will be collected as garbage and finalized using the finalize() method.

Property type: Boolean

Value range:

• true: If the user does not call the close() method, the finalize() method closes the connection object.
• false: If the user does not call the close() method, the connection object is not 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 pgxc_stat_activity table on CN to view the information about the client that is being connected. The application_name field indicates the JDBC driver name.

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 or PGXC_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.

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 cached queries in each connection (queries are cached after PreparedStatement triggers prepareThreshold).

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 size of the space for caching queries in each connection (queries are cached after PreparedStatement triggers prepareThreshold).

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 passed to the database when the java.sql.PreparedStatement#setString method is called.

Property type: string

Value range: unspecified and varchar.

• varchar: The parameters are sent to the server as varchar parameters.
• unspecified: The parameters are sent to the server without specifying the type, and the server will attempt to infer the appropriate type.

Default value: varchar

batchMode

Specifies whether to use the batch mode.

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

Suggestion: If the service framework (such as hibernate) checks the return value during batch update, you can set this parameter to solve the problem.

fetchsize

Specifies the default fetchsize for statements in the created connection.

Specifies the number of rows read by fetch in ResultSet at a 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 read by fetch in ResultSet at a time. Limiting the number of rows read each time in a database access request can avoid unnecessary memory consumption, thereby avoiding 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: Combine N insert statements into one: insert into TABLE_NAME values(values1, ..., valuesN), ..., (values1, ..., valuesN)
• false: Do not rewrite SQL statements during batch insertion.

Default value: false

unknownLength

Specifies the length of the unknown length type when the data of some GaussDB types (such as TEXT) is returned by functions such as ResultSetMetaData.getColumnDisplaySize and ResultSetMetaData.getPrecision.

Property type: integer

Value range: 0 to 2147483647.

Default value: 2147483647

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 the metadata in uppercase must be used as the input and output parameters.

For details about the involved APIs, see java.sql.DatabaseMetaData and java.sql.ResultSetMetaData.

Property type: string

Value range:

• true and upper indicate that metadata is converted to uppercase letters.
• false: The configuration of GUC parameter uppercase_attribute_name is used.
• lower indicates that metadata is converted to lowercase letters.

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. Every two 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. Every two 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 ORA and MySQL and to off for systems migrated from 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

It is used to set SO_RCVBUF on the 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

It is used to set SO_SNDBUF on the 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, only Q messages are sent. Only text is supported. The parse and bind operations are not supported.
• In extended mode, parse, bind, and execute operations are supported.
• In extendedForPrepared mode, extended query applies to only the Prepared Statement objects, and the Statement objects support only simple query.
• In extendedCacheEverything mode, the query generated by each Statement object is cached.

Default value: extended

ApplicationType

Sets whether to enable distributed write and query. This parameter is valid only when the database is in the GTM-free mode.

Property type: string

Value range: not_perfect_sharding_type and perfect_sharding_type

• not_perfect_sharding_type: enables distributed write and query.
• perfect_sharding_type: disables distributed write and query by default. Distributed write and query can be performed only after /* multinode */ is added to the SQL statement.

Default value: not_perfect_sharding_type

priorityServers

Specifies that the first n nodes configured in the URL are preferentially connected as the primary cluster. It is used in streaming DR scenarios.

Example: jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4,/database?priorityServers=2. That is, host1 and host2 are primary cluster nodes, and host3 and host4 are standby cluster nodes for DR.

Property type: integer

Value range: a number greater than 0 and less than the number of CNs configured in the URL.

Default value: NULL

usingEip

Specifies whether to use an elastic IP address to implement load balancing.

Property type: Boolean

Value range:

• true: Elastic IP addresses are used to implement load balancing.
• false: Data IP addresses are used to implement load balancing.

Default value: true

traceInterfaceClass

Specifies the fully qualified name of the implementation class of the com.huawei.gaussdb.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

enableStandbyRead

Specifies whether to enable the read mode of the standby node.

Property type: Boolean

Value range:

• true: enabled.
• false: disabled.

Default value: false

compatibilityTags

Is used to restore some features of the driver to an earlier version to ensure forward compatibility. You can configure one or more tags. Each tag indicates that the corresponding forward compatibility feature is enabled. Different tags are separated by commas (,). Currently, the following tag is supported:

typeMapInitNull: After this tag is used, the behavior of earlier driver versions is compatible. The initial value of typeMap in java.sql.Connection is NULL. If this tag is not used, the initial value is an empty map.

Property type: string

Default value: No default value is provided.

parseCandidatesByDomain

Specifies whether to obtain candidate nodes based on domain names.

Property type: Boolean

Value range:

• true: enabled. After this function is enabled, you need to configure the host information in the URL in the format of domain name plus port number. The driver obtains the IP address based on the domain name, generates a standby node set, and works with the autoBalance parameter for load balancing.
• false: disabled.

Default value: false

primaryDomains

Specifies that the first n domain names configured in the URL are preferentially connected as the primary cluster. A value greater than 0 indicates that the primary cluster is preferentially connected. This parameter takes effect only when parseCandidatesByDomain is set to true. The domain names in the URL are divided into two groups. The first group is the primary cluster, and the second group is the standby cluster. After a switchover, the two groups switch their positions. The first group is the primary cluster, and the second group is the standby cluster. It applies to streaming DR and Dorado dual-cluster scenarios.

Example: jdbc:gaussdb://domain1:port1,domain2:port2,domain3:port3,domain4:port4/database?parseCandidatesByDomain=true&primaryDomains=2, in which domain1 and domain2 correspond to the primary cluster and the IP addresses corresponding to domain1 and domain2 are preferentially connected. If a switchover occurs, domain3 and domain4 are marked as the primary cluster, and connections are preferentially established to domain3 and domain4.

Property type: integer

Value range: 0 to the number of domain names configured in the URL.

Default value: 0, indicating that the function is disabled.

priorityDomains

Specifies the first n domain names configured in the URL as the domain names to be preferentially connected. A value greater than 0 indicates that the function is enabled. This parameter takes effect only when parseCandidatesByDomain is set to true.

Example: jdbc:gaussdb://domain1:port1,domain2:port2,domain3:port3,domain4:port4/database?parseCandidatesByDomain=true&primaryDomains=2&priorityDomains=1, in which domain1 and domain2 correspond to the primary cluster but the IP address corresponding to domain1 is preferentially connected. domain2 is the standby domain name. The system attempts to connect to domain2 only when domain1 cannot be connected. If a switchover occurs, domain3 and domain4 are marked as the primary cluster. However, the IP address corresponding to domain3 is preferentially connected. If domain3 cannot be connected, the IP address corresponding to domain4 is connected.

Property type: integer

Value range: 0 to the number of domain names configured in the URL. If primaryDomains is configured, the value must be less than the value of primaryDomains.

Default value: 0, indicating that the function is disabled.

refreshDomainResolveTime

It specifies the interval for updating the domain name resolution result and takes effect only when parseCandidatesByDomain is set to true. After it takes effect, the domain name resolution update time involved in the URL is set to a specified value and the domain name resolution result is periodically updated in the asynchronous thread.

Property type: integer

Unit: s

Value range: 1 to 2147483647

Default value: 10

oracleCompatible

This is used to set the ORA-compatible features of driver APIs.

Property type: string

Default value: false

mCompatible

Specifies that the M-compatible features of the driver are controlled by users.

Property type: string

Default value: false

printSqlInLog

Specifies whether to output SQL statements in exception information or logs.

Property type: Boolean

Value range:

• true: enabled.
• false: disabled.

Default value: true

useGsClobBlobClass

Specifies the objects returned when the java.sql.ResultSet#getObject API is used to obtain the CLOB and BLOB columns.

Property type: Boolean

Value range:

• If it is set to true, an object of the PGClob type is returned when the java.sql.ResultSet#getObject API is used to obtain the CLOB columns, and an object of the PGBlob type is returned when the java.sql.ResultSet#getObject API is used to obtain the BLOB columns. If the type name of the CLOB column is obtained through the metadata API java.sql.ResultSetMetaData#getColumnClassName, java.sql.CLOB is returned. If the type name of the BLOB column is obtained, java.sql.BLOB is returned.

• If it is set to false, an object of the PGClob type is returned when the java.sql.ResultSet#getObject API is used to obtain the CLOB columns, and an object of the byte[] type is returned when the java.sql.ResultSet#getObject API is used to obtain the BLOB columns. If the type name of the CLOB column is obtained through the metadata API java.sql.ResultSetMetaData#getColumnClassName, java.sql.CLOB is returned. If the type name of the BLOB column is obtained, java.sql.BLOB is returned.

Default value: false

sessionType

Specifies the type of the current session. An execution plan is generated based on the actual value.

Property type: string

Value range: singleNode, globalReadOnly, and normal.

• normal: indicates a common session. The plan is executed based on the original logic of the database.
• singleNode: indicates a single-node session. The read and write operations of the session can be pushed down. In single-node session mode, a CN sends a one-to-one session to a specified target DN. This parameter must be used together with execTargetNode. Set execTargetNode to the name of the target DN. JDBC preferentially connects to the local CN corresponding to the target DN.
• globalReadOnly: indicates a cross-node read-only session. In this mode, distributed plans are generated normally, but distributed write operations are prohibited.

Default value: normal

execTargetNode

Specifies a DN in single-node session mode. This parameter must be used together with sessionType and takes effect only when sessionType is set to singleNode.

Property type: string

Value range: names of all DNs in the current cluster.

Default value: NULL

executeUpdateQueryable

Specifies whether to enable the executeUpdate() method to execute DQL statements.

Property type: Boolean

Value range:

• true: enabled. After this method is enabled, –1 is returned when the executeUpdate() method executes DQL statements, and a result set can be obtained.
• false: disabled.

Default value: false

dbMonitor

Specifies whether to enable the connection monitoring function for JDBC.

Property type: Boolean

Value range:

• true: enabled.
• false: disabled.

Default value: false

enableStreamingQuery

Specifies whether to enable the streaming read function.

Streaming read function: All data is read at a time by the server and sent to the socket buffer of a client until the buffer is full. If there is free space, the data continues to be sent to the buffer. At the same time, a JVM reads data from the buffer row by row. The advantage is that the result is processed fast and no JVM memory overflow occurs. The disadvantage is that streaming read can only traverse backwards. Before data processing is complete or the statement is closed, no other operations can be performed in the current connection. For details, see Using the Streaming Read Function.

Property type: Boolean

Value range:

• If this parameter is set to true and statement.setFetchSize(Integer.MIN_VALUE) or statement.enableStreamingResults() is used, the streaming read function is enabled.
• If this parameter is set to false, this function is disabled.

Default value: false

yearIsDateType

Specifies whether the returned data object is displayed in the date type when the java.sql.ResultSet#getObject and java.sql.ResultSet#getString APIs are used to obtain columns of the year type.

Property type: Boolean

Value range:

• true: An object of the date type is returned when the java.sql.ResultSet#getObject API is used to obtain columns of the year type. A date character string in the yyyy-mm-dd format is returned when the java.sql.ResultSet#getString API is used to obtain year data. A year value is returned when the java.sql.ResultSet#getInt/getLong/getShort API is used to obtain data.
• false: An object of the integer type is returned when the java.sql.ResultSet#getObject API is used to obtain columns of the year data type. A year character string is returned when the java.sql.ResultSet#getString API is used to obtain year data. A year value is returned when the java.sql.ResultSet#getInt/getLong/getShort API is used to obtain data.

Default value: true

enableObjectTypeConv

Specifies whether to allow the getObject(int, Class<?>) method in the ResultSet API to support compatible type conversion. Currently, conversion between the integer type and the long, double, or bigdecimal types, and conversion between the CLOB type and the string type are supported.

Property type: Boolean

Value range:

• true: Compatible type conversion is allowed.
• false: Compatible type conversion is not allowed.

Default value: false

disasterToleranceCluster

Specifies whether to connect to the primary cluster or the standby cluster for DR when the load balancing function is enabled and only standby cluster nodes are configured in the URL for the JDBC to connect to the database. This parameter cannot be used together with the priorityServers parameter.

Property type: Boolean

Value range:

• true: Load balancing is enabled on nodes in the standby cluster for DR.
• false: Load balancing is performed among nodes in the primary cluster.

Default value: false

pgCompatible

Specifies whether the SQL syntax parsing mode of JDBC is compatible with PG.

Property type: Boolean

Value range:

• true: The syntax parsing is compatible with PG. A statement can contain multiple SQL statements separated by semicolons (;). After this function is enabled, SQL statements containing semicolons (;) cannot be executed.
• false: The default SQL statement parsing mode is used, which is incompatible with PG.

Default value: false

setFloat

Specifies whether the OID passed to the kernel is an OID of float4 when setFloat is called or setObject is set to float.

Property type: Boolean

Value range:

• If it is set to true and setFloat or setObject is called to specify the type as float, the OID passed to the kernel is of the float4 type.
• If it is set to false and setFloat or setObject is called to specify the type as float, the OID passed to the kernel is of the float8 type.

Default value: false

enableGaussArrayAndStruct

After this function is enabled, a projection column or output parameter of the collection or array type can be obtained as a GaussArray or GaussStruct object.

Property type: Boolean

Value range: true and false

Default value: false

actualErrorCodeForBatch

Specifies whether the error code 0 or the actual error code is returned when an error is reported during the execution of the executeBatch API.

Property type: Boolean

Value range:

• true: The actual error code is returned when an error is reported during the execution of the executeBatch API.
• false: The error code 0 is returned when an error is reported during the execution of the executeBatch API.

Default value: false

jdbc.version_num

Version

Range

Usage Rule

Kernel Judgment Rule

Remarks

502xx

505.2

50200–50299

The minimum available value must be used in the version.

Version number ≥ 502xx (latest value)

Related compatibility changes must be incorporated into branches of later versions.

501xx

505.1

50100–50199

The minimum available value must be used in the version.

Version number ≥ 501xx (latest value)

Related compatibility changes must be incorporated into branches of later versions.

500xx

505.0

50000–50099

The minimum available value must be used in the version.

Version number ≥ 500xx (latest value)

Related compatibility changes must be incorporated into branches of later versions.

301xx

503.1

30100–30199

The minimum available value must be used in the version.

Version number ≥ 301xx (latest value)

Related compatibility changes must be incorporated into branches of later versions.