Database URL|V2.4.15|OceanBase Connector/J |docs|OceanBase Documentations

A database URL is a string used to connect to OceanBase Database and implement the specified features.

OceanBase Connector/J allows you to add extra connection attributes in the URL. The complete URL syntax is as follows:

jdbc:oceanbase:hamode://host:port/databasename?[username&password]&[opt1=val1&opt2=val2...]

OceanBase Connector/J allows you to add extra connection attributes in the URL. The following table describes the attributes:

The hamode attribute specifies the high availability mode. The value can be loadbalance.
The [username/password] attribute specifies the username and password for uniquely identifying the database to which the application connects.
The [opt1=val1&opt2=val2...] attribute specifies extra connection attributes, that is, URL parameters.

Here is an example:

jdbc:oceanbase://10.XXX.XXX.XXX:1001/unittests?user=**u**@sys&password=******&
pool=false&useBulkStmts=true&rewriteBatchedStatements=false&useServerPrepStmts=true

This topic describes the optional URL parameters supported by OceanBase Connector/J.

OceanBase Connector/J specific parameters

Parameter	Description
emulateLocators`\| Default value:`False`. Specifies whether the driver should emulate`java.sql.Blob` using locators.
`locatorFetchBufferSize`	Default value: `1048576`. Specifies the buffer size to use when fetching BLOB data via `getBinaryInputStream()` when `emulateLocators` is set to true.
supportLobLocator	Specifies whether to enable LOB locators. Default value: `true`.
useObChecksum	Specifies whether to enable checksums for OceanBase Protocol 2.0. Default value: `true`.
useOceanBaseProtocolV20	Specifies whether to use OceanBase Protocol 2.0. Default value: `true`.
complexDataCacheSize	Specifies the size of the complex data cache. Default value: 50.
cacheComplexData	Specifies whether to cache `ComplexData`. Default value: `true`.
useSqlStringCache	Specifies whether to cache SQL strings on the client. Default value: `false`.
useServerPsStmtChecksum	Specifies whether to use checksums for prepared statements. Default value: `true`.
connectProxy	Specifies whether to connect to the OceanBase Data Proxy (ODP). If this parameter is set to `true`, you can only configure or query the ODP. Default value: `false`.
obProxySocket	Specifies whether to enable the rich client feature. Default value: "".
enableOb20Checksum	Specifies whether to enable checksums for OceanBase Protocol 2.0. Default value: `ture`, which means to calculate the CRC checksum. If this parameter is set to `false`, the checksum is 0.
ocpAccessInterval	Specifies the interval (in minutes) between accesses to OceanBase Cloud Platform (OCP). Default value: 5.
httpConnectTimeout	Specifies the timeout value (in milliseconds) for establishing a communication link to the network resource referenced by this URLConnection. Default value: 0.
httpReadTimeout	Specifies the timeout value (in milliseconds) for reading from the input stream when a URLConnection is established to the resource. Default value: 0.
compatibleOjdbcVersion	Specifies the version of the target ojdbc driver. Valid values: 6 and 8. If this parameter is set to other values, the default value is used. Default value: 6.
useOraclePrepareExecute	Specifies whether to enable the combined prepare and execute protocol for Oracle mode. In Oracle mode, the `preparedStatement` will not communicate with the server before using `COM_STMT_PREPARE_EXECUTE`. Default value: `false`. In the current version, when `useOraclePrepareExecute` is set to `true`, `useServerPrepStmts` is set to `true`. In versions earlier than V2.4.5, you must set both parameters to `true` to enable the combined prepare and execute protocol.
compatibleMysqlVersion	Specifies the version of the target mysql-jdbc driver. Valid values: 5 and 8. If this parameter is set to other values, the default value is used. Default value: 5.
mapDateToTimeStamp	If set to `true`, the Date data type in Oracle mode will include time, minute, and second information. If set to `false`, only the date part will be displayed. Default value `true`.
obDateTypeOptimization	Specifies whether to use the value from the byte array for the `getDate` method instead of converting it to a string and then truncating it. Default value `false`.
useNewResultSetMetaData	Specifies whether to use native MySQL JDBC metadata. Default value `false`.
usePieceData	Specifies whether to use the piece data transmission mode. Default value: false. In Oracle mode, the `COM_STMT_SEND_PIECE_DATA` protocol is used to set the `InputStream` and `Reader` parameters. When `usePieceData` is set to true, `useOraclePrepareExecute` is set to true, and `useCursorFetch` is changed to true.
useArrayBinding	Specifies whether to use array binding in Oracle mode to reduce network round trips and improve performance. Default value: false. When this parameter is set to true, you can enable array binding, which allows you to pass multiple parameters as an array.
oracleXaPrepareThrowException	If the return value of `dbms_xa.xa_prepare` is neither 0 nor 3, an exception is thrown. Default value: `false`.
convertNoneNanoSecsToDate	In Oracle mode, specifies whether to convert the value of the `setTimestamp` interface parameter to the Date type when the value does not contain nanoseconds (nanos). Default value: `true`.
oracleUseNumberForSetDouble	In Oracle mode, specifies whether to serialize the type of `setDouble` to the number type. Default value: `false`.
lowercaseRoutinesInMetadata	In Oracle mode, specifies whether to allow the name of procedures and functions to be in lowercase when retrieving metadata. Default value: `true`.

Basic parameters

Parameter	Description
user	The name of the database user.
password	The password of the database user.
rewriteBatchedStatements	For insert queries, rewrite `batchedStatement` to execute in a single `executeQuery`. For example, `insert into ab (i) values (?)with first batch values = 1, second = 2` is rewritten to `insert into ab (i) values (1), (2)`. If a query cannot be rewritten with "multi-value" syntax, it will be rewritten using multiple queries. For example, `INSERT INTO TABLE(col1) VALUES (?) ON DUPLICATE KEY UPDATE col2=?` with additional values [1,2] and [2,3] will be rewritten to `INSERT INTO TABLE(col1) VALUES (1) ON DUPLICATE KEY UPDATE col2=2;INSERT INTO TABLE(col1) VALUES (3) ON DUPLICATE KEY UPDATE col2=4`. When `rewriteBatchedStatements` is enabled, the `useServerPrepStmts` option is set to `false`. Default value: `false`.
useServerPrepStmts	Prepare `PrepareStatement` on the server before execution. Applications that reuse the same query can activate this option, but typically direct commands (text protocol) are used. If `rewriteBatchedStatements` is set to `true`, this option will be set to `false`. Default value: `false`.
useBatchMultiSend	The driver can send queries in batches. If set to `false`, queries will be sent one at a time, waiting for the result before sending the next. If set to `true`, queries will be sent in batches based on the value of the `useBatchMultiSendNumber` option (default `100`), or based on the `max_allowed_packet` server variable if the number of queries exceeds what can be sent in a single packet. This helps avoid significant network latency when the client and server are not on the same host. Default value: `true`.
allowLocalInfile	Allows loading data from files. Default value: `false`.
useCompatibleMetadata	When set to true, forces the return of MySQL/Oracle as the database name, rather than OceanBase. This option replaces the useMysqlMetadata option.
characterEncoding	The character encoding supported by the MySQL URL option. Default value: `utf8`. Supports the Hong Kong character set `HKSCS/HKSCS31`.

Network connection parameters

Parameter	Description
socksProxyHost	The name or IP address of the `SOCKS` host to connect to. Default value: `null`
socksProxyPort	The port of the `SOCKS` server. Default value: 1080.
socketFactory	If you want to use a custom Socket Factory, set it to the full name of the `javax.net.SocketFactory` class.
connectTimeout	The connection timeout in milliseconds. If no timeout is specified, the value is zero. Default value: 30000.
maxReconnects	Default value is `3`. The maximum number of reconnection attempts when `autoReconnect` is true.
socketTimeout	Defines the network Socket timeout (`SO_TIMEOUT`) in milliseconds. A value of 0 disables this timeout. You can also limit the query time by setting the system variable `max_statement_time`. Default value: 0 (standard configuration) or 10000 ms.
localSocketAddress	The hostname or IP address to bind the connection Socket to the local (UNIX domain) Socket.
tcpKeepAlive	If using a TCP/IP connection, whether the driver should set `SO_KEEPALIVE`. Default value: `true`.
tcpNoDelay	If using a TCP/IP connection, whether the driver should set `SO_TCP_NODELAY` (disable Nagle's algorithm). Default value: `true`.
tcpRcvBuf	Sets the size of the TCP buffer (`SO_RCVBUF`). Default value is 0, which means the platform's default value is used.
tcpSndBuf	Sets the size of the TCP buffer (`SO_SNDBUF`). Default value is 0, which means the platform's default value is used.

TLS parameters

Parameter	Description
useSSL	Specifies whether to use SSL/TLS when a connection is established. Default value: `false`.
trustServerCertificate	Specifies whether to trust the server certificate when SSL/TLS is used. Default value: `false`.
serverSslCert	Specifies the server certificate or the CA certificate of the server in DER format. This server certificate will be added to the `trustStor`, so that self-signed certificates can be trusted. You can use one of the following methods: serverSslCert=/path/to/cert.pem (full path to certificate) serverSslCert=classpath:relative/cert.pem (relative to current classpath) as verbatim DER-encoded certificate string "------BEGIN CERTIFICATE-----"
keyStore	Specifies the file path of the keyStore file that contains the client private key store and associated certificate (similar to the Java system property `javax.net.ssl.keyStore`, but only entries that use private keys are allowed). This parameter is also known as `clientCertificateKeyStoreUrl`.
keyStorePassword	Specifies the password of the client certificate keyStore (similar to the Java system property `javax.net.ssl.keyStorePassword`). This parameter is also known as `clientCertificateKeyStorePassword`
keyPassword	Specifies the password of the private key in the client certificate keyStore. This parameter is required only when the private key password is different from the keyStore password.
trustStore	Specifies the file path of the trustStore file (similar to the Java system property `javax.net.ssl.trustStore`, also known as `trustCertificateKeyStoreUrl`). This parameter specifies the file to be used for trusted root certificates. After this parameter is set, the `serverSslCert` parameter is overridden.
trustStorePassword	Specifies the password of the trusted root certificate file (similar to the Java system property `javax.net.ssl.trustStorePassword`, also known as `trustCertificateKeyStorePassword`).
enabledSslProtocolSuites	Specifies a list of specific TLS versions (separated by commas) to be enforced for the TLS/SSL protocol. Example: "TLSv1, TLSv1.1, TLSv1.2" (you can also use the alias `enabledSSLProtocolSuites`). Default value: the default value of Java.
enabledSslCipherSuites	Specifies a list of TLS/SSL ciphers (separated by commas) to be enforced. Example: " `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_DSS_WITH_AES_256_GCM_SHA384`". Default value: the ciphers supported by the JRE.
disableSslHostnameVerification	Specifies whether to disable hostname verification when SSL is used. When this option is enabled, the driver will not verify the server identity in the server certificate (such as the subject alternative name or certificate CN) to prevent man-in-the-middle attacks. This option allows you to disable the hostname verification. When `trustServerCertificate` is set to `default`, hostname verification is disabled.
keyStoreType	Specifies the key store type (JKS/PKCS12). The default value is `null`, which indicates that the Java default type is used.
trustStoreType	Specifies the trust store type (JKS/PKCS12). The default value is `null`, which indicates that the Java default type is used.

Performance tuning parameters

Parameter	Description
useLocalSessionState	Specifies whether to use the locally cached session state (such as transaction mode, auto-commit status, and current database) to avoid frequently sending queries to the server to obtain these states. When the parameter value is False, queries are always sent. When the parameter value is True, requests are not sent to the OBServer if the session state does not change. Default value: `true`.
useLocalTransactionState	Specifies whether to use the transaction state provided by the MySQL protocol to determine whether `commit()` or `rollback()` has been sent to the database. Default value: `true`. Notice This parameter cannot be modified in the current version.
useOceanBaseProtocolV20	Specifies whether to enable the OB2.0 protocol. Default value: enabled.
enableFullLinkTrace	Specifies whether to enable the full-link tracing feature. Default value: disabled. When `enableFullLinkTrace` is set to `true`, `useOceanBaseProtocolV20` is also forcibly modified to `true`.

Connection pool parameters

Parameter	Description
pool	Specifies whether to use a connection pool. This option is useful only when you use connection objects instead of the DataSource object. Default value: `false`.
poolName	The name of the connection pool for identifying threads. Default value: automatically generated as `oceanbase-pool- <pool-index>`.
maxPoolSize	The maximum number of physical connections that a connection pool can contain. Default value: 8.
minPoolSize	If a connection is deleted because it has been idle for more than `maxIdleTime`, the connection is closed and removed from the pool. `minPoolSize` specifies the minimum number of physical connections that must always be available in the connection pool. This value must be less than or equal to `maxPoolSize`. Default value: `maxPoolSize`.
poolValidMinDelay	When a connection is requested, the connection pool validates the connection status. If the connection has been recently borrowed, `poolValidMinDelay` allows you to disable this validation to avoid unnecessary validations when the connection is frequently reused. A value of 0 indicates that the connection status is validated for each request. Default value: 1000 (ms).
maxIdleTime	The maximum time that a connection can be idle in the pool, in seconds. This value must always be less than `@wait_timeout-45s`. Default value: 600 seconds (10 minutes). Minimum value: 60 seconds.
staticGlobal	Specifies whether to keep the values of the global variables `max_allowed_packet`, `wait_timeout`, `autocommit`, `auto_increment_increment`, `time_zone`, `system_time_zoneandtx_isolation` unchanged to allow the connection pool to create new connections more quickly. Default value: `false`.
useResetConnection	Specifies whether to reset the connection status when a connection is returned to the connection pool. If this option is set to `true`, the server will delete prepared statements, reset session variables, and destroy user variables when the server allows it, thereby saving memory when a large number of variables are used in an application. This option cannot be used together with the `useServerPrepStmts` option. Default value: `false`.
registerJmxPool	Specifies whether to register the JMX monitoring pool. Default value: `true`.

Log parameters

Parameter	Description
log	Specifies whether to enable log information. Default value: `false`.
maxQuerySizeToLog	Specifies the number of characters to be displayed in the log. Default value: 1024.
slowQueryThresholdNanos	Specifies the execution time threshold for recording queries. Default value: 1024.
profileSql	Specifies whether to log the execution time of queries. Default value: `false`.

Other parameters

Parameter	Description
passwordCharacterEncoding	Specifies the character set for password encoding. The character set value must be a Java character set. For example: UTF-8. Default value: `null` (the default character set of the platform).
useFractionalSeconds	Specifies whether to process timestamps with subsecond precision. Default value: `true`.
allowMultiQueries	Specifies the SQL String format for executing multiple queries in a single operation. For example `insert into ab (i) values (1); insert into ab (i) values (2)`. Default value: `false`
dumpQueriesOnException	If set to `true`, exceptions during query execution will include the query string. Default value: `false`.
useCompression	Specifies whether to compress network communication with the database using `gzip`. This can improve performance when database network overhead is significant. Default value: `false`.
tcpAbortiveClose	This option is useful in environments where connections are created and closed rapidly. Typically, in such environments, it is not possible to create a Socket within a short period because all local "ephemeral" ports are exhausted by TCP connections and are in the `TCP_WAIT` state. Using `tcpAbortiveClose` resolves this issue by resetting the TCP connection (either actively or forcibly) instead of performing an orderly shutdown. Use `socket.setSoLinger(true,0)` for a forced shutdown.
tinyInt1isBit	A data type mapping flag that processes MySQL Tiny as BIT (Boolean). Default value: `true`.
yearIsDateType	Processes Year as a date type rather than a number. Default value: `true`.
sessionVariables	A list of `<var> = <value>` pairs for setting session variables, separated by commas.
localSocket	If the server allows it, connects to the database using a Unix domain socket. The value is the path to the Unix domain socket (i.e., the socket database parameter: `select @@ socket`).
sharedMemory	If the server allows it, connects to the database using shared memory. The value is the base name of the shared memory.
interactiveClient	Defines the session timeout using the `thewait_timeoutserver` variable. Setting `interactiveClient` to `true` tells the server to use the `interactive_timeoutserver` variable. Default value: `false`
useOldAliasMetadataBehavior	Metadata returned by `ResultSetMetaData.getTableName()` provides the physical table name. If `useOldAliasMetadataBehavior` is set, you can retrieve table aliases. Default value: `false`
createDatabaseIfNotExist	Creates the specified database in the URL if it does not exist. Default value: `false`
serverTimezone	Defines the server timezone. Only used when the GRE server implementation has different server timezones (preferably the same server timezone).
cachePrepStmts	If `useServerPrepStmts = true`, prepared statements are cached in an LRU cache to avoid re-preparing commands. When the command is used again, the prepared identifier and parameters (if any) are sent to the server, avoiding the need for the server to re-parse the query. Default value: `false`
prepStmtCacheSize	If `useServerPrepStmts = true`, defines the size of the prepared statement cache used by the `cachePrepStmts` option. Default value: 250.
prepStmtCacheSqlLimit	If `useServerPrepStmts = true`, queries exceeding this threshold will not be cached. Default value: 2048.
jdbcCompliantTruncation	Truncation errors ("Data in column '%s' of row %d was truncated" and "Value in column '%s' of row %d is out of range") are treated as errors rather than warnings. Default value: `true`
cacheCallableStmts	Enables/disables caching of Callable Statements. Default value: `true`
callableStmtCacheSize	If `cacheCallableStmts` is enabled, sets the number of Callable Statements cached by the driver per VM. Default value: 150.
useBatchMultiSendNumber	When the `useBatchMultiSend` option is active, sets the maximum number of queries that can be sent consecutively before reading results. Default value: 100.
connectionAttributes	When `performance_schema` is active, allows sending some client information to the server in key-value pair format (e.g., `connectionAttributes = key1: value1, key2, value2`). This information can be retrieved from the `performance_schema.session_connect_attrs` and `performance_schema.session_account_connect_attrs` tables on the server.
usePipelineAuth	During connection, executes different queries. If this option is active, queries are sent via a pipeline (send all queries, then read all results), allowing faster connection creation. Default value: `true`
enablePacketDebug	The driver will save the most recent 16 MySQL data exchange packets (limited to the first 1000 bytes). When an IOException occurs, the hexadecimal values of these packets will be added to the `stacktrace`. This option does not affect performance but will consume more than 16 KB of memory. Default value: `false`.
useBulkStmts	Use the `COM_STMT_BULK_EXECUTE` protocol for bulk inserts as much as possible. (Does not include `Statement.RETURN_GENERATED_KEYS` and streaming batch processing). Default value: `false`.
autocommit	Sets the default value for autocommit when the connection is initialized. Default value: `true`.
galeraAllowedState	Typically, `Connection.isValid` sends an empty packet to the server, and the server responds with a small response to ensure connectivity. After setting this option, the connector will ensure that the Galera server state `wsrep_local_state` corresponds to the allowed values (separated by commas). For example, "4,5", recommended value is "4". Default value: empty.
includeInnodbStatusInDeadlockExceptions	When a deadlock exception occurs, the result of `SHOW ENGINE INNODB STATUS` will be added to the exception trace. Default value: `false`.
includeThreadDumpInDeadlockExceptions	When a deadlock exception occurs, the thread dump will be added to the exception trace. Default value: `false`.
useReadAheadInput	Use a buffered `inputSteam` to read available socket data. Default value: `true`.
servicePrincipalName	When using GSSAPI authentication, this value will be used as the service principal name (SPN) instead of the name defined for the user account on the database server.
useCompatibleMetadata	When set to true, forces the driver to return "MySQL/Oracle" as the database name instead of "OceanBase". This option replaces the useMysqlMetadata option.
defaultFetchSize	The driver will call `setFetchSize(n)` on all newly created Statements. Default value: 0.
blankTableNameMeta	The `getTableName` method of the result set metadata always returns an empty string. This option is mainly for compatibility with Oracle databases. Default value: `false`.
serverRsaPublicKeyFile	Specifies the path to the RSA server public key file used for `sha256_password` and `caching_sha2_password` authentication passwords.
allowPublicKeyRetrieval	When `serverRsaPublicKeyFile` is not set, allows the client to retrieve the RSA server public key (for `sha256_password` and `caching_sha2_password` authentication passwords). Default value: `false`.
tlsSocketType	Specifies the type of the TLS `org.oceanbase.jdbc.tls.TlsSocketPlugin` plugin to use. The plugin must be present in the `classpath`.
credentialType	Specifies the type of the credential plugin to use. The plugin must be present in the `classpath`.
trackSchema	When the server has the `CLIENT_SESSION_TRACK` feature, allows the `session_track_schema` setting to be disabled. Default value: `true`.
clobberStreamingResults	If another query is executed before all data is read from the server, this will cause the streaming result set to be automatically closed, and any data being streamed from the server that has not yet been transmitted will be discarded. Default value: `false`.
maxRows	The maximum number of rows to return. The default value is `0`, which means all rows are returned.
zeroDateTimeBehavior	Specifies how to handle invalid dates in MySQL mode. Valid values are `convertToNull`, `exception`, or `round`. That is, `ZERO_DATETIME_CONVERT_TO_NULL = "convertToNull";ZERO_DATETIME_EXCEPTION = "exception";ZERO_DATETIME_ROUND = "round";` Default value: `ZERO_DATETIME_EXCEPTION`.
allowNanAndInf	Whether to allow the use of NaN or +/- INF values in PreparedStatement.setDouble(). Default value: `false`.
defaultConnectionAttributesBanList	When `sendConnectionAttributes=true`, this parameter controls the list of connection attributes not to send to the server. The list is separated by commas and is case-sensitive. Default value: `null`.
useInformationSchema	Whether to use the INFORMATION_SCHEMA to derive information for "DatabaseMetaData". Default value: `false`.