org.springframework.test.context.jdbc

Annotation Type Sql

@Documented
 @Inherited
 @Retention(value=RUNTIME)
 @Target(value={TYPE,METHOD})
 @Repeatable(value=SqlGroup.class)
public @interface Sql

@Sql is used to annotate a test class or test method to configure SQL scripts to be executed against a given database during integration tests.

Method-level declarations override class-level declarations.

Script execution is performed by the SqlScriptsTestExecutionListener, which is enabled by default.

The configuration options provided by this annotation and @SqlConfig are equivalent to those supported by ScriptUtils and ResourceDatabasePopulator but are a superset of those provided by the <jdbc:initialize-database/> XML namespace element. Consult the javadocs of individual attributes in this annotation and @SqlConfig for details.

Beginning with Java 8, @Sql can be used as a repeatable annotation. Otherwise, @SqlGroup can be used as an explicit container for declaring multiple instances of @Sql.

This annotation may be used as a meta-annotation to create custom composed annotations; however, attribute overrides are not currently supported for repeatable annotations that are used as meta-annotations.

Since:

4.1

Author:

Sam Brannen

See Also:

SqlConfig, SqlGroup, SqlScriptsTestExecutionListener, Transactional, TransactionalTestExecutionListener, ResourceDatabasePopulator, ScriptUtils

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
SqlConfig	config Local configuration for the SQL scripts declared within this @Sql annotation.
Sql.ExecutionPhase	executionPhase When the SQL scripts should be executed.
String[]	scripts The paths to the SQL scripts to execute.
String[]	value Alias for scripts().

Element Detail

value

public abstract String[] value

Alias for scripts().

This attribute may not be used in conjunction with scripts(), but it may be used instead of scripts().

Default:

{}

scripts

public abstract String[] scripts

The paths to the SQL scripts to execute.

This attribute may not be used in conjunction with value(), but it may be used instead of value().

Path Resource Semantics

Each path will be interpreted as a Spring Resource. A plain path — for example, "schema.sql" — will be treated as a classpath resource that is relative to the package in which the test class is defined. A path starting with a slash will be treated as an absolute classpath resource, for example: "/org/example/schema.sql". A path which references a URL (e.g., a path prefixed with classpath:, file:, http:, etc.) will be loaded using the specified resource protocol.

Default Script Detection

If no SQL scripts are specified, an attempt will be made to detect a default script depending on where this annotation is declared. If a default cannot be detected, an IllegalStateException will be thrown.

• class-level declaration: if the annotated test class is com.example.MyTest, the corresponding default script is "classpath:com/example/MyTest.sql".
• method-level declaration: if the annotated test method is named testMethod() and is defined in the class com.example.MyTest, the corresponding default script is "classpath:com/example/MyTest.testMethod.sql".

Default:

{}

executionPhase

public abstract Sql.ExecutionPhase executionPhase

When the SQL scripts should be executed.

Defaults to BEFORE_TEST_METHOD.

Default:

org.springframework.test.context.jdbc.Sql.ExecutionPhase.BEFORE_TEST_METHOD

config

public abstract SqlConfig config

Local configuration for the SQL scripts declared within this @Sql annotation.

See the class-level javadocs for SqlConfig for explanations of local vs. global configuration, inheritance, overrides, etc.

Defaults to an empty @SqlConfig instance.

Default:

@org.springframework.test.context.jdbc.SqlConfig