Annotation Interface SqlPreflight

@Retention(RUNTIME) @Target({METHOD,TYPE}) @Repeatable(SqlPreflights.class) @Alpha public @interface SqlPreflight
Executes a "pre-flight" SQL statement on the same Handle, immediately before the annotated SQL Object method's main statement runs. The primary use case is setting a scoped/session variable before a query, for example a non-default Postgres trigram threshold: 
@SqlPreflight("set pg_trgm.word_similarity_threshold=0.4")
@SqlQuery("find-user")
@RegisterFieldMapper(User.class)
List<User> findUser(String search);

The preflight statement runs during the main statement's setup, on the same Handle, so it always shares the main statement's connection and transaction. In particular, if the method is annotated with @Transaction, the preflight runs inside that transaction regardless of the order in which the two annotations are declared. The method's arguments are bound to the preflight statement, respecting parameter binding annotations such as @Bind and @BindBean; arguments that the preflight SQL does not reference are ignored.

The annotation is repeatable; multiple preflight statements run in declaration order. It may be placed on a method or on the SQL Object type (type-level preflights apply to all methods, and run before any method-level preflights).

The value is always used as literal SQL; unlike @SqlQuery and @SqlUpdate, it is not resolved through the configured SqlLocator, so external .sql files have no effect on it.

Since:
3.54.0

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    Returns the literal SQL to execute before the main statement.

  • Element Details

    • value

      String value
      Returns the literal SQL to execute before the main statement.
      Returns:
      the preflight SQL string