Package org.springframework.test.context.jdbc

Annotation Interface Sql

@Target({TYPE,METHOD}) @Retention(RUNTIME) @Documented @Inherited @Repeatable(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. However, this does not apply to class-level declarations configured for the BEFORE_TEST_CLASS or AFTER_TEST_CLASS execution phase. Such declarations cannot be overridden, and the corresponding scripts and statements will be executed once per class in addition to any method-level scripts and statements.

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.

@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 will be inherited from an enclosing test class by default. See @NestedTestConfiguration for details. This annotation may also be used as a meta-annotation to create custom composed annotations with attribute overrides.

If you want to see which SQL scripts are being executed, set the org.springframework.test.context.jdbc logging category to DEBUG. If you want to see which SQL statements are being executed, set the org.springframework.jdbc.datasource.init logging category to DEBUG.

Use of this annotation requires the spring-jdbc and spring-tx modules as well as their transitive dependencies to be present on the classpath.

Since:
4.1
Author:
Sam Brannen, Andreas Ahlenstorf
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Sql.ExecutionPhase
    Enumeration of phases that dictate when SQL scripts are executed.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    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 Details

    • value

      @AliasFor("scripts") 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:
      Default:
      {}

    • scripts

      @AliasFor("value") 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 (for example, a path prefixed with classpath:, file:, http:, etc.) will be loaded using the specified resource protocol.

      As of Spring Framework 6.2, paths may contain property placeholders (${...}) that will be replaced by properties stored in the Environment of the test's ApplicationContext.

      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:
      Default:
      {}

    • statements

      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:
      Default:
      {}

    • executionPhase

      Sql.ExecutionPhase executionPhase
      When the SQL scripts and statements should be executed.

      Defaults to BEFORE_TEST_METHOD.

      Default:
      BEFORE_TEST_METHOD

    • config

      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