JDBC reference

This section provides reference information about Derby's implementation of the Java Database Connectivity (JDBC) API and documents the way it conforms to the JDBC APIs.

Derby comes with a built-in JDBC driver. That makes the JDBC API the only API for working with Derby databases. The driver is a native-protocol fully Java technology-enabled driver (Type 4 of the types described under "JDBC Architecture" in http://www.oracle.com/technetwork/java/overview-141217.html).

See the Derby Developer's Guide for task-oriented instructions on working with the driver.

This JDBC driver implements the standard JDBC interfaces. When invoked from an application running in the same Java Virtual Machine (JVM) as Derby, the JDBC driver supports connections to a Derby database in embedded mode. No network transport is required to access the database. In client/server mode, the client application dispatches JDBC requests to the JDBC server over a network; the server, in turn, which runs in the same JVM as Derby, sends requests to Derby through the embedded JDBC driver.

For information on the DataSource implementations provided by Derby, see DataSource classes.

The Derby JDBC implementation provides access to Derby databases and supplies all the required JDBC interfaces. Unimplemented aspects of the JDBC driver return an SQLException with a message stating "Feature not implemented" and an SQLState of XJZZZ. These unimplemented parts are for features not supported by Derby.

• java.sql.Driver interface
  The class that loads Derby's local JDBC driver is the class org.apache.derby.jdbc.EmbeddedDriver. The class that loads Derby's network client driver is the class org.apache.derby.jdbc.ClientDriver.
• java.sql.DriverManager.getConnection method
  A Java application that uses the JDBC API establishes a connection to a database by obtaining a Connection object. The standard way to obtain a Connection object is to call the method DriverManager.getConnection, which takes a String that contains a database connection URL.
• java.sql.Connection interface
  A Derby Connection object is not garbage-collected until all other JDBC objects created from that connection are closed or are themselves garbage-collected.
• java.sql.DatabaseMetaData interface
  Derby implements the java.sql.DatabaseMetaData interface.
• java.sql.Statement interface
  Derby does not implement the setEscapeProcessing method of java.sql.Statement. In addition, the cancel method raises a "Feature not supported" exception.
• java.sql.CallableStatement interface
  Derby supports all methods of CallableStatement except setBlob, getBlob, setClob, and getClob.
• java.sql.PreparedStatement interface
  Derby provides all the required JDBC type conversions and additionally allows use of the individual setXXX methods for each type as if a setObject(Value, JDBCTypeCode) invocation were made.
• java.sql.ResultSet interface
  A positioned update or delete issued against a cursor being accessed through a ResultSet object modifies or deletes the current row of the ResultSet object.
• java.sql.ResultSetMetaData interface
  Derby does not track the source or updatability of columns in ResultSets, and so always returns the constants shown for the methods listed in the following table.
• java.sql.SQLException class
  Derby supplies values for the getMessage, getSQLState, and getErrorCode calls of SQLException.
• java.sql.SQLWarning class
  Derby can generate a warning in certain circumstances. A warning is generated if, for example, you try to connect to a database with the create attribute set to true if the database already exists.
• java.sql.SQLXML interface
  The java.sql.SQLXML interface is the mapping for the SQL XML data type. However, Derby defines the XML data type and operators only in the SQL layer. There is no JDBC-side support for the XML data type and operators.
• java.sql.SQLType interface
  JDBC 4.2 introduced a data type identifier, java.sql.SQLType, to help databases describe data types which do not appear in the ANSI/ISO SQL Standard. Databases which provide non-standard types can provide their own implementations of SQLType.
• java.sql.Savepoint interface
  The Savepoint interface contains methods to set, release, or roll back a transaction to designated savepoints. Once a savepoint has been set, the transaction can be rolled back to that savepoint without affecting preceding work.
• Mapping of java.sql.Types to SQL types
  In Derby, the java.sql.Types are mapped to SQL data types.
• JDBC escape syntax
  JDBC provides a way of smoothing out some of the differences in the ways different DBMS vendors implement SQL. This is called escape syntax.