Package org.springframework.jdbc.datasource.embedded

# Class EmbeddedDatabaseBuilder

java.lang.Object
org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseBuilder

public class EmbeddedDatabaseBuilder extends Object
A builder that provides a convenient API for constructing an embedded database.

### Usage Example

     EmbeddedDatabase db = new EmbeddedDatabaseBuilder()
         .generateUniqueName(true)
         .setType(H2)
         .setScriptEncoding("UTF-8")
         .ignoreFailedDrops(true)
         .addScript("schema.sql")
         .addScripts("user_data.sql", "country_data.sql")
         .build();

     // perform actions against the db (EmbeddedDatabase extends javax.sql.DataSource)

     db.shutdown();

Since:
  3.0
Author:
  Keith Donald, Juergen Hoeller, Dave Syer, Sam Brannen
See Also:
  - `ScriptUtils`
  - `ResourceDatabasePopulator`
  - `DatabasePopulatorUtils`

## Constructor Summary

Constructors
Constructor
Description
`EmbeddedDatabaseBuilder()`
Create a new embedded database builder with a `DefaultResourceLoader`.
`EmbeddedDatabaseBuilder(org.springframework.core.io.ResourceLoader resourceLoader)`
Create a new embedded database builder with the given `ResourceLoader`.

## Method Summary

Modifier and Type
Method
Description
`EmbeddedDatabaseBuilder`
`addDefaultScripts()`
Add default SQL scripts to execute to populate the database.
`EmbeddedDatabaseBuilder`
`addScript(String script)`
Add an SQL script to execute to initialize or populate the database.
`EmbeddedDatabaseBuilder`
`addScripts(String... scripts)`
Add multiple SQL scripts to execute to initialize or populate the database.
`EmbeddedDatabase`
`build()`
Build the embedded database.
`EmbeddedDatabaseBuilder`
`continueOnError(boolean flag)`
Specify that all failures which occur while executing SQL scripts should be logged but should not cause a failure.
`EmbeddedDatabaseBuilder`
`generateUniqueName(boolean flag)`
Specify whether a unique ID should be generated and used as the database name.
`EmbeddedDatabaseBuilder`
`ignoreFailedDrops(boolean flag)`
Specify that a failed SQL `DROP` statement within an executed script can be ignored.
`EmbeddedDatabaseBuilder`
`setBlockCommentEndDelimiter(String blockCommentEndDelimiter)`
Specify the end delimiter for block comments in all SQL scripts.
`EmbeddedDatabaseBuilder`
`setBlockCommentStartDelimiter(String blockCommentStartDelimiter)`
Specify the start delimiter for block comments in all SQL scripts.
`EmbeddedDatabaseBuilder`
`setCommentPrefix(String commentPrefix)`
Specify the single-line comment prefix used in all SQL scripts.
`EmbeddedDatabaseBuilder`
`setCommentPrefixes(String... commentPrefixes)`
Specify the prefixes that identify single-line comments within all SQL scripts.
`EmbeddedDatabaseBuilder`
`setDatabaseConfigurer(EmbeddedDatabaseConfigurer configurer)`
Set the configurer to use to configure the embedded database, as an alternative to `setType(org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType)`.
`EmbeddedDatabaseBuilder`
`setDataSourceFactory(DataSourceFactory dataSourceFactory)`
Set the factory to use to create the `DataSource` instance that connects to the embedded database.
`EmbeddedDatabaseBuilder`
`setName(String databaseName)`
Set the name of the embedded database.
`EmbeddedDatabaseBuilder`
`setScriptEncoding(String scriptEncoding)`
Specify the character encoding used in all SQL scripts, if different from the platform encoding.
`EmbeddedDatabaseBuilder`
`setSeparator(String separator)`
Specify the statement separator used in all SQL scripts, if a custom one.
`EmbeddedDatabaseBuilder`
`setType(EmbeddedDatabaseType databaseType)`
Set the type of embedded database.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### EmbeddedDatabaseBuilder

public EmbeddedDatabaseBuilder()
Create a new embedded database builder with a `DefaultResourceLoader`.

### EmbeddedDatabaseBuilder

public EmbeddedDatabaseBuilder(org.springframework.core.io.ResourceLoader resourceLoader)
Create a new embedded database builder with the given `ResourceLoader`.

Parameters:
  `resourceLoader` - the `ResourceLoader` to delegate to

## Method Details

### generateUniqueName

public EmbeddedDatabaseBuilder generateUniqueName(boolean flag)
Specify whether a unique ID should be generated and used as the database name.

If the configuration for this builder is reused across multiple application contexts within a single JVM, this flag should be enabled (i.e., set to `true`) in order to ensure that each application context gets its own embedded database.

Enabling this flag overrides any explicit name set via `setName(java.lang.String)`.

Parameters:
  `flag` - `true` if a unique database name should be generated
Returns:
  `this`, to facilitate method chaining
Since:
  4.2
See Also:
  - `setName(java.lang.String)`

### setName

public EmbeddedDatabaseBuilder setName(String databaseName)
Set the name of the embedded database.

Defaults to `EmbeddedDatabaseFactory.DEFAULT_DATABASE_NAME` if not called.

Will be overridden if the `generateUniqueName` flag has been set to `true`.

Parameters:
  `databaseName` - the name of the embedded database to build
Returns:
  `this`, to facilitate method chaining
See Also:
  - `generateUniqueName(boolean)`

### setType

public EmbeddedDatabaseBuilder setType(EmbeddedDatabaseType databaseType)
Set the type of embedded database. Consider using `setDatabaseConfigurer(org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseConfigurer)` if customization of the connections properties is necessary.

Defaults to HSQL if not called.

Parameters:
  `databaseType` - the type of embedded database to build
Returns:
  `this`, to facilitate method chaining

### setDatabaseConfigurer

public EmbeddedDatabaseBuilder setDatabaseConfigurer(EmbeddedDatabaseConfigurer configurer)
Set the configurer to use to configure the embedded database, as an alternative to `setType(org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType)`.

Parameters:
  `configurer` - the configurer of the embedded database
Returns:
  `this`, to facilitate method chaining
Since:
  6.2
See Also:
  - `EmbeddedDatabaseConfigurers`

### setDataSourceFactory

public EmbeddedDatabaseBuilder setDataSourceFactory(DataSourceFactory dataSourceFactory)
Set the factory to use to create the `DataSource` instance that connects to the embedded database.

Defaults to `SimpleDriverDataSourceFactory` but can be overridden, for example to introduce connection pooling.

Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### addDefaultScripts

public EmbeddedDatabaseBuilder addDefaultScripts()
Add default SQL scripts to execute to populate the database.

The default scripts are `"schema.sql"` to create the database schema and `"data.sql"` to populate the database with data.

Returns:
  `this`, to facilitate method chaining

### addScript

public EmbeddedDatabaseBuilder addScript(String script)
Add an SQL script to execute to initialize or populate the database.

Parameters:
  `script` - the script to execute
Returns:
  `this`, to facilitate method chaining

### addScripts

public EmbeddedDatabaseBuilder addScripts(String... scripts)
Add multiple SQL scripts to execute to initialize or populate the database.

Parameters:
  `scripts` - the scripts to execute
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### setScriptEncoding

public EmbeddedDatabaseBuilder setScriptEncoding(String scriptEncoding)
Specify the character encoding used in all SQL scripts, if different from the platform encoding.

Parameters:
  `scriptEncoding` - the encoding used in scripts
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### setSeparator

public EmbeddedDatabaseBuilder setSeparator(String separator)
Specify the statement separator used in all SQL scripts, if a custom one.

Defaults to `";"` if not specified and falls back to `"\n"` as a last resort; may be set to `ScriptUtils.EOF_STATEMENT_SEPARATOR` to signal that each script contains a single statement without a separator.

Parameters:
  `separator` - the statement separator
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### setCommentPrefix

public EmbeddedDatabaseBuilder setCommentPrefix(String commentPrefix)
Specify the single-line comment prefix used in all SQL scripts.

Defaults to `"--"`.

Parameters:
  `commentPrefix` - the prefix for single-line comments
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3
See Also:
  - `setCommentPrefixes(String...)`

### setCommentPrefixes

public EmbeddedDatabaseBuilder setCommentPrefixes(String... commentPrefixes)
Specify the prefixes that identify single-line comments within all SQL scripts.

Defaults to `["--"]`.

Parameters:
  `commentPrefixes` - the prefixes for single-line comments
Returns:
  `this`, to facilitate method chaining
Since:
  5.2

### setBlockCommentStartDelimiter

public EmbeddedDatabaseBuilder setBlockCommentStartDelimiter(String blockCommentStartDelimiter)
Specify the start delimiter for block comments in all SQL scripts.

Defaults to `"/*"`.

Parameters:
  `blockCommentStartDelimiter` - the start delimiter for block comments
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3
See Also:
  - `setBlockCommentEndDelimiter(java.lang.String)`

### setBlockCommentEndDelimiter

public EmbeddedDatabaseBuilder setBlockCommentEndDelimiter(String blockCommentEndDelimiter)
Specify the end delimiter for block comments in all SQL scripts.

Defaults to `"*/"`.

Parameters:
  `blockCommentEndDelimiter` - the end delimiter for block comments
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3
See Also:
  - `setBlockCommentStartDelimiter(java.lang.String)`

### continueOnError

public EmbeddedDatabaseBuilder continueOnError(boolean flag)
Specify that all failures which occur while executing SQL scripts should be logged but should not cause a failure.

Defaults to `false`.

Parameters:
  `flag` - `true` if script execution should continue on error
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### ignoreFailedDrops

public EmbeddedDatabaseBuilder ignoreFailedDrops(boolean flag)
Specify that a failed SQL `DROP` statement within an executed script can be ignored.

This is useful for a database whose SQL dialect does not support an `IF EXISTS` clause in a `DROP` statement.

The default is `false` so that `building` will fail fast if a script starts with a `DROP` statement.

Parameters:
  `flag` - `true` if failed drop statements should be ignored
Returns:
  `this`, to facilitate method chaining
Since:
  4.0.3

### build

public EmbeddedDatabase build()
Build the embedded database.

Returns:
  the embedded database