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

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

OceanBase Connector/J allows you to add additional connection properties to the URL. The complete supported URL syntax is as follows:

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

OceanBase Connector/J allows you to add additional connection properties to the URL. The details are as follows:

The hamode attribute specifies high-availability mode. The only supported parameter is loadbalance.
The [username/password] attribute is optional and represents the username and password used to uniquely identify the database to which the application connects.
The [opt1=val1&opt2=val2...] attribute contains additional connection properties, which are 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

Meaning of each field in a JDBC URL

A JDBC URL consists of the following parts, where each field has its own meaning:

field	Meaning	Description
`jdbc:oceanbase:`	Protocol prefix	Fixed format, indicating that the OceanBase Connector/J driver is used to connect to OceanBase Database.
`hamode`	High Availability Mode	Optional, for example,`loadbalance`Indicates that load balancing is enabled. If omitted, direct connection mode is used.
`host`	Host Address	The IP address or hostname of the OBServer or ODP.
`port`	Port Number	The listening port of the OBServer or ODP, typically 2881 (for direct connection to OBServer) or 2883 (via ODP).
`databasename`	Database Name	The name of the database (in MySQL-compatible mode) or schema (in Oracle-compatible mode) to connect to.
`username`	Username	Optional. You can specify the following parameters in the URL:`user=`Specify it, or you can also use`getConnection(url, user, password)`Passed in . MySQL-compatible mode supports`user@tenant`format.
`password`	password	Optional. You can specify the parameter in the URL by using the`password=`Specify it, or you can also use`getConnection`Passed in.
`opt1=val1&...`	URL parameters	Additional connection properties for configuring timeouts, SSL, connection pools, and so on. For details, see the parameter tables below.

This section describes the optional URL parameters for OceanBase Connector/J.

OceanBase Connector/J-specific parameters

Parameter	Description
emulateLocators`\| The default value is`False`. Whether the driver should use a locator to simulate`java.sql.Blob`
`locatorFetchBufferSize`	The default value is`1048576`.`emulateLocators`Set to true. Pass through`getBinaryInputStream()`Buffer size to use when retrieving BLOB data
supportLobLocator	LOB locator switch. Default value:`true`.
useObChecksum	The checksum switch is a configuration parameter for the OceanBase Protocol 2.0. Default value:`true`.
useOceanBaseProtocolV20	Whether to use OceanBase Protocol 2.0. Default value:`true`.
complexDataCacheSize	The size of the ComplexData cache. Default value: 50.
cacheComplexData	Cached?`ComplexData`. Default value:`true`.
useSqlStringCache	Whether to cache SQL strings on the client. Default value:`false`.
useServerPsStmtChecksum	Whether to use the checksum of the PS. Default value:`true`.
connectProxy	Configure the connection to ODP. At this point, you cannot execute queries on business SQL; you can only configure ODP or configure queries. Default value:`false`.
obProxySocket	Whether to enable the rich client feature. Default value: "".
enableOb20Checksum	Based on the OB2.0 protocol, controls the header checksum and trailer checksum of OceanBase Connector/J request packets. Default value is`ture`, indicating that the CRC checksum is calculated; otherwise, the checksum is 0.
ocpAccessInterval	The interval for accessing OCP, in minutes. Default value: 5.
httpConnectTimeout	Sets the specified timeout value (in milliseconds) to be used when opening a communication link to the network resource referenced by this URLConnection. Default value: 0.
httpReadTimeout	When a URLConnection is established to a resource, a non-zero value specifies the timeout period (in milliseconds) for reading from the input stream. Default value: 0.
compatibleOjdbcVersion	Specifies the version of the target ODBC driver to be compatible with. Valid values: 6 and 8. If set to any other integer, no error will be reported, but the value will be treated as the default. Default value: 6.
useOraclePrepareExecute	Enable PS/SSP protocol, Oracle-compatible mode`preparedStatement`When using`COM_STMT_PREPARE_EXECUTE`Does not communicate with the server before execution. Default value:`false`. Current version`useOraclePrepareExecute`is`true`When,`useServerPrepStmts`Set to`true`. Versions earlier than V2.4.5 must be used together to enable the PS combined protocol.
compatibleMysqlVersion	Sets the version compatible with the target MySQL JDBC driver. Valid values: 5 and 8. If set to other integer values, no error is reported, but the driver will be treated as if the default value 5 were used. Default value: 5.
mapDateToTimeStamp	Set to`true`When set to this value, the Date data type in Oracle-compatible mode will include hours, minutes, and seconds. If set to`false`is specified, only the date part is displayed. Default value:`true`.
obDateTypeOptimization	For`getDate`The method retrieves values from the byte array instead of converting it to a string for truncation. Default value`false`.
useNewResultSetMetaData	The metadata information is compatible with native MySQL JDBC. Default value:`false`.
usePieceData	Sets whether to use the sharded data transfer mode. Default value: false. In Oracle-compatible mode, use`COM_STMT_SEND_PIECE_DATA`Protocol settings`InputStream`and`Reader`parameter. When`usePieceData`When this parameter is set to true,`useOraclePrepareExecute`When set to true,`useCursorFetch`is changed to true.
useArrayBinding	Array binding is supported in Oracle-compatible mode to reduce network round trips and improve performance. Default value: false. When this parameter is set to true, array binding can be enabled, allowing multiple parameters to be passed as an array.
oracleXaPrepareThrowException	When`dbms_xa.xa_prepare`An exception is thrown if the return value of is neither 0 nor 3. Default value:`false`.
convertNoneNanoSecsToDate	In Oracle-compatible mode,`setTimestamp`Whether to convert the API parameter value to a Date type if nanoseconds are not provided. Default value:`true`.
oracleUseNumberForSetDouble	Oracle Tenant, Whether to Serialize`setDouble`The type is number. Default value:`false`.
lowercaseRoutinesInMetadata	Whether the name of a procedure/function can be in lowercase when metadata is retrieved for an Oracle-compatible tenant. Default value:`true`.
obConvertCallsToBlocks	For Oracle tenants, specifies whether to convert the {call xxx} statement into a begin...end anonymous block. Default value:`false`.
obIncludeOutOrNullParamTypeInfo	For Oracle tenants, specifies whether to pass the data types of out and null parameters in procedures to OBServer nodes. This parameter is typically used to handle scenarios with procedure synonyms. Default value:`false`.
clientInfoProvider	Implementation`com.oceanbase.jdbc.ClientInfoProvider`The fully qualified class name of the interface, used to customize the getClientInfo/setClientInfo behavior of a Connection. If not configured, the driver's default implementation is used. This applies to both MySQL and Oracle-compatible tenants. For more information, see clientInfoProvider Usage Instructions.
useProxyUser	Set to true in Oracle-compatible mode to use the proxy user for login. Default value:`false`.
obCachePsMetaData	Indicates whether to cache meta information under the PS protocol. This parameter takes effect only when it is enabled by setting the server parameter enable_ps_meta_response_optimize. Default value:`false`.
obGetDateStringWithMillis	Specifies whether to output milliseconds when retrieving the date type using getString in an Oracle-compatible tenant. (In scenarios compatible with OJDBC 6, this parameter does not affect the result.) Default value:`false`.

Basic parameters

Parameters	Description
user	The database username.
password	The password of the database user.
rewriteBatchedStatements	For INSERT queries, rewrite as`batchedStatement`To process data in a single`executeQuery`. For example:`insert into ab (i) values (?)with first batch values = 1, second = 2`overridden to`insert into ab (i) values (1), (2)`. If the query cannot be rewritten using "multi-valued", multi-query rewriting will be used.`INSERT INTO TABLE(col1) VALUES (?) ON DUPLICATE KEY UPDATE col2=?`With the addition of values [1,2] and [2,3], it will be rewritten as`INSERT INTO TABLE(col1) VALUES (1) ON DUPLICATE KEY UPDATE col2=2;INSERT INTO TABLE(col1) VALUES (3) ON DUPLICATE KEY UPDATE col2=4`. `rewriteBatchedStatements`When it is active,`useServerPrepStmts`The option is set to`false`. Default value:`false`.
useServerPrepStmts	Before execution, prepare on the server side:`PrepareStatement`Applications that reuse the same query have the value for this option activated, but typically use direct commands (text protocol). If`rewriteBatchedStatements`Set to`true`, then 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 by one, waiting for the return result before sending the next. If set to`true`, the query will be executed based on the condition with the highest priority.`useBatchMultiSendNumber`Option value (default is`100`) queries in batches. If the number of queries exceeds the limit allowed by the packet, they will be processed according to the`max_allowed_packet`The server variable sends the query and then reads the result, thereby avoiding significant network latency when the client and server are not on the same host. Default value:`true`.
allowLocalInfile	Whether to allow loading data from files. Default value:`false`.
useCompatibleMetadata	`databaseMetaData.getDatabaseProductName()`Returns Oracle or MySQL based on the server type.
characterEncoding	Character encoding supported for MySQL URL options. Default value:`utf8`. Supports the Hong Kong character set.`HKSCS/HKSCS31`.

Network connection parameters

Parameter	Description
socksProxyHost	To connect to the`SOCKS`Host name or IP address. Default value:`null`
socksProxyPort	`SOCKS`The port of the server. Default value: 1080.
socketFactory	To use a custom socket factory, set it to`javax.net.SocketFactory`The fully qualified name of the class.
connectTimeout	The connection timeout value, in milliseconds. If there is no timeout, the value is zero. Default: 30000.
maxReconnects	Default value:`3`.`autoReconnect`When set to true, specifies the maximum number of attempts to reconnect.
socketTimeout	Defines the network socket timeout (`SO_TIMEOUT`), in milliseconds. When the value is 0, this timeout is disabled. You can also set the system variable`max_statement_time`to limit the query time. Default value: 0 (standard configuration) or 10000 ms.
localSocketAddress	Bind the connection socket to the hostname or IP address of the local (UNIX domain) socket.
tcpKeepAlive	If using a TCP/IP connection, should the driver be set to`SO_KEEPALIVE`. Default value:`true`.
tcpNoDelay	If using a TCP/IP connection, should the driver be set to`SO_TCP_NODELAY`(Disables the Nagle algorithm). Default value:`true`.
tcpRcvBuf	Set the TCP buffer size (`SO_RCVBUF`) in bytes. The default value is 0, which means the platform's default value for this attribute is used.
tcpSndBuf	Set the TCP buffer size (`SO_SNDBUF`) in bytes. The default value is 0, which means the platform's default value for this attribute is used.

TLS parameters

Parameters	Description
useSSL	Specifies whether to use SSL/TLS for forced connections. Default value:`false`.
trustServerCertificate	When using SSL/TLS, the server certificate is not verified. Default value:`false`.
serverSslCert	Allows the server certificate or server CA certificate to be provided in DER format. The server will be added to the`trustStor`This allows the self-signed certificate to be trusted. You can use one of the following three 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	File path of the keyStore file containing the client private key and its associated certificate (similar to a Java system property.`javax.net.ssl.keyStore`, but ensure that only the entry for the private key is used). Old alias`clientCertificateKeyStoreUrl`.
keyStorePassword	The password for the client certificate keyStore (similar to a Java system property.`javax.net.ssl.keyStorePassword`). Old alias`clientCertificateKeyStorePassword`
keyPassword	The password for the private key in the client certificate keyStore. (Required only if the private key password is different from the keyStore password.)
trustStore	The file path of the trustStore file (similar to a Java system property.`javax.net.ssl.trustStore`, old alias`trustCertificateKeyStoreUrl`) Use the specified file as the trusted root certificate. After this setting is configured, it will overwrite the`serverSslCert`.
trustStorePassword	The password for the trusted root certificate file (similar to the Java system property`javax.net.ssl.trustStorePassword`, old alias`trustCertificateKeyStorePassword`).
enabledSslProtocolSuites	Forces the TLS/SSL protocol to a specific set of TLS versions (a comma-separated list). Example: "TLSv1,TLSv1.1,TLSv1.2" (aliases can also be used)`enabledSSLProtocolSuites`) Default value: The default Java value.
enabledSslCipherSuites	Mandatory TLS/SSL ciphers (comma-separated list). Example: "`TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_DSS_WITH_AES_256_GCM_SHA384`". Default value: Use the JRE password.
disableSslHostnameVerification	When using SSL, the driver verifies the hostname (or alternate name or certificate CN) against the server identity displayed in the server certificate to prevent man-in-the-middle attacks. This option allows you to disable this verification. When`trustServerCertificate`The option is set to`default`will disable hostname verification.
keyStoreType	Specifies the key store type (JKS or PKCS12). Default value:`null`, which indicates using the default Java type.
trustStoreType	Specifies the trusted library type (JKS or PKCS12). Default value:`null`, indicating the use of the default Java type.

Performance scaling parameters

Parameter	Description
useLocalSessionState	Controls whether the driver uses local cached session states (such as transaction mode, auto-commit status, current database, etc.) to avoid frequently sending queries to the server for these states. When the parameter value is False, all states are always sent. When the value is True and the session state has not changed, no request is sent to the OBServer; a request is sent only if there is a change. Default value:`true`.
useLocalTransactionState	Whether the driver uses the transaction status provided by the MySQL protocol to determine`commit()`or`rollback()`Has indeed been sent to the database. Default value:`true`. Note This parameter cannot be modified in the current version.
useOceanBaseProtocolV20	Whether to enable the OB2.0 protocol. Enabled by default.
enableFullLinkTrace	Whether to enable end-to-end tracing. The default value is disabled. When`enableFullLinkTrace`Set to`true`When you use the following methods,`useOceanBaseProtocolV20`will also be forcibly modified to`true`.

Connection pool parameters

Parameters	Description
pool	Use a connection pool. This option is useful only when you use only connection objects and do not use DataSource objects. Default value:`false`.
poolName	The name of the connection pool that allows thread identification. Default value: automatically generated as`oceanbase-pool- <pool-index>`.
maxPoolSize	The maximum number of physical connections allowed in the connection pool. Default value: 8.
minPoolSize	If the usage time does not exceed`maxIdleTime`If a connection is dropped, it will be closed and removed from the pool.`minPoolSize`Specifies the number of physical connections that the connection pool should always keep available. This parameter must be less than or equal to`maxPoolSize`. Default value:`maxPoolSize`.
poolValidMinDelay	When a connection is requested, the connection pool verifies its status. If a connection was recently borrowed,`poolValidMinDelay`Specifies whether to disable this verification to avoid unnecessary verification when the connection is frequently reused. 0 indicates that verification is performed every time a connection is requested. Default value: 1000 (milliseconds).
maxIdleTime	The maximum duration (in seconds) for which a connection can remain in the pool when it is not in use. This value must always be lower than`@wait_timeout-45s`. Default value: 600 seconds (10 minutes), with a minimum value of 60 seconds.
staticGlobal	Indicates that global variables will not be modified.`max_allowed_packet`, `wait_timeout`, `autocommit`, `auto_increment_increment`, `time_zone`, `system_time_zoneandtx_isolation`, which allows the connection pool to create new connections more quickly. Default value:`false`.
useResetConnection	When a connection is`closed()`When a connection is returned to the connection pool, the pool resets the connection state. With this option enabled, if allowed by the server, prepared commands are deleted, session variables are reset, and user variables are destroyed. This helps the server conserve memory when applications extensively use variables. Do not enable this option in conjunction with`useServerPrepStmts`can be used together. Default value:`false`.
registerJmxPool	Register the JMX monitoring pool. Default value:`true`.

Logging parameters

Parameters	Description
log	Enable logging. Default value:`false`.
maxQuerySizeToLog	The log displays only a number of characters corresponding to the size of this option. Default value: 1024.
slowQueryThresholdNanos	Queries with execution time exceeding this value are recorded (if defined). Default value: 1024.
profileSql	Log query execution time. Default value:`false`.

Other parameters

Parameters	Description
passwordCharacterEncoding	Specifies the password encoding charset. The value must be a Java charset, for example, UTF-8. Default value:`null`(the default character set of the platform).
useFractionalSeconds	Supports timestamps with sub-second precision. Default value:`true`.
allowMultiQueries	SQL string for executing multiple queries at once. For example,`insert into ab (i) values (1); insert into ab (i) values (2)`. Default value:`false`.
dumpQueriesOnException	If set to`true`, an exception containing the query string is thrown during query execution. Default value:`false`.
useCompression	Via`gzip`the database for network communication. This can provide better performance when database network overhead is high. Default value:`false`.
tcpAbortiveClose	This option can be used in environments where connections are created and closed rapidly in succession. Typically, sockets cannot be created in such an environment within a short period because all local "temporary" ports are exhausted by TCP connections and are in use.`TCP_WAIT`Status. Use`tcpAbortiveClose`This issue is resolved by resetting TCP connections (either actively closing or forcibly closing) rather than closing them in order. Use`socket.setSoLinger(true,0)`Perform a forced shutdown.
tinyInt1isBit	Data type mapping flag, which treats a MySQL Tiny column as a BIT (Boolean) column. Default value:`true`.
yearIsDateType	Treats Year as a date type, not a number. Default value:`true`.
sessionVariables	The value set when the connection was successfully established.`<var> = <value>`Yes, you can separate the session variables with commas.
localSocket	If the server allows it, you can connect to the database through a Unix domain socket. The value is the path of the Unix domain socket (that is, the Socket database parameter:`select @@ socket`).
sharedMemory	If the server allows it, connect to the database through shared memory. The value is the basic name of the shared memory.
interactiveClient	Session timeout is caused by`thewait_timeoutserver`Variable definition. Set`interactiveClient`Set to`true`will tell the server to use`interactive_timeoutserver`Variable. Default value:`false`.
useOldAliasMetadataBehavior	Metadata is transmitted via`ResultSetMetaData.getTableName()`Returns the name of the physical table. If set to`useOldAliasMetadataBehavior`, you can obtain the table alias. Default value:`false`.
createDatabaseIfNotExist	Creates the specified database in the URL if it does not exist. Default value:`false`.
serverTimezone	Defines the server's time zone. This parameter is used only when different server time zones are implemented on the GRE servers (it is recommended to have the same server time zone).
cachePrepStmts	If`useServerPrepStmts = true`, the prepared information is cached in an LRU cache to avoid re-preparing the command. The next time this command is used, the prepared identifier and parameters (if any) are sent to the server, thereby avoiding the need for the server to re-parse the query. Default value:`false`.
prepStmtCacheSize	If`useServerPrepStmts = true`, you can define the option`cachePrepStmts`The size of the prepared statement cache. Default value: 250.
prepStmtCacheSqlLimit	If`useServerPrepStmts = true`, queries exceeding this threshold will not be cached. Default value: 2048.
jdbcCompliantTruncation	Truncation errors ("Data in column '%' at line % was truncated", "Value of column '%' at line % is out of range") are treated as errors rather than warnings. Default value:`true`.
cacheCallableStmts	Enables/disables caching for Callable Statements. Default value:`true`.
callableStmtCacheSize	If enabled,`cacheCallableStmts`, set the number of Callable Statements cached by the driver for each VM. Default value: 150.
useBatchMultiSendNumber	When the option`useBatchMultiSend`When it is in the active state, specifies the maximum number of consecutive queries that can be sent before reading the results. Default value: 100.
connectionAttributes	When`performance_schema`When it is active, it allows data to be stored in key-value pairs (for example:`connectionAttributes = key1:value1,key2,value2)`Send some client information to the server. This information can be used in tables on the server.`performance_schema.session_connect_attrs`and`performance_schema.session_account_connect_attrs`Retrieved from .
usePipelineAuth	Different queries will be executed during the connection. If this option is enabled, queries are sent via pipelining (sending all queries and then reading all results), which allows for faster connection establishment. Default value:`true`.
enablePacketDebug	The driver will retain the last 16 MySQL data exchange packets (limited to the first 1000 bytes). In case of an IOException, the hexadecimal values of these packets are appended to the error message.`stacktrace`. This option has no impact on performance, but the driver will occupy more than 16 KB of memory. Default value:`false`.
useBulkStmts	Use dedicated whenever possible.`COM_STMT_BULK_EXECUTE`Perform batch inserts using the protocol. (Excluding`Statement.RETURN_GENERATED_KEYS`and stream batch processing). Default value:`false`.
autocommit	Sets the default value for auto-commit during connection initialization. Default value:`true`.
galeraAllowedState	Typically,`Connection.isValid`It simply sends an empty packet to the server, which in turn sends a small response to ensure connectivity. With this option enabled, the connector will ensure that the Galera server status`wsrep_local_state`The allowed values (separated by commas). For example, for " 4,5", the recommended value is " 4". Default value: empty.
includeInnodbStatusInDeadlockExceptions	When a deadlock exception occurs, the`SHOW ENGINE INNODB STATUS`Add result to exception tracking. Default value:`false`.
includeThreadDumpInDeadlockExceptions	Add thread dumps to the exception trace when a deadlock exception occurs. Default value:`false`.
useReadAheadInput	Buffered`inputSteam`Reads available socket data. Default value:`true`.
servicePrincipalName	When using GSSAPI authentication, this value is used as the Service Principal Name (SPN), rather than the name defined for the user account on the database server.
useCompatibleMetadata	force yes yes yes yes yes yes`DatabaseMetadata.getDatabaseProductName()`Returns MySQL as the database, not the actual database type. Default value:`false`.
defaultFetchSize	The driver will call on all newly created Statements.`setFetchSize(n)`. Default value: 0.
blankTableNameMeta	Result set metadata`getTableName`Always return blank. This option is primarily for compatibility with Oracle Database. Default value:`false`.
serverRsaPublicKeyFile	Specifies the tool used for`sha256_password`and`caching_sha2_password`The path to the RSA server public key file for password authentication.
allowPublicKeyRetrieval	When not set`serverRsaPublicKeyFile`When the client requests an RSA server public key (for the`sha256_password`and`caching_sha2_password`(password for authentication). Default value:`false`.
tlsSocketType	Specify the TLS version to use.`org.oceanbase.jdbc.tls.TlsSocketPlugin`Plugin type. The plugin must exist in`classpath`.
credentialType	Specifies the type of credential plugin to use. The plugin must be located in the`classpath`.
trackSchema	The server has`CLIENT_SESSION_TRACK`When the feature is disabled, it is allowed to disable`session_track_schema`The default value is:`true`.
clobberStreamingResults	If another query is executed before all data is read from the slave, the streaming result set will be automatically closed, and the data that was being streamed but not yet completed will be discarded. Default value:`false`.
maxRows	The maximum number of rows to return. Default value:`0`, which means to return all rows.
zeroDateTimeBehavior	Three ways to handle invalid dates in MySQL-compatible mode. Valid values:`convertToNull`, `exception` or `round`, that is,`ZERO_DATETIME_CONVERT_TO_NULL = "convertToNull";ZERO_DATETIME_EXCEPTION = "exception";ZERO_DATETIME_ROUND = "round";`Default:`ZERO_DATETIME_EXCEPTION`.
allowNanAndInf	Whether NaN or +/- INF values are allowed in PreparedStatement.setDouble(). Default value:`false`.
defaultConnectionAttributesBanList	When`sendConnectionAttributes=true`When the connection is closed, you can use this parameter to control the list of connection attributes that are not sent to the server. The list is separated by commas (,) and is case-sensitive. Default value:`null`.
useInformationSchema	Specifies whether to use the INFORMATION_SCHEMA to derive information for "DatabaseMetaData". Default value: `false`.
generateSimpleParameterMetadata	When set to true, the driver generates simple parameter metadata. Default value: `false`.

OceanBase

Customer Stories

Documentation

Database URL