12.8 Embedded database support

The org.springframework.jdbc.datasource.embedded package provides support for embedded Java database engines. Support for HSQL, H2, and Derby is provided natively. There is also an extensible API for plugging in new embedded database types and DataSource implementations.

12.8.1 Why use an embedded database?

An embedded database is useful during the development phase of a project due to its lightweight nature. Ease of configuration, quick startup time, testability, and the ability to rapidly evolve SQL during development are just some of the benefits of using an embedded database.

12.8.2 Creating an embedded database instance using Spring XML

When you wish to expose an embedded database instance as a bean in a Spring ApplicationContext, use the embedded-database tag in the spring-jdbc namespace:

    <jdbc:embedded-database id="dataSource">
        <jdbc:script location="classpath:schema.sql"/>
        <jdbc:script location="classpath:test-data.sql"/>
    </jdbc:embedded-database>

The configuration above creates an embedded HSQL database populated with SQL from schema.sql and testdata.sql resources in the classpath. The database instance is made available to the Spring container as a bean of type javax.sql.DataSource. This bean can then be injected into data access objects as needed.

12.8.3 Creating an embedded database instance programatically

The EmbeddedDatabaseBuilder class provides a fluent API for constructing an embedded database programmatically. Use this when you need to create an embedded database instance in a standalone environment, such as a data access object unit test:

    EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
    EmbeddedDatabase db = builder.type(H2).script("schema.sql").script("test-data.sql").build();
    // do stuff against the db (EmbeddedDatabase extends javax.sql.DataSource)
    db.shutdown()

12.8.4 Extending the embedded database support

Spring Jdbc's embedded database support can be extended in two ways:

  1. Implement EmbeddedDatabaseConfigurer to support a new embedded database type, such as Apache Derby.

  2. Implement DataSourceFactory to support a new DataSource implementation, such as a connection pool, to manage embedded database connections.

You are encouraged to contribute back extensions to the Spring community at jira.springframework.org.

12.8.5 Using HSQL

Support for HSQL 1.0.0 to 2.0.0 is provided. HSQL is the default database embedded database that will be used if no type is specified explicitly. To specify HSQL explicitly, set the type attribute of the embedded-database tag to HSQL. If using the builder API, call the type(EmbeddedDatabaseType) method with EmbeddedDatabaseType.HSQL.

12.8.6 Using H2

Support for H2 1.8.0 to 2.0.0 is provided. To enable H2, set the type attribute of the embedded-database tag to H2. If using the builder API, call the type(EmbeddedDatabaseType) method with EmbeddedDatabaseType.H2.

12.8.7 Using Derby

Support for Apache Derby 10.5.1.1 to 10.6.0 is provided. To enable Derby, set the type attribute of the embedded-database tag to Derby. If using the builder API, call the type(EmbeddedDatabaseType) method with EmbeddedDatabaseType.Derby.

12.8.8 Unit testing data access logic with an EmbeddedDatabase

Embedded databases provide a lightweight way to test data access code. A basic data access unit test template that uses an embedded database is provided below:

public class DataAccessUnitTestTemplate {
    private EmbeddedDatabase db;
    
    @Before
    public void setUp() {
        // creates a HSQL in-memory db populated from classpath:schema.sql and classpath:test-data.sql
        db = EmbeddedDatabaseBuilder.buildDefault();		
    }
	
    @Test
    public void testDataAccess() {
        JdbcTemplate template = new JdbcTemplate(db);
        template.query(...);
    }
	
    @After
    public void tearDown() {
        db.shutdown();
    }
}