org.springframework.test.context.jdbc

Annotation Type Sql

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

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

Method-level declarations override class-level declarations by default, but this behavior can be configured via @SqlMergeMode.

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 with attribute overrides.

As of Spring Framework 5.3, this annotation will be inherited from an enclosing test class by default. See @NestedTestConfiguration for details.

Since:

4.1

Author:

Sam Brannen

See Also:

SqlConfig, SqlMergeMode, 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 and statements declared within this @Sql annotation.
Sql.ExecutionPhase	executionPhase When the SQL scripts and statements should be executed.
String[]	scripts The paths to the SQL scripts to execute.
String[]	statements Inlined SQL statements to execute.
String[]	value Alias for scripts().

Element Detail

value

@AliasFor(value="scripts")
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().

See Also:

scripts(), statements()

Default:

{}

scripts

@AliasFor(value="value")
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(). Similarly, this attribute may be used in conjunction with or instead of statements().

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 or statements() 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".

See Also:

value(), statements()

Default:

{}

statements

public abstract String[] statements

Inlined SQL statements to execute.

This attribute may be used in conjunction with or instead of scripts().

Ordering

Statements declared via this attribute will be executed after statements loaded from resource scripts(). If you wish to have inlined statements executed before scripts, simply declare multiple instances of @Sql on the same class or method.

Since:

4.2

See Also:

scripts()

Default:

{}

executionPhase

public abstract Sql.ExecutionPhase executionPhase

When the SQL scripts and statements 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 and statements 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