Release Notes for Apache Derby

These notes describe the difference between Apache Derby release and the preceding release


The most up to date information about Derby releases can be found on the Derby download page.

Apache Derby is a pure Java relational database engine using standard SQL and JDBC as its APIs. More information about Derby can be found on the Apache web site. Derby functionality includes:

Java and JDBC versions supported:

New Features

This is a bug fix release. No new features were added.

Bug Fixes

The following issues are addressed by Derby release These issues are not addressed in the preceding release.

Issue IdDescription
DERBY-5951Missing method exception raised when using Clobs with territory based collation
DERBY-5937File handle is leaked when a Slave replication is shutdown with failover=true
DERBY-5925Document derby.log changes resulting from DERBY-5240
DERBY-5918CREATE TABLE AS SELECT doesn't work on tables with BOOLEAN columns
DERBY-5916java.lang.NullPointerException connecting to network server
DERBY-5912testIsValidImplemented fails for NetworkServer in some slow running machines/configurations
DERBY-5911WHERE condition getting pushed into sub-query with FETCH
DERBY-5910Document use of Connection.close() with try-with-resources
DERBY-5909The lang attribute in toc.html always says 'en-us'
DERBY-5906In the Reference Manual, sin() is used as the example for the sinh() function.
DERBY-5905Derby html documentation doesn't render properly and prints garbage on Internet Explorer
DERBY-5900Need to correct Reference Guide description of contents of SYS.SYSPERMS.OBJECTTYPE
DERBY-5898add ibm18 class to functionTests.harness
DERBY-5838By using syscs_set_database_property, you can set the database version to a garbage string which prevents you from booting the database.
DERBY-5830Make DoubleProperties.propertyNames() thread-safe
DERBY-5822Document the new SQL standard behavior of the SPACE_TABLE vti
DERBY-5805Database encryption topics in Reference Manual need more information
DERBY-5799add more info on when Derby chooses 32k page size for tables.
DERBY-5775Upgrade tests should print full IOException stack trace when it fails to access old versions
DERBY-5727Update POMs to deploy Maven artifacts to and use ASF parent POM
DERBY-5692intermittent test failure in storetests/
DERBY-5691Document that Write Caching must be disabled to avoid possible database corruption
DERBY-5681When a foreign key constraint on a table is dropped, the associated statistics row for the conglomerate is not removed
DERBY-5663Getting NPE when trying to set derby.language.logStatementText property to true inside a junit suite.
DERBY-5649make improvements to nstest so it's easier to run/analyze/debug
DERBY-5638intermittent test failure in test_05_ClobNegative when running full largedata._Suite; LobLimitsTestjava.sql.SQLException: Table/View 'BLOBTBL' already exists in Schema 'APP'.
DERBY-5633Add tests for state transition and behavior with Lock Timeout in XA Transaction (DERBY-5552 testing task)
DERBY-5624System can run out of stack space while processing DropOnCommit requests.
DERBY-5622Reduce the chance for hash collisions when checking bootPassword at boot time and when changing password.
DERBY-5617Improve process handling in SpawnedProcess
DERBY-5616demo/vtis/sql/demoFileVtis.sql needs to be adjusted: has moved
DERBY-5614NullPointerException with INSERT INTO [global temporary table] SELECT ... FROM [VTI]
DERBY-5609Prepare old test harness for running tests on Java 8
DERBY-5608BaseTestCase.readProcessOutput should read getInputStream() and getErrorStream() in separate threads
DERBY-5603EmbedConnection.clearLOBMapping() incorrectly clears lobFiles causing a ConcurrentModificationException
DERBY-5599readlocks.sql fails with extra locks.
DERBY-5598testStartWithPrintWriter(org.apache.derbyTesting.functionTests.tests.derbynet.DerbyNetNewServerTest)junit.framework.AssertionFailedError: Num of log item should add
DERBY-5586Remove the fo2html.xsl script from the docs repository and fix the docs and release builds so that they don't build monohtml versions of the Derby manuals.
DERBY-5584Select statement with subqueries with group by and count distinct statements returns wrong number of results
DERBY-5582Access denied (java.lang.RuntimePermission modifyThreadGroup) in IndexStatisticsDaemonImpl.schedule()
DERBY-5574encryption test in encryption nightly suite test fails with ERROR XBM0S: Unable to rename file error
DERBY-5567AlterTableTest#testDropColumn fails: drop view cannot be performed due to dependency
DERBY-5564Code does different things depending if derby.locks.deadlockTrace=true is set
DERBY-5562An read-only XA transaction that has a timeout never has the timer canceled when the transaction is complete
DERBY-5561Race conditions in LogicalConnection checking for a null physical connection
DERBY-5552Derby threads hanging when using ClientXADataSource and a deadlock or lock timeout occurs
DERBY-5547NSSecurityMechanismTest fixture testNetworkServerSecurityMechanism fails intermittentlyt
DERBY-5531Assert failure when inserting NULL into indexed column with territory-based collation
DERBY-5530SQLChar.getCollationKey NPE in index-stat-thread
DERBY-5527Documentation problem: 5 - Verifying the copy of the files
DERBY-5526on upgrade from 10.5 to 10.8.2 , getting ERROR XBM0A: The database directory 'C:\cygwin\home\debugfat\clientdb' exists. However, it does not contain the expected '' file.
DERBY-5517testReplication_Local_3_p1_StateNegativeTests failed with connection refused
DERBY-5509javadoc for NetServlet and NetworkServerControl are missing a few closing tags
DERBY-5508Improve backup/restore documentation visibility and content to encourage proper backups and restore procedures
DERBY-5467Copyright notice in the API documentation (generated by the Javadoc tool) is outdated
DERBY-5465Broken null checks in NsTest
DERBY-5456Problems running SecureServerTest and replication tests on Open JDK 7 for Mac OS X
DERBY-5454ERROR 40001 deadlock in nstest on select max(serialkey)
DERBY-544910.8 client with 10.5 server gives java.lang.ClassCastException: java.lang.Boolean incompatible with java.lang.Short in NetStatementRequest.buildFDODTA with CursorTest.testCursorParam()
DERBY-5440test failure in testBTreeForwardScan_fetchRows_resumeAfterWait_nonUnique_split( expected:<1> but was:<0>
DERBY-5427Unauthorized shutdown should not generate thread dump and javacore. AuthenticationTest dumps over 20 javacores with IBM JVM for normal user errors
DERBY-5425Updateable holdable ResultSet terminates early after 65638 updates
DERBY-5407When run across the network, dblook produces unusable DDL for VARCHAR FOR BIT DATA columns.
DERBY-5406Intermittent failures in CompressTableTest and TruncateTableTest
DERBY-5379testDERBY5120NumRowsInSydependsForTrigger - The number of values assigned is not the same as the number of specified or implied columns.
DERBY-5377AssertionFailedError in testCaseCS4595B_NonUniqueIndex in AccessTest
DERBY-5370The toSQL method of the org.apache.derby.vti.Restriction class does not output correct constants for VARCHAR, Timestamp, Date, Time, or CHAR FOR BIT DATA types
DERBY-5369Restricted Table Function support should pass NOT EQUAL restrictions to initScan
DERBY-5358SYSCS_COMPRESS_TABLE failed with conglomerate not found exception
DERBY-5305Convert store/updatelocks.sql to JUnit
DERBY-5272Stop building Eclipse plugins as Derby release artifacts
DERBY-5240Log Operating system information to derby.log on boot
DERBY-5096DisconnectException: "Connection was refused because the database DB was not found" when creating db for first time
DERBY-4631Wrong join column returned by right outer join with NATURAL or USING and territory-based collation
DERBY-4291Intermittent failure in 'store/updatelocks.sql' on Windows Vista
DERBY-4279Statement cache deadlock
DERBY-4229encryptionKeyLength connection attribute should be documented
DERBY-4201SecureServerTest AssertionFailedError: Timed out waiting for network server to start
DERBY-3823NullPointerException in stress.multi test
DERBY-3808Convert subquery.sql to junit
DERBY-3740BlobClob4BlobTest.testLockingWithLongRowBlob fails with .AssertionFailedError: FAIL - statement should timeout
DERBY-2687store/encryptDatabase.sql fails intermittently with ClassNotFoundException, Log Corrupted
DERBY-1913storetests/ fails intermittently
DERBY-1721DOCS - Remove duplicate information in Dev Guide re: Encryption


Compared with the previous release (, Derby release introduces the following new features and incompatibilities. These merit your special attention.

Note for DERBY-5564

Summary of Change

The SQL state of the error returned from a lock timeout when the property "derby.locks.deadlockTrace=true" is set will return 40XL1 rather than 40XL2.

Symptoms Seen by Applications Affected by Change

In the previous release, applications which set "derby.locks.deadlockTrace=true" would get error 40XL2 when a lock timeout was received. This was confusing as simply setting the system to return extra diagnostic information would change the SQL state of the error returned by the system for a lock timeout.

Incompatibilities with Previous Release

Applications which explicitly tested for SQL state error 40XL2 as a lock timeout will no longer get that error. 40XL1 will now always be returned for a lock timeout error whether lock diagnostics are enabled or not.

Rationale for Change

The previous behavior was not intended. Lock timeout should generate same SQL state whether diagnostics are enabled or not. Only the text of the error will change based on the requested diagnostic level.

Application Changes Required

If the application has been explicitly coded to take action when getting error 40XL2 and does not do the same action for 40XL1, then the application should be changed. This action is usually retry logic based on a lock timeout or deadlock.

Note for DERBY-4631

Summary of Change

Derby can pick incorrect join column value for a RIGHT OUTER JOIN with NATURAL/USING clause.

Symptoms Seen by Applications Affected by Change

In case of RIGHT OUTER JOIN with NATURAL/USING clause, Derby always picked the join column's value from the right table. This could lead to incorrect join column value depending on the data in the tables. The correct value should be determined by doing equivalent of COALESCE(leftTableValue, rightTableValue). This correct behavior has been implemented as a fix for DERBY-4631.

Incompatibilities with Previous Release

The data returned for join column value for a RIGHT OUTER JOIN with NATURAL/USING clause can now be different(and correct).

Build Environment

Derby release was built using the following environment:

Verifying Releases

It is essential that you verify the integrity of the downloaded files using the PGP and MD5 signatures. MD5 verification ensures the file was not corrupted during the download process. PGP verification ensures that the file came from a certain person.

The PGP signatures can be verified using PGP or GPG. First download the Apache Derby KEYS as well as the asc signature file for the particular distribution. It is important that you get these files from the ultimate trusted source - the main ASF distribution site, rather than from a mirror. Then verify the signatures using ...

% pgpk -a KEYS
% pgpv db-derby-X.Y.tar.gz.asc


% pgp -ka KEYS
% pgp db-derby-X.Y.tar.gz.asc


% gpg --import KEYS
% gpg --verify db-derby-X.Y.tar.gz.asc

To verify the MD5 signature on the files, you need to use a program called md5 or md5sum, which is included in many unix distributions. It is also available as part of GNU Textutils. Windows users can get binary md5 programs from here, here, or here.

We strongly recommend that you verify your downloads with both PGP and MD5.