Dependency Info

See the Dependency Info page to add this project as a dependency to your project; if the use of this library is limited to unit testing only, then add the dependency to the test scope only. You may have to add the required Distribution Repository for resolution.

Also see the Project Dependencies for dependencies that come with this project, you may want to exclude some of them to avoid version conflicts if your project has some of those dependencies as well.

Basic Workflow

When unit testing a piece of JDBC code, the steps would be:

1. Configure and start an in-memory instance of Derby
2. Set up the tables and test data in the instance
3. Run your tests
4. Shut down the database and run cleanup

Hello World

A small sample test:

public class SimpleDerbyTest {
	
	private TemporaryFolder tempFolder = new TemporaryFolder();
	private EmbeddedDerbyResource embeddedDerbyResource =
		new EmbeddedDerbyResource(DerbyResourceConfig.buildDefault()
			.useDevNullErrorLogging(),
		tempFolder);
	
	@Rule
	public RuleChain derbyRuleChain = RuleChain.outerRule(tempFolder).around(embeddedDerbyResource);

	@Test
	public void test () throws SQLException {
		final String jdbcUrl = embeddedDerbyResource.getJdbcUrl();
		Connection connection = null;
		Statement stmt = null;
		ResultSet rs = null;

		try {
			connection = DriverManager.getConnection(jdbcUrl);
	
			// Check a value
			stmt = connection.createStatement();
			rs = stmt.executeQuery("SELECT 1 FROM SYSIBM.SYSDUMMY1");
	
			assertTrue(rs.next());
		} finally {
			// Close resources
		}
	}
}

The Derby instance is wrapped inside the EmbeddedDerbyResource instance, and it has convenience methods to access the runtime values from the instance (see EmbeddedDerbyResource Javadocs for more information on available methods). The instance can be configured using the DerbyResourceConfig instance, which provides a Fluent Interface to configure runtime parameters (see javadocs for API information). See the Configuration Options documentation to see available configurations.

Derby Instances

An Embedded Derby instance can be started and stopped using the EmbeddedDerbyResource#start() and EmbeddedDerbyResource#close() methods. Users are free to initialize and manage instances on their own (also read about Concurrency when attempting to run multiple concurrent instances of Derby).

If the user wants to control the instance and possibly share it across multiple test classes or want more control over the running instance.

private TemporaryFolder tempFolder = new TemporaryFolder();
private EmbeddedDerbyResource embeddedDerbyResource =
	new EmbeddedDerbyResource(DerbyResourceConfig.buildDefault(), tempFolder);

@ClassRule
public RuleChain derbyRuleChain = RuleChain.outerRule(tempFolder).around(embeddedDerbyResource);

EmbeddedDerbyResource state

The EmbeddedDerbyResource maintains an internal state which is set to active only between an invocation of #before() / #start() and #after() / #close(). Invoking methods to access the instance, including #getJdbcUrl(), #createConnection(), #backupLiveDatabase() while the database is not active will cause the resource to throw an IllegalStateException. Invoking #before() / #start() while the instance is active has no effect; similarly invoking #after() / #close() when the instance is not active has no effect.

The current active state of the resource can be checked using the #isActive() method.

Application Logging

Derby JUnit Helper uses Log4j2 API for the little bit of logging it sends. It does not have a default log configuration with the distribution, neither does it come with a runtime logger. Users are free to provide their own configuration and runtime logger as a dependency; or live with no logging and a 2 line Log4j warning on each JVM run.

Common Errors

A few common errors to look out for

java.sql.SQLException: No suitable driver found for jdbc:derby:...
	at java.sql.DriverManager.getConnection(DriverManager.java:596)
	at java.sql.DriverManager.getConnection(DriverManager.java:233)