Release Notes for Apache Derby 10.8.1.2

Summary of Change

In Derby 10.7.1.1, update triggers with REFERENCING clauses can corrupt data. Users are urged to upgrade to the next release in the 10.7 family or to 10.8.

Symptoms Seen by Applications Affected by Change

In Derby 10.7.1.1, UPDATE triggers which use the REFERENCING clause can be confused about which columns to pass to their triggered actions. This can silently corrupt data manipulated by the triggered actions.

Incompatibilities with Previous Release

Derby 10.7.1.1 is the only release whose triggers corrupt data this way. Upgrading to a later 10.7 release or to 10.8 will recompile these triggers correctly. Applications should check for data corruption if they used 10.7.1.1 to create UPDATE triggers with the REFERENCING clause.

Rationale for Change

This change was made in order to fix a data corruption problem caused by UPDATE triggers with REFERENCING clauses.

Summary of Change

The JDBC-level conversion from BOOLEAN to CHAR has changed.

Symptoms Seen by Applications Affected by Change

In previous releases of Derby, when using PreparedStatement.setObject() or PreparedStatement.setBoolean() to initialize a character type parameter (CHAR, VARCHAR, etc.) with a boolean value, the parameter would be set to the value "1" or "0" for true or false, respectively.

Incompatibilities with Previous Release

In this release, PreparedStatement.setObject() and PreparedStatement.setBoolean() will convert the boolean values true and false to the strings "true" and "false", respectively, if the type of the parameter is one of the character types.

Rationale for Change

The previous behavior caused failures in a JDBC compliance test after Derby's meta-data started reporting that the BOOLEAN data type was supported in version 10.7.1.1.

Application Changes Required

If the application expects the parameter to be set to "1" or "0" instead of "true" or "false", it must be recoded to explicitly set the parameter to an integer value.

For example, if an application uses setBoolean() to set a character type parameter, it could be changed from

ps.setBoolean(col, b);

to

ps.setInt(col, b ? 1 : 0);

in order to preserve the old behavior.

Summary of Change

Interrupt resilience may degrade the performance of writes on some platforms.

Symptoms Seen by Applications Affected by Change

In Derby 10.8, INSERTs and UPDATEs may run slower on platforms which do not support write synchronization. Affected platforms include JDK 1.4.0 and JDK 1.4.1 (on all operating systems) and Java 5 (on Mac OSX and BSD variants).

Incompatibilities with Previous Release

On some platforms, INSERTs and UPDATEs may run slower than they did in previous Derby releases. Changes needed for interrupt resilience may cause extra io calls on platforms which do not support the "rws"/"rwd" modes in the constructor for RandomAccessFile(File,String)

Rationale for Change

Derby's log flushing logic was changed to prevent Thread interrupts from crashing the engine.

Application Changes Required

Upgrade the JVM to JDK 6 or higher if your application suffers slower INSERTs/UPDATEs after upgrading to Derby 10.8.

Summary of Change

Index cardinality statistics are updated automatically.

Symptoms Seen by Applications Affected by Change

During query compilation, Derby now checks if the index cardinality statistics for the tables involved in the query are out of date. If the statistics are outdated, the query compiler will schedule a job that updates them in a separate thread. The thread that updates the statistics in the background may affect the performance of the user threads.

Incompatibilities with Previous Release

This release of Derby may cause more threads to be running than previous releases did. These threads may use resources also needed by the user threads (for example, disk bandwidth, CPU or locks on system tables) and thereby interfere with the execution in the user threads.

Rationale for Change

Derby's optimizer will often choose query execution plans that yield bad performance if the index cardinality statistics are out of date.

Application Changes Required

If the automatic updating of index cardinality statistics causes problems, the application can disable it by setting the database property derby.storage.indexStats.auto=false.

To diagnose problems with automatic updating of index statistics, the application may set the database property derby.storage.indexStats.log=true. When this property is set, the thread that updates the statistics will write messages to the Derby system log (derby.log) every time it performs a task.

Summary of Change

Diagnostics for system crashes and session errors have been expanded.

Symptoms Seen by Applications Affected by Change

After a severe error (system crash or session error), the Derby error log will snapshot stack traces for all threads. On IBM JVMs these errors will produce a javacore file too.

To obtain thread dumps and diagnostics for less severe errors, adjust the derby.stream.error.extendedDiagSeverityLevel property as described in the Setting system-wide properties section of the Derby Developer's Guide. Please consult the Derby documentation for explanations of error severities and the other possible settings of extendedDiagSeverityLevel.

For example, to obtain this extra information while diagnosing deadlocks, set derby.stream.error.extendedDiagSeverityLevel=30000. Then deadlocks will dump thread stacks into the Derby error log.

Incompatibilities with Previous Release

None.

Rationale for Change

This change gives DBAs and tech support engineers more information to help them diagnose errors and crashes.

Application Changes Required

No application changes are required. To disable this feature, simply set the derby.stream.error.extendedDiagSeverityLevel property to the value 50001.

Summary of Change

JDBC metadata reports longer precision and scale for Timestamps.

Symptoms Seen by Applications Affected by Change

Previously, JDBC metadata calls reported that Derby Timestamps had precision 26 and scale 6. Now the precision of Timestamps is 29 and the scale is 9. The following metadata were corrected:

• DatabaseMetaData.getTypeInfo() - The PRECISION and MINIMUM_SCALE fields were wrong.
• DatabaseMetaData.getColumns() - The COLUMN_SIZE and DECIMAL_DIGITS fields were wrong.
• DatabaseMetaData.getProcedureColumns() - The PRECISION and SCALE fields were wrong.
• DatabaseMetaData.getFunctionColumns() - The PRECISION and SCALE fields were wrong.
• ResultSetMetaData - Wrong results came back from the getColumnDisplaySize(), getPrecision(), and getScale() methods.
• ParameterMetaData - Wrong results came back from the getPrecision() and getScale() methods.

Incompatibilities with Previous Release

Applications which rely on JDBC metadata to determine the length of Timestamps will now display longer Timestamps.

Rationale for Change

The metadata was changed to reflect the actual precision and scale of Derby Timestamps, which are simply instances of java.sql.Timestamp.

Application Changes Required

Applications, which consulted JDBC metadata in order to determine the length of Timestamps, should be tested (and if necessary recoded) to verify that they correctly handle the longer lengths.

Summary of Change

Engine shutdown now unregisters the embedded JDBC driver.

Symptoms Seen by Applications Affected by Change

In release 10.1, orderly engine shutdown unregistered the embedded JDBC driver, allowing the JVM to garbage-collect the Derby classes. Later releases (10.2 through 10.7) did not unregister the driver. 10.8 revives the 10.1 behavior. In 10.8, orderly engine shutdown unregisters the embedded JDBC driver.

After the embedded driver has been unregistered, it must be re-registered in order to obtain a new Connection to Derby. Re-registration occurs when the application invokes the following statement:

Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();

It is also possible for an application to request orderly shutdown without unregistering the embedded driver. After such a shutdown it is not necessary to re-register the embedded driver. To request this kind of shutdown, the application needs to add deregister=false to the end of the shutdown URL. For more information on this feature, please see the section on the deregister attribute in the Derby Reference Manual.

Incompatibilities with Previous Release

None.

Rationale for Change

The 10.1 behavior has been revived so that the JVM can garbage-collect the Derby classes after orderly engine shutdown.

Application Changes Required

Applications no longer need to call DriverManager.deregister(driver) in order to enable garbage-collection of the Derby classes after orderly engine shutdown.

Summary of Change

The requirements for XML operators have changed.

Symptoms Seen by Applications Affected by Change

After upgrading to Derby 10.8, applications may fail if they use the XMLPARSE, XMLSERIALIZE, XMLQUERY, and XMLEXISTS operators. Using those operators may raise the following error message:

ERROR XML00: Failed to locate 'XPath 3.0' API or implementation classes.  XML operations are not permitted unless these classes are in your classpath.

This happens if the classpath doesn't include the DOM Level 3 XPath interfaces or an implementation of those interfaces.

Incompatibilities with Previous Release

On Java 5 and earlier JVMs, the XMLPARSE, XMLSERIALIZE, XMLQUERY, and XMLEXISTS operators may fail as described above.

Rationale for Change

Previous releases of Derby required a recent version of Apache Xalan-Java in order to support the XML operators. Since not all platforms include Apache Xalan-Java, and some platforms contain a modified version with a different interface, these operators didn't work out of the box on many platforms.

In this release, the XML operators access the platform's XML libraries via the javax.xml and org.w3c.dom interfaces instead of accessing the Xalan implementation classes directly. This change makes the XML operators work out of the box on most Java SE 6 or later platforms, but may break the functionality on older platforms that don't contain all the required interfaces.

Application Changes Required

In environments affected by this change, the XML operators can be fixed by upgrading the JVM (IBM's versions 1.5.0 and 1.6.0 and Oracle's version 1.6.0 are known to work) or by installing a recent version of Apache Xalan-Java.

Installation of Xalan-Java may require the Endorsed Standards Override Mechanism. This is described in the "XML data types and operators" section of the Derby Developer's Guide.