com.mysql.cj.jdbc

## Interface JdbcConnection

All Superinterfaces:
  AutoCloseable, Connection, MysqlConnection, TransactionEventHandler, Wrapper

All Known Subinterfaces:
  LoadBalancedConnection, ReplicationConnection

    public interface JdbcConnection
    extends Connection, MysqlConnection, TransactionEventHandler

This interface contains methods that are considered the "vendor extension" to the JDBC API for MySQL's implementation of java.sql.Connection. For those looking further into the driver implementation, it is not an API that is used for plugability of implementations inside our driver (which is why there are still references to ConnectionImpl throughout the code).

### Field Summary

### Fields inherited from interface java.sql.Connection

`TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `abortInternal()` Clobbers the physical network connection and marks this connection as closed.
`void` `changeUser(String userName, String newPassword)` Changes the user on this connection by performing a re-authentication.
`PreparedStatement` `clientPrepareStatement(String sql)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`PreparedStatement` `clientPrepareStatement(String sql, int autoGenKeyIndex)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`PreparedStatement` `clientPrepareStatement(String sql, int[] autoGenKeyIndexes)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`PreparedStatement` `clientPrepareStatement(String sql, int resultSetType, int resultSetConcurrency)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`PreparedStatement` `clientPrepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`PreparedStatement` `clientPrepareStatement(String sql, String[] autoGenKeyColNames)` Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
`void` `decachePreparedStatement(JdbcPreparedStatement pstmt)`
`void` `doClose(Throwable cause, CloseOption... options)` Close the connection and release resources.
`JdbcConnection` `getActiveMySQLConnection()`
`int` `getActiveStatementCount()` Returns the number of statements active on this connection, which haven't been .close()d.
`int` `getAutoIncrementIncrement()` Returns the session value of 'auto_increment_increment' from the server if it exists, or '1' if not.
`CachedResultSetMetaData` `getCachedMetaData(String sql)` Returns cached metadata (or null if not cached) for the given query, which must match _exactly_.
`String` `getCharacterSetMetadata()`
`ClientInfoProvider` `getClientInfoProviderImpl()`
`String` `getDatabase()` Retrieves this connection object's current database name.
`String` `getHost()`
`String` `getHostPortPair()`
`long` `getIdleFor()` Reports how long this connection has been idle.
`Lock` `getLock()`
`Statement` `getMetadataSafeStatement()`
`JdbcConnection` `getMultiHostParentProxy()`
`JdbcConnection` `getMultiHostSafeProxy()`
`JdbcPropertySet` `getPropertySet()`
`List<QueryInterceptor>` `getQueryInterceptorsInstances()`
`ServerVersion` `getServerVersion()`
`int` `getSessionMaxRows()` Returns the sql select limit max-rows for this session.
`String` `getStatementComment()` Returns the comment that will be prepended to all statements sent to the server.
`boolean` `hasSameProperties(JdbcConnection c)` Does this connection have the same properties as another?
`void` `initializeResultsMetadataFromCache(String sql, CachedResultSetMetaData cachedMetaData, ResultSetInternalMethods resultSet)` Caches CachedResultSetMetaData that has been placed in the cache using the given SQL as a key.
`void` `initializeSafeQueryInterceptors()`
`boolean` `isInGlobalTx()` Is this connection currently a participant in an XA transaction?
`boolean` `isProxySet()`
`boolean` `isReadOnly(boolean useSessionStatus)` Tests to see if the connection is in Read Only Mode.
`boolean` `isSameResource(JdbcConnection c)` Does this connection have the same resource name as the given connection (for XA)?
`boolean` `isServerLocal()` Is the server this connection is connected to "local" (i.e.
`boolean` `isSourceConnection()` Is this connection connected to the first host in the list if there is a list of servers in the URL?
`boolean` `lowerCaseTableNames()` Is the server configured to use lower-case table names only?
`void` `ping()` Detect if the connection is still good by sending a ping command to the server.
`void` `pingInternal(boolean checkForClosedConnection, int timeoutMillis)`
`void` `recachePreparedStatement(JdbcPreparedStatement pstmt)`
`void` `registerStatement(JdbcStatement stmt)` Register a Statement instance as open.
`void` `resetServerState()` Resets the server-side state of this connection.
`PreparedStatement` `serverPrepareStatement(String sql)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`PreparedStatement` `serverPrepareStatement(String sql, int autoGenKeyIndex)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`PreparedStatement` `serverPrepareStatement(String sql, int[] autoGenKeyIndexes)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`PreparedStatement` `serverPrepareStatement(String sql, int resultSetType, int resultSetConcurrency)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`PreparedStatement` `serverPrepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`PreparedStatement` `serverPrepareStatement(String sql, String[] autoGenKeyColNames)` Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.
`void` `setDatabase(String dbName)` Set current database for this connection.
`void` `setFailedOver(boolean flag)`
`void` `setInGlobalTx(boolean flag)` Set the state of being in a global (XA) transaction.
`void` `setProxy(JdbcConnection proxy)`
`void` `setReadOnlyInternal(boolean readOnlyFlag)`
`void` `setSessionMaxRows(int max)` Sets the sql select limit max-rows for this session if different from current.
`void` `setStatementComment(String comment)` Sets the comment that will be prepended to all statements sent to the server.
`void` `shutdownServer()` Used by MiniAdmin to shutdown a MySQL server
`boolean` `storesLowerCaseTableName()`
`void` `throwConnectionClosedException()`
`void` `unregisterStatement(JdbcStatement stmt)` Remove the given statement from the list of open statements
`void` `unSafeQueryInterceptors()`

### Methods inherited from interface java.sql.Connection

`abort, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap`

### Methods inherited from interface java.sql.Wrapper

`isWrapperFor, unwrap`

### Methods inherited from interface com.mysql.cj.MysqlConnection

`checkClosed, cleanup, createNewIO, getConnectionLock, getExceptionInterceptor, getId, getProperties, getServerSessionStateController, getSession, getURL, getUser`

### Methods inherited from interface com.mysql.cj.TransactionEventHandler

`transactionBegun, transactionCompleted`

### Method Detail

#### getLock

    Lock getLock()

#### getPropertySet

    JdbcPropertySet getPropertySet()

Specified by:
  `getPropertySet` in interface `MysqlConnection`

#### changeUser

    void changeUser(String userName,
                    String newPassword)
             throws SQLException

Changes the user on this connection by performing a re-authentication. If authentication fails, the connection is failed.

Parameters:
  `userName` - the username to authenticate with
  `newPassword` - the password to authenticate with
Throws:
  `SQLException` - if authentication fails, or some other error occurs while performing the command.

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String)`

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql,
                                             int autoGenKeyIndex)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyIndex` - autoGenKeyIndex
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int)`

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql,
                                             int resultSetType,
                                             int resultSetConcurrency)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
  `resultSetType` - resultSetType
  `resultSetConcurrency` - resultSetConcurrency
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int, int)`

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql,
                                             int[] autoGenKeyIndexes)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyIndexes` - autoGenKeyIndexes
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int[])`

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql,
                                             int resultSetType,
                                             int resultSetConcurrency,
                                             int resultSetHoldability)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
  `resultSetType` - resultSetType
  `resultSetConcurrency` - resultSetConcurrency
  `resultSetHoldability` - resultSetHoldability
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int, int, int)`

#### clientPrepareStatement

    PreparedStatement clientPrepareStatement(String sql,
                                             String[] autoGenKeyColNames)
                                      throws SQLException

Prepares a statement on the client, using client-side emulation (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyColNames` - autoGenKeyColNames
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, String[])`

#### getActiveStatementCount

    int getActiveStatementCount()

Returns the number of statements active on this connection, which haven't been .close()d.

Returns:
  the number of active statements

#### getIdleFor

    long getIdleFor()

Reports how long this connection has been idle. This time (reported in milliseconds) is updated once a query has completed.

Returns:
  number of ms that this connection has been idle, 0 if the driver is busy retrieving results.

#### getStatementComment

    String getStatementComment()

Returns the comment that will be prepended to all statements sent to the server.

Returns:
  the comment that will be prepended to all statements sent to the server.

#### isInGlobalTx

    boolean isInGlobalTx()

Is this connection currently a participant in an XA transaction?

Returns:
  true if this connection currently a participant in an XA transaction

#### setInGlobalTx

    void setInGlobalTx(boolean flag)

Set the state of being in a global (XA) transaction.

Parameters:
  `flag` - the state flag

#### isSourceConnection

    boolean isSourceConnection()

Is this connection connected to the first host in the list if there is a list of servers in the URL?

Returns:
  true if this connection is connected to the first in the list.

#### isSameResource

    boolean isSameResource(JdbcConnection c)

Does this connection have the same resource name as the given connection (for XA)?

Parameters:
  `c` - connection
Returns:
  true if it is the same one

#### lowerCaseTableNames

    boolean lowerCaseTableNames()

Is the server configured to use lower-case table names only?

Returns:
  true if lower_case_table_names is 'on'

#### ping

    void ping()
       throws SQLException

Detect if the connection is still good by sending a ping command to the server.

Throws:
  `SQLException` - if the ping fails

#### resetServerState

    void resetServerState()
                   throws SQLException

Resets the server-side state of this connection. Doesn't work if isParanoid() is set (it will become a no-op in this case). Usually only used from connection pooling code.

Throws:
  `SQLException` - if the operation fails while resetting server state.

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String)`

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql,
                                             int autoGenKeyIndex)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyIndex` - autoGenKeyIndex
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int)`

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql,
                                             int resultSetType,
                                             int resultSetConcurrency)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
  `resultSetType` - resultSetType
  `resultSetConcurrency` - resultSetConcurrency
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int, int)`

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql,
                                             int resultSetType,
                                             int resultSetConcurrency,
                                             int resultSetHoldability)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
  `resultSetType` - resultSetType
  `resultSetConcurrency` - resultSetConcurrency
  `resultSetHoldability` - resultSetHoldability
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int, int, int)`

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql,
                                             int[] autoGenKeyIndexes)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyIndexes` - autoGenKeyIndexes
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, int[])`

#### serverPrepareStatement

    PreparedStatement serverPrepareStatement(String sql,
                                             String[] autoGenKeyColNames)
                                      throws SQLException

Prepares a statement on the server (regardless of the configuration property 'useServerPrepStmts') with the same semantics as the method java.sql.Connection.prepareStatement() with the same argument types.

Parameters:
  `sql` - statement
  `autoGenKeyColNames` - autoGenKeyColNames
Returns:
  prepared statement
Throws:
  `SQLException` - if an error occurs
See Also:
  `Connection.prepareStatement(String, String[])`

#### setFailedOver

    void setFailedOver(boolean flag)

Parameters:
  `flag` - The failedOver flag to set.

#### setStatementComment

    void setStatementComment(String comment)

Sets the comment that will be prepended to all statements sent to the server. Do not use slash-star or star-slash tokens in the comment as these will be added by the driver itself.

Parameters:
  `comment` - the comment that will be prepended to all statements sent to the server.

#### shutdownServer

    void shutdownServer()
                 throws SQLException

Used by MiniAdmin to shutdown a MySQL server

Throws:
  `SQLException` - if the command can not be issued.

#### getAutoIncrementIncrement

    int getAutoIncrementIncrement()

Returns the session value of 'auto_increment_increment' from the server if it exists, or '1' if not.

Returns:
  the session value of 'auto_increment_increment'

#### hasSameProperties

    boolean hasSameProperties(JdbcConnection c)

Does this connection have the same properties as another?

Parameters:
  `c` - connection
Returns:
  true if has the same properties

#### getHost

    String getHost()

#### getHostPortPair

    String getHostPortPair()

#### setProxy

    void setProxy(JdbcConnection proxy)

#### isServerLocal

    boolean isServerLocal()
                   throws SQLException

Is the server this connection is connected to "local" (i.e. same host) as the application?

Returns:
  true if the server is "local"
Throws:
  `SQLException` - if an error occurs

#### getSessionMaxRows

    int getSessionMaxRows()

Returns the sql select limit max-rows for this session.

Returns:
  int max rows

#### setSessionMaxRows

    void setSessionMaxRows(int max)
                    throws SQLException

Sets the sql select limit max-rows for this session if different from current.

Parameters:
  `max` - the new max-rows value to set.
Throws:
  `SQLException` - if a database error occurs issuing the statement that sets the limit.

#### abortInternal

    void abortInternal()
                throws SQLException

Clobbers the physical network connection and marks this connection as closed.

Throws:
  `SQLException` - if an error occurs

#### isProxySet

    boolean isProxySet()

#### getCachedMetaData

    CachedResultSetMetaData getCachedMetaData(String sql)

Returns cached metadata (or null if not cached) for the given query, which must match _exactly_. Calls to this method must be guarded by the Connection object lock that can be obtained by `MysqlConnection.getConnectionLock()`.

Parameters:
  `sql` - the query that is the key to the cache
Returns:
  metadata cached for the given SQL, or none if it doesn't exist.

#### getCharacterSetMetadata

    String getCharacterSetMetadata()

Returns:
  Returns the characterSetMetadata.

#### getMetadataSafeStatement

    Statement getMetadataSafeStatement()
                                throws SQLException

Throws:
  `SQLException`

#### getServerVersion

    ServerVersion getServerVersion()

#### getQueryInterceptorsInstances

    List<QueryInterceptor> getQueryInterceptorsInstances()

#### initializeResultsMetadataFromCache

    void initializeResultsMetadataFromCache(String sql,
                                            CachedResultSetMetaData cachedMetaData,
                                            ResultSetInternalMethods resultSet)
                                     throws SQLException

Caches CachedResultSetMetaData that has been placed in the cache using the given SQL as a key. Calls to this method must be guarded by the Connection object lock that can be obtained by `MysqlConnection.getConnectionLock()`.

Parameters:
  `sql` - the query that the metadata pertains too.
  `cachedMetaData` - metadata (if it exists) to populate the cache.
  `resultSet` - the result set to retrieve metadata from, or apply to.
Throws:
  `SQLException` - if an error occurs

#### initializeSafeQueryInterceptors

    void initializeSafeQueryInterceptors()
                                  throws SQLException

Throws:
  `SQLException`

#### isReadOnly

    boolean isReadOnly(boolean useSessionStatus)
                throws SQLException

Tests to see if the connection is in Read Only Mode.

Parameters:
  `useSessionStatus` - in some cases, for example when restoring connection with autoReconnect=true, we can rely only on saved readOnly state, so use useSessionStatus=false in that case
Returns:
  true if the connection is read only
Throws:
  `SQLException` - if a database access error occurs

#### pingInternal

    void pingInternal(boolean checkForClosedConnection,
                      int timeoutMillis)
               throws SQLException

Throws:
  `SQLException`

#### doClose

    void doClose(Throwable cause,
                 CloseOption... options)
          throws SQLException

Close the connection and release resources.

Parameters:
  `cause` - the exception that caused this method call
  `options` - options indicating how the close was initiated and/or what should be performed during the close
Throws:
  `SQLException` - if an error occurs

#### recachePreparedStatement

    void recachePreparedStatement(JdbcPreparedStatement pstmt)
                           throws SQLException

Throws:
  `SQLException`

#### decachePreparedStatement

    void decachePreparedStatement(JdbcPreparedStatement pstmt)
                           throws SQLException

Throws:
  `SQLException`

#### registerStatement

    void registerStatement(JdbcStatement stmt)

Register a Statement instance as open.

Parameters:
  `stmt` - the Statement instance to remove

#### setReadOnlyInternal

    void setReadOnlyInternal(boolean readOnlyFlag)
                      throws SQLException

Throws:
  `SQLException`

#### storesLowerCaseTableName

    boolean storesLowerCaseTableName()

#### throwConnectionClosedException

    void throwConnectionClosedException()
                                 throws SQLException

Throws:
  `SQLException`

#### unregisterStatement

    void unregisterStatement(JdbcStatement stmt)

Remove the given statement from the list of open statements

Parameters:
  `stmt` - the Statement instance to remove

#### unSafeQueryInterceptors

    void unSafeQueryInterceptors()
                          throws SQLException

Throws:
  `SQLException`

#### getMultiHostSafeProxy

    JdbcConnection getMultiHostSafeProxy()

#### getMultiHostParentProxy

    JdbcConnection getMultiHostParentProxy()

#### getActiveMySQLConnection

    JdbcConnection getActiveMySQLConnection()

#### getClientInfoProviderImpl

    ClientInfoProvider getClientInfoProviderImpl()
                                          throws SQLException

Throws:
  `SQLException`

#### setDatabase

    void setDatabase(String dbName)
              throws SQLException

Set current database for this connection.

Parameters:
  `dbName` - the database for this connection to use
Throws:
  `SQLException` - if a database access error occurs

#### getDatabase

    String getDatabase()
                throws SQLException

Retrieves this connection object's current database name.

Returns:
  current database name
Throws:
  `SQLException` - if an error occurs

Copyright © 2016, 2024, Oracle and/or its affiliates.