# JDBC Support and Limitations ## Schema, Catalog, and Tables The semantics of schema, catalogs, and tables often vary by database vendor. For the DocumentDB JDBC driver, the "schema" is a particular database on a DocumentDB cluster, and the "tables" are determined from the collections within that database through [schema discovery and generation](../schema/schema-discovery.md). There is no concept of "catalogs" and a user can only work within one schema (a database) at a time even though they might have access to others on that cluster. ## Interface Limitations ## Connection The driver does not support the `CallableStatement` interface, auto-generated keys, or transactions. It also does not support creating instances of the `Blob`, `Clob`, `Struct`and `SQLXML` types. As such this limits the methods available on a `Connection`. Of the JDBC API's `Connection` [methods](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html), the following are unsupported or supported with some limitations: ### Unsupported - `abort(Executor executor)` - `commit()` - `createBlob()` - `createClob()` - `createNClob()` - `createSQLXML()` - `createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)` - `createStruct(String typeName, Object[] attributes)` - `prepareCall(String sql)` - `prepareCall(String sql, int resultSetType, int resultSetConcurrency)` - `prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` - `prepareStatement(String sql, int autoGeneratedKeys)` - `prepareStatement(String sql, int[] columnIndexes)` - `prepareStatement(String sql, String[] columnNames)` - `releaseSavepoint(Savepoint savepoint)` - `rollback()` - `rollback(Savepoint savepoint)` - `setHoldability(int holdability)` - `setSavepoint(String name)` When called, these methods will throw a `SqlException`. ### Supported with limitations - `createStatement(int resultSetType, int resultSetConcurrency)` - This can only be called if the type is forward-only, and the currency is read-only which are already defaults. - `getCatalog()` - This always returns null. Driver does not have catalogs. - `prepareStatement(String sql, int resultSetType, int resultSetConcurrency)`- This can only be called if the type is forward-only, and the currency is read-only which are already defaults. - `setSchema(String schema)` - This is a no-op. Schema cannot be changed. - `setCatalog(String catalog)` - This is a no-op. Driver does not have catalogs. ## PooledConnection The driver supports connection pooling but not statement pooling. Of the JDBC API's `PooledConnection` [methods](https://docs.oracle.com/javase/8/docs/api/javax/sql/PooledConnection.html), the following are unsupported: - `addStatementEventListener(StatementEventListener listener)` - `removeStatementEventListener(StatementEventListener listener)` When called, these methods will have no effect and log a warning. ## DataSource The driver does not support setting a`LogWriter`. `getLogWriter()` will always return `null` while `setLogWriter(PrintWriter out)` will not throw any errors but is a no-op. ## Statement The driver is read-only and does not support batch processing, updates, or auto-generated keys. Of the JDBC API's `Statement` [methods](https://docs.oracle.com/javase/8/docs/api/java/sql/Statement.html), the following are unsupported: ### Unsupported - `addBatch(String sql)` - `clearBatch()` - `executeBatch()` - `executeLargeBatch()` - `executeLargeUpdate(String sql)` - `executeLargeUpdate(String sql, int autoGeneratedKeys)` - `executeLargeUpdate(String sql, int[] columnIndexes)` - `executeLargeUpdate(String sql, String[] columnNames)` - `executeUpdate(String sql)` - `executeUpdate(String sql, int autoGeneratedKeys)` - `executeUpdate(String sql, int[] columnIndexes)` - `executeUpdate(String sql, String[] columnNames)` - `setPoolable(boolean poolable)` - `setCursorName(String name)` When called, these methods will throw a `SqlException`. ### Supported with limitations - `execute(String sql)` - `execute(String sql, int autoGeneratedKeys)` - `execute(String sql, int[] columnIndexes)` - `execute(String sql, String[] columnNames)` These can only be used to execute query statements. The second parameter, if any, is ignored. All are equivalent to `executeQuery(String sql)`. ## PreparedStatement To support BI tools that may use the `PreparedStatement` interface in auto-generated queries, the driver supports the use of `PreparedStatement`. However, the use of parameters (values left as `?`) is not supported and repeated calls to execute a `PreparedStatement` do not have a reduced parsing or query time. This implementation has no significant differences with the `Statement` interface. Of the JDBC API's `PreparedStatement` [methods](https://docs.oracle.com/javase/8/docs/api/java/sql/PreparedStatement.html), the following are unsupported: - `addBatch()` - `clearParameters()` - `executeLargeUpdate()` - `executeUpdate()` - `getParameterMetaData()` - `setPoolable()` - any set parameter method such as `setArray(int parameterIndex, Array x)` When called, these methods will throw a `SqlException`. ## DatabaseMetaData Of the JDBC API's `DatabaseMetaData` [methods](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html), the following are unsupported: - `getBestRowIdentifier()` - `getClientInfoProperties()` - `getCrossReference()` - `getExportedKeys()` - `getFunctionColumns()` - `getFunctions()` - `getIndexInfo()` - `getProcedureColumns()` - `getPseudoColumns()` - `getSuperTables()` - `getSuperTypes()` - `getTablePrivileges` - `getTypeInfo()` - `getUDTs()` - `getVersionColumns()` When called, these methods will throw a `SqlException`. ## ResultSet Every `ResultSet` returned by the driver will have a read-only concurrency mode, a forward fetch direction, and a forward-only cursor. As such, this limits the methods available on a `ResultSet`. Of the JDBC API's `ResultSet` [methods](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html), the following are unsupported or supported with some limitations: #### Unsupported - `afterLast()` - `beforeFirst()` - `cancelRowUpdates()` - `deleteRow()` - `first()` - `insertRow()` - `last()` - `moveToCurrentRow()` - `moveToInsertRow()` - `previous()` - `refreshRow()` - `rowDeleted()` - `rowInserted()` - `rowUpdated()` - any get method for the data types `Ref,` `RowId`, `SQLXML` or `URL` such as `getSQLXML(String columnLabel)` - any update method for all data types such as `updateBlob(int columnLabel, Blob x)` When called, these methods will throw a `SqlException`. ### Supported with limitations These methods only accept certain inputs. When called with an invalid input, these will throw a `SqlException`. - `absolute(int row)` - This will only accept positive values that are greater or equal to the current row. - `relative(int rows)` - This only accepts positive values as the cursor only moves forward. - `setFetchDirection(int direction)` - This only accepts setting the direction to `FETCH_FORWARD` which would be a no-op since this is already the default direction.