Package com.databricks.jdbc.api.impl

## Class DatabricksConnection

- java.lang.Object
- - com.databricks.jdbc.api.impl.DatabricksConnection

All Implemented Interfaces:
  `IDatabricksConnection`, `IDatabricksConnectionInternal`, `AutoCloseable`, `Connection`, `Wrapper`

    public class DatabricksConnection
    extends Object
    implements IDatabricksConnection, IDatabricksConnectionInternal

Implementation for Databricks specific connection.

### Field Summary

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

`TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

### Constructor Summary

Constructors
`DatabricksConnection​(IDatabricksConnectionContext connectionContext)` Creates an instance of Databricks connection for given connection context.
`DatabricksConnection​(IDatabricksConnectionContext connectionContext, IDatabricksClient testDatabricksClient)`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `abort​(Executor executor)`
`void` `beginRequest()`
`void` `clearWarnings()`
`void` `close()`
`void` `closeStatement​(IDatabricksStatement statement)` Closes a statement from the connection's active set.
`void` `commit()` Makes all changes made since the previous commit/rollback permanent.
`Array` `createArrayOf​(String typeName, Object[] elements)`
`Blob` `createBlob()`
`Clob` `createClob()`
`NClob` `createNClob()`
`SQLXML` `createSQLXML()`
`Statement` `createStatement()`
`Statement` `createStatement​(int resultSetType, int resultSetConcurrency)`
`Statement` `createStatement​(int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
`Struct` `createStruct​(String typeName, Object[] attributes)`
`void` `endRequest()`
`boolean` `getAutoCommit()` Retrieves the current auto-commit mode for this connection.
`String` `getCatalog()`
`Properties` `getClientInfo()` Retrieves all client and session properties as a Properties object.
`String` `getClientInfo​(String name)` Retrieves the value of the specified client info property. case-insensitive
`Connection` `getConnection()` Returns the corresponding sql connection object
`IDatabricksConnectionContext` `getConnectionContext()` Returns the connection context associated with the connection.
`String` `getConnectionId()` Retrieves the unique identifier for this connection.
`int` `getHoldability()`
`DatabaseMetaData` `getMetaData()`
`int` `getNetworkTimeout()`
`String` `getSchema()`
`IDatabricksSession` `getSession()` Returns the underlying session for the connection.
`Statement` `getStatement​(String statementId)` Retrieves a statement handle for a given statement ID.
`int` `getTransactionIsolation()`
`Map<String,​Class<?>>` `getTypeMap()`
`SQLWarning` `getWarnings()`
`boolean` `isClosed()`
`boolean` `isReadOnly()`
`boolean` `isValid​(int timeout)`
`boolean` `isWrapperFor​(Class<?> iface)`
`String` `nativeSQL​(String sql)`
`void` `open()` Opens the connection and initiates the underlying session
`CallableStatement` `prepareCall​(String sql)`
`CallableStatement` `prepareCall​(String sql, int resultSetType, int resultSetConcurrency)`
`CallableStatement` `prepareCall​(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
`PreparedStatement` `prepareStatement​(String sql)`
`PreparedStatement` `prepareStatement​(String sql, int autoGeneratedKeys)`
`PreparedStatement` `prepareStatement​(String sql, int[] columnIndexes)`
`PreparedStatement` `prepareStatement​(String sql, int resultSetType, int resultSetConcurrency)`
`PreparedStatement` `prepareStatement​(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
`PreparedStatement` `prepareStatement​(String sql, String[] columnNames)`
`void` `releaseSavepoint​(Savepoint savepoint)`
`void` `rollback()` Undoes all changes made in the current transaction.
`void` `rollback​(Savepoint savepoint)`
`void` `setAutoCommit​(boolean autoCommit)` Sets the auto-commit mode for this connection to the given state.
`void` `setCatalog​(String catalog)`
`void` `setClientInfo​(String name, String value)` Sets a client info property/session config
`void` `setClientInfo​(Properties properties)` Sets multiple client info properties from the provided Properties object.
`void` `setHoldability​(int holdability)`
`void` `setNetworkTimeout​(Executor executor, int milliseconds)`
`void` `setReadOnly​(boolean readOnly)`
`Savepoint` `setSavepoint()`
`Savepoint` `setSavepoint​(String name)`
`void` `setSchema​(String schema)`
`void` `setShardingKey​(ShardingKey shardingKey)`
`void` `setShardingKey​(ShardingKey shardingKey, ShardingKey superShardingKey)`
`boolean` `setShardingKeyIfValid​(ShardingKey shardingKey, int timeout)`
`boolean` `setShardingKeyIfValid​(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout)`
`void` `setTransactionIsolation​(int level)`
`void` `setTypeMap​(Map<String,​Class<?>> map)`
`<T> T` `unwrap​(Class<T> iface)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DatabricksConnection

    public DatabricksConnection​(IDatabricksConnectionContext connectionContext)
                         throws DatabricksSQLException

Creates an instance of Databricks connection for given connection context.

Parameters:
  `connectionContext` - underlying connection context
Throws:
  `DatabricksSQLException`

#### DatabricksConnection

    public DatabricksConnection​(IDatabricksConnectionContext connectionContext,
                                IDatabricksClient testDatabricksClient)
                         throws DatabricksSQLException

Throws:
  `DatabricksSQLException`

### Method Detail

#### open

    public void open()
              throws SQLException

Description copied from interface: `IDatabricksConnectionInternal`
Opens the connection and initiates the underlying session

Specified by:
  `open` in interface `IDatabricksConnectionInternal`
Throws:
  `SQLException`

#### getStatement

    public Statement getStatement​(String statementId)
                           throws SQLException

Description copied from interface: `IDatabricksConnection`
Retrieves a statement handle for a given statement ID.

Specified by:
  `getStatement` in interface `IDatabricksConnection`
Parameters:
  `statementId` - The unique identifier of the statement to retrieve
Returns:
  A `Statement` object representing the statement
Throws:
  `SQLException` - if a database access error occurs or this method is called on a closed connection

#### getConnectionId

    public String getConnectionId()
                           throws SQLException

Description copied from interface: `IDatabricksConnection`
Retrieves the unique identifier for this connection.

Specified by:
  `getConnectionId` in interface `IDatabricksConnection`
Returns:
  A string representing the unique connection ID
Throws:
  `SQLException` - if a database access error occurs or this method is called on a closed connection

#### getSession

    public IDatabricksSession getSession()

Description copied from interface: `IDatabricksConnectionInternal`
Returns the underlying session for the connection.

Specified by:
  `getSession` in interface `IDatabricksConnectionInternal`

#### createStatement

    public Statement createStatement()
                              throws SQLException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareCall

    public CallableStatement prepareCall​(String sql)
                                  throws SQLException

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLException`

#### nativeSQL

    public String nativeSQL​(String sql)
                     throws SQLException

Specified by:
  `nativeSQL` in interface `Connection`
Throws:
  `SQLException`

#### setAutoCommit

    public void setAutoCommit​(boolean autoCommit)
                       throws SQLException

Sets the auto-commit mode for this connection to the given state.

When auto-commit is enabled (the default), each SQL statement is executed as an individual transaction and is committed immediately upon completion.

When auto-commit is disabled, SQL statements are grouped into transactions that must be explicitly committed via `commit()` or rolled back via `rollback()`. When auto-commit is disabled, a new transaction is automatically started:

- Immediately after executing SET AUTOCOMMIT = FALSE
- After each COMMIT or ROLLBACK statement

Thread Safety

This method is not thread-safe. The `Connection` object should not be shared across multiple threads. Concurrent access may lead to undefined behavior and server-side transaction aborts due to sequence ID mismatches. Each thread should obtain its own `Connection` from a connection pool.

Example Usage

     // Disable auto-commit to start a transaction
     connection.setAutoCommit(false);

     try {
         // Execute multiple statements as part of one transaction
         statement.executeUpdate("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
         statement.executeUpdate("UPDATE accounts SET balance = balance + 100 WHERE id = 2");

         // Commit the transaction
         connection.commit();
     } catch (SQLException e) {
         // Rollback on error
         connection.rollback();
         throw e;
     }

Specified by:
  `setAutoCommit` in interface `Connection`
Parameters:
  `autoCommit` - `true` to enable auto-commit mode; `false` to disable it
Throws:
  `DatabricksSQLException` - if the connection is closed
  `DatabricksTransactionException` - if the auto-commit mode cannot be changed due to an active transaction or invalid state
  `SQLException`
See Also:
  `getAutoCommit()`, `commit()`, `rollback()`

#### getAutoCommit

    public boolean getAutoCommit()
                          throws SQLException

Retrieves the current auto-commit mode for this connection.

On a newly created connection, returns `true` (JDBC default) without making a server round-trip.

After `setAutoCommit(boolean)` is called, returns the cached value from the session.

If the connection property `FetchAutoCommitFromServer=1` is set, this method will query the server using `SET AUTOCOMMIT` SQL command to retrieve the current auto-commit state, ensuring the returned value matches the server state. This is useful for debugging or when strict state verification is needed.

Specified by:
  `getAutoCommit` in interface `Connection`
Returns:
  true if auto-commit mode is enabled; false otherwise
Throws:
  `DatabricksSQLException` - if the connection is closed
  `DatabricksSQLException` - if querying the server fails (when FetchAutoCommitFromServer=1)
  `SQLException`
See Also:
  `setAutoCommit(boolean)`

#### commit

    public void commit()
                throws SQLException

Makes all changes made since the previous commit/rollback permanent.

This method should be used only when auto-commit mode has been disabled.

When auto-commit is FALSE:

- Commits the current transaction
- A new transaction begins automatically

When auto-commit is TRUE:

- This operation throws `DatabricksTransactionException` (if ignoreTransactions flag is not set)

Specified by:
  `commit` in interface `Connection`
Throws:
  `DatabricksSQLException` - if the connection is closed
  `DatabricksTransactionException` - for transaction-specific errors such as MULTI_STATEMENT_TRANSACTION_NO_ACTIVE_TRANSACTION or MULTI_STATEMENT_TRANSACTION_ROLLBACK_REQUIRED_AFTER_ABORT
  `SQLException`
See Also:
  `setAutoCommit(boolean)`, `rollback()`

#### rollback

    public void rollback()
                  throws SQLException

Undoes all changes made in the current transaction.

This method should be used only when auto-commit mode has been disabled.

When auto-commit is FALSE:

- Rolls back the current transaction
- A new transaction begins automatically (per autocommit design)

When auto-commit is TRUE:

- ROLLBACK is a safe no-op (does not throw exception)
- This is more forgiving than COMMIT, which throws an exception when there's no active transaction

Note: ROLLBACK is designed to be safe to call even when there is no active transaction. It can be used to recover from error states without needing to check transaction status first.

Specified by:
  `rollback` in interface `Connection`
Throws:
  `DatabricksSQLException` - if the connection is closed
  `DatabricksTransactionException` - for transaction-specific errors (rare - ROLLBACK is typically very forgiving)
  `SQLException`
See Also:
  `setAutoCommit(boolean)`, `commit()`

#### close

    public void close()
               throws SQLException

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Connection`
Throws:
  `SQLException`

#### isClosed

    public boolean isClosed()
                     throws SQLException

Specified by:
  `isClosed` in interface `Connection`
Throws:
  `SQLException`

#### getMetaData

    public DatabaseMetaData getMetaData()
                                 throws SQLException

Specified by:
  `getMetaData` in interface `Connection`
Throws:
  `SQLException`

#### setReadOnly

    public void setReadOnly​(boolean readOnly)
                     throws SQLException

Specified by:
  `setReadOnly` in interface `Connection`
Throws:
  `SQLException`

#### isReadOnly

    public boolean isReadOnly()
                       throws SQLException

Specified by:
  `isReadOnly` in interface `Connection`
Throws:
  `SQLException`

#### setCatalog

    public void setCatalog​(String catalog)
                    throws SQLException

Specified by:
  `setCatalog` in interface `Connection`
Throws:
  `SQLException`

#### getCatalog

    public String getCatalog()
                      throws SQLException

Specified by:
  `getCatalog` in interface `Connection`
Throws:
  `SQLException`

#### setTransactionIsolation

    public void setTransactionIsolation​(int level)
                                 throws SQLException

Specified by:
  `setTransactionIsolation` in interface `Connection`
Throws:
  `SQLException`

#### getTransactionIsolation

    public int getTransactionIsolation()
                                throws SQLException

Specified by:
  `getTransactionIsolation` in interface `Connection`
Throws:
  `SQLException`

#### getWarnings

    public SQLWarning getWarnings()
                           throws SQLException

Specified by:
  `getWarnings` in interface `Connection`
Throws:
  `SQLException`

#### clearWarnings

    public void clearWarnings()
                       throws SQLException

Specified by:
  `clearWarnings` in interface `Connection`
Throws:
  `SQLException`

#### createStatement

    public Statement createStatement​(int resultSetType,
                                     int resultSetConcurrency)
                              throws SQLException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int resultSetType,
                                              int resultSetConcurrency)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareCall

    public CallableStatement prepareCall​(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency)
                                  throws SQLException

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLException`

#### getTypeMap

    public Map<String,​Class<?>> getTypeMap()

Specified by:
  `getTypeMap` in interface `Connection`

#### setTypeMap

    public void setTypeMap​(Map<String,​Class<?>> map)
                    throws SQLException

Specified by:
  `setTypeMap` in interface `Connection`
Throws:
  `SQLException`

#### setHoldability

    public void setHoldability​(int holdability)
                        throws SQLException

Specified by:
  `setHoldability` in interface `Connection`
Throws:
  `SQLException`

#### getHoldability

    public int getHoldability()
                       throws SQLException

Specified by:
  `getHoldability` in interface `Connection`
Throws:
  `SQLException`

#### setSavepoint

    public Savepoint setSavepoint()
                           throws SQLException

Specified by:
  `setSavepoint` in interface `Connection`
Throws:
  `SQLException`

#### setSavepoint

    public Savepoint setSavepoint​(String name)
                           throws SQLException

Specified by:
  `setSavepoint` in interface `Connection`
Throws:
  `SQLException`

#### rollback

    public void rollback​(Savepoint savepoint)
                  throws SQLException

Specified by:
  `rollback` in interface `Connection`
Throws:
  `SQLException`

#### releaseSavepoint

    public void releaseSavepoint​(Savepoint savepoint)
                          throws SQLException

Specified by:
  `releaseSavepoint` in interface `Connection`
Throws:
  `SQLException`

#### createStatement

    public Statement createStatement​(int resultSetType,
                                     int resultSetConcurrency,
                                     int resultSetHoldability)
                              throws SQLException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int resultSetType,
                                              int resultSetConcurrency,
                                              int resultSetHoldability)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareCall

    public CallableStatement prepareCall​(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency,
                                         int resultSetHoldability)
                                  throws SQLException

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int autoGeneratedKeys)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int[] columnIndexes)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              String[] columnNames)
                                       throws SQLException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLException`

#### createClob

    public Clob createClob()
                    throws SQLException

Specified by:
  `createClob` in interface `Connection`
Throws:
  `SQLException`

#### createBlob

    public Blob createBlob()
                    throws SQLException

Specified by:
  `createBlob` in interface `Connection`
Throws:
  `SQLException`

#### createNClob

    public NClob createNClob()
                      throws SQLException

Specified by:
  `createNClob` in interface `Connection`
Throws:
  `SQLException`

#### createSQLXML

    public SQLXML createSQLXML()
                        throws SQLException

Specified by:
  `createSQLXML` in interface `Connection`
Throws:
  `SQLException`

#### isValid

    public boolean isValid​(int timeout)
                    throws SQLException

Specified by:
  `isValid` in interface `Connection`
Throws:
  `SQLException`

#### setClientInfo

    public void setClientInfo​(String name,
                              String value)
                       throws SQLClientInfoException

Sets a client info property/session config

Specified by:
  `setClientInfo` in interface `Connection`
Parameters:
  `name` - The name of the property to set
  `value` - The value to set
Throws:
  `SQLClientInfoException` - If the property cannot be set due to validation errors or if the property name is not recognized

#### setClientInfo

    public void setClientInfo​(Properties properties)
                       throws SQLClientInfoException

Sets multiple client info properties from the provided Properties object.

Specified by:
  `setClientInfo` in interface `Connection`
Parameters:
  `properties` - The properties containing client info to set
Throws:
  `SQLClientInfoException` - If any property cannot be set

#### getClientInfo

    public String getClientInfo​(String name)
                         throws SQLException

Retrieves the value of the specified client info property. case-insensitive

Specified by:
  `getClientInfo` in interface `Connection`
Parameters:
  `name` - The name of the client info property to retrieve
Returns:
  The value of the specified client info property, or null if not found
Throws:
  `SQLException` - If a database access error occurs

#### getClientInfo

    public Properties getClientInfo()
                             throws SQLException

Retrieves all client and session properties as a Properties object. Keys are in lower case.

The returned Properties object contains default session configurations, user-defined session configurations, and client info properties.

Specified by:
  `getClientInfo` in interface `Connection`
Returns:
  A Properties object containing all client info properties
Throws:
  `SQLException` - If a database access error occurs

#### createArrayOf

    public Array createArrayOf​(String typeName,
                               Object[] elements)
                        throws SQLException

Specified by:
  `createArrayOf` in interface `Connection`
Throws:
  `SQLException`

#### createStruct

    public Struct createStruct​(String typeName,
                               Object[] attributes)
                        throws SQLException

Specified by:
  `createStruct` in interface `Connection`
Throws:
  `SQLException`

#### setSchema

    public void setSchema​(String schema)
                   throws SQLException

Specified by:
  `setSchema` in interface `Connection`
Throws:
  `SQLException`

#### getSchema

    public String getSchema()
                     throws SQLException

Specified by:
  `getSchema` in interface `Connection`
Throws:
  `SQLException`

#### abort

    public void abort​(Executor executor)
               throws SQLException

Specified by:
  `abort` in interface `Connection`
Throws:
  `SQLException`

#### setNetworkTimeout

    public void setNetworkTimeout​(Executor executor,
                                  int milliseconds)
                           throws SQLException

Specified by:
  `setNetworkTimeout` in interface `Connection`
Throws:
  `SQLException`

#### getNetworkTimeout

    public int getNetworkTimeout()
                          throws SQLException

Specified by:
  `getNetworkTimeout` in interface `Connection`
Throws:
  `SQLException`

#### unwrap

    public <T> T unwrap​(Class<T> iface)
                 throws SQLException

Specified by:
  `unwrap` in interface `Wrapper`
Throws:
  `SQLException`

#### isWrapperFor

    public boolean isWrapperFor​(Class<?> iface)
                         throws SQLException

Specified by:
  `isWrapperFor` in interface `Wrapper`
Throws:
  `SQLException`

#### closeStatement

    public void closeStatement​(IDatabricksStatement statement)

Description copied from interface: `IDatabricksConnectionInternal`
Closes a statement from the connection's active set.

Specified by:
  `closeStatement` in interface `IDatabricksConnectionInternal`
Parameters:
  `statement` - `IDatabricksStatement` to be closed

#### beginRequest

    public void beginRequest()

Specified by:
  `beginRequest` in interface `Connection`

#### endRequest

    public void endRequest()

Specified by:
  `endRequest` in interface `Connection`

#### setShardingKeyIfValid

    public boolean setShardingKeyIfValid​(ShardingKey shardingKey,
                                         ShardingKey superShardingKey,
                                         int timeout)
                                  throws DatabricksSQLFeatureNotImplementedException

Specified by:
  `setShardingKeyIfValid` in interface `Connection`
Throws:
  `DatabricksSQLFeatureNotImplementedException`

#### setShardingKeyIfValid

    public boolean setShardingKeyIfValid​(ShardingKey shardingKey,
                                         int timeout)
                                  throws DatabricksSQLFeatureNotImplementedException

Specified by:
  `setShardingKeyIfValid` in interface `Connection`
Throws:
  `DatabricksSQLFeatureNotImplementedException`

#### setShardingKey

    public void setShardingKey​(ShardingKey shardingKey,
                               ShardingKey superShardingKey)
                        throws DatabricksSQLFeatureNotImplementedException

Specified by:
  `setShardingKey` in interface `Connection`
Throws:
  `DatabricksSQLFeatureNotImplementedException`

#### setShardingKey

    public void setShardingKey​(ShardingKey shardingKey)
                        throws DatabricksSQLFeatureNotImplementedException

Specified by:
  `setShardingKey` in interface `Connection`
Throws:
  `DatabricksSQLFeatureNotImplementedException`

#### getConnection

    public Connection getConnection()

Description copied from interface: `IDatabricksConnectionInternal`
Returns the corresponding sql connection object

Specified by:
  `getConnection` in interface `IDatabricksConnectionInternal`

#### getConnectionContext

    public IDatabricksConnectionContext getConnectionContext()

Description copied from interface: `IDatabricksConnectionInternal`
Returns the connection context associated with the connection.

Specified by:
  `getConnectionContext` in interface `IDatabricksConnectionInternal`