Skip to content

Latest commit

 

History

History
173 lines (145 loc) · 6.99 KB

jdbc-limitations.md

File metadata and controls

173 lines (145 loc) · 6.99 KB
Raw

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. 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, Structand SQLXML types. As such this limits the methods available on a Connection. Of the JDBC API's Connection methods, 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, 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 aLogWriter. 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, 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, 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, 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, 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.