Pre-General Availability Draft: 2018-03-20
MySQL Connector/J, as a rigorous implementation of the JDBC API, passes all of the tests in the publicly available version of Oracle's JDBC compliance test suite. The JDBC specification is flexible on how certain functionality should be implemented. This section gives details on an interface-by-interface level about implementation decisions that might affect how you code applications with MySQL Connector/J.
You can emulate BLOBs with locators by adding the property
emulateLocators=trueto your JDBC URL. Using this method, the driver will delay loading the actual BLOB data until you retrieve the other data and then use retrieval methods (
getBytes(), and so forth) on the BLOB data stream.
You must use a column alias with the value of the column to the actual name of the BLOB, for example:
SELECT id, 'data' as blob_data from blobtable
You must also follow these rules:
The BLOB implementation does not allow in-place modification (they are copies, as reported by the
DatabaseMetaData.locatorsUpdateCopies()method). Because of this, use the corresponding
ResultSet.updateBlob()(in the case of updatable result sets) methods to save changes back to the database.
Stored procedures are supported when connecting to MySQL using the
CallableStatementinterface. Currently, the
CallableStatementis not supported.
isClosed()method does not ping the server to determine if it is available. In accordance with the JDBC specification, it only returns true if
closed()has been called on the connection. If you need to determine if the connection is still valid, issue a simple query, such as
SELECT 1. The driver will throw an exception if the connection is no longer valid.
Foreign key information (
getCrossReference()) is only available from
InnoDBtables. The driver uses
SHOW CREATE TABLEto retrieve this information, so if any other storage engines add support for foreign keys, the driver would transparently support them as well.
Two variants of prepared statements are implemented by Connector/J, the client-side and the server-side prepared statements. Client-side prepared statements are used by default because early MySQL versions did not support the prepared statement feature or had problems with its implementation. Server-side prepared statements and binary-encoded result sets are used when the server supports them. To enable usage of server-side prepared statements, set
Be careful when using a server-side prepared statement with large parameters that are set using
setNCLob(). To re-execute the statement with any large parameter changed to a nonlarge parameter, call
clearParameters()and set all parameters again. The reason for this is as follows:
During both server-side prepared statements and client-side emulation, large data is exchanged only when
Once that has been done, the stream used to read the data on the client side is closed (as per the JDBC spec), and cannot be read from again.
If a parameter changes from large to nonlarge, the driver must reset the server-side state of the prepared statement to allow the parameter that is being changed to take the place of the prior large value. This removes all of the large data that has already been sent to the server, thus requiring the data to be re-sent, using the
Consequently, to change the type of a parameter to a nonlarge one, you must call
clearParameters()and set all parameters of the prepared statement again before it can be re-executed.
By default, ResultSets are completely retrieved and stored in memory. In most cases this is the most efficient way to operate and, due to the design of the MySQL network protocol, is easier to implement. If you are working with ResultSets that have a large number of rows or large values and cannot allocate heap space in your JVM for the memory required, you can tell the driver to stream the results back one row at a time.
To enable this functionality, create a
Statementinstance in the following manner:
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_READ_ONLY); stmt.setFetchSize(Integer.MIN_VALUE);
The combination of a forward-only, read-only result set, with a fetch size of
Integer.MIN_VALUEserves as a signal to the driver to stream result sets row-by-row. After this, any result sets created with the statement will be retrieved row-by-row.
There are some caveats with this approach. You must read all of the rows in the result set (or close it) before you can issue any other queries on the connection, or an exception will be thrown.
The earliest the locks these statements hold can be released (whether they be
MyISAMtable-level locks or row-level locks in some other storage engine such as
InnoDB) is when the statement completes.
If the statement is within scope of a transaction, then locks are released when the transaction completes (which implies that the statement needs to complete first). As with most other databases, statements are not complete until all the results pending on the statement are read or the active result set for the statement is closed.
Therefore, if using streaming results, process them as quickly as possible if you want to maintain concurrent access to the tables referenced by the statement producing the result set.
Another alternative is to use cursor-based streaming to retrieve a set number of rows each time. This can be done by setting the connection property
useCursorFetchto true, and then calling
intbeing the desired number of rows to be fetched each time:
conn = DriverManager.getConnection("jdbc:mysql://localhost/?useCursorFetch=true", "user", "s3cr3t"); stmt = conn.createStatement(); stmt.setFetchSize(100); rs = stmt.executeQuery("SELECT * FROM your_table_here");
Connector/J includes support for both
Statement.setQueryTimeout(). Both require a separate connection to issue the
KILL QUERYstatement. In the case of
setQueryTimeout(), the implementation creates an additional thread to handle the timeout functionality.Note
Failures to cancel the statement for
setQueryTimeout()may manifest themselves as
RuntimeExceptionrather than failing silently, as there is currently no way to unblock the thread that is executing the query being cancelled due to timeout expiration and have it throw the exception instead.
MySQL does not support SQL cursors, and the JDBC driver does not emulate them, so
setCursorName()has no effect.
Connector/J also supplies two additional methods:
InputStreaminstance that will be used to send data to the MySQL server for a
LOAD DATA LOCAL INFILEstatement rather than a
URLInputStreamthat represents the path given as an argument to the statement.
This stream will be read to completion upon execution of a
LOAD DATA LOCAL INFILEstatement, and will automatically be closed by the driver, so it needs to be reset before each call to
execute*()that would cause the MySQL server to request data to fulfill the request for
LOAD DATA LOCAL INFILE.
If this value is set to
NULL, the driver will revert to using a
InputStreaminstance that will be used to send data in response to a
LOAD DATA LOCAL INFILEstatement.
This method returns
NULLif no such stream has been set using