Translations

Users can read about MyBatis-Spring-Boot-Starter in the following translations:

• English
• 简体中文

What is MyBatis-Spring-Boot-Starter?

The MyBatis-Spring-Boot-Starter help you build quickly MyBatis applications on top of the Spring Boot.

By using this module you will achieve:

• Build standalone applications
• Reduce the boilerplate to almost zero
• Less XML configuration

Requirements

The MyBatis-Spring-Boot-Starter requires following versions:

Installation

To use the MyBatis-Spring-Boot-Starter module, you just need to include the mybatis-spring-boot-autoconfigure.jar file and its dependencies(mybatis.jar, mybatis-spring.jar and etc …) in the classpath.

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

dependencies {
  implementation("org.mybatis.spring.boot:mybatis-spring-boot-starter:3.0.2")
}

Quick Setup

As you may already know, to use MyBatis with Spring you need at least an SqlSessionFactory and at least one mapper interface.

MyBatis-Spring-Boot-Starter will:

• Autodetect an existing DataSource
• Will create and register an instance of a SqlSessionFactory passing that DataSource as an input using the SqlSessionFactoryBean
• Will create and register an instance of a SqlSessionTemplate got out of the SqlSessionFactory
• Auto-scan your mappers, link them to the SqlSessionTemplate and register them to Spring context so they can be injected into your beans

Suppose we have the following mapper:

@Mapper
public interface CityMapper {

  @Select("SELECT * FROM CITY WHERE state = #{state}")
  City findByState(@Param("state") String state);

}

You just need to create a normal Spring boot application and let the mapper be injected like follows(available on Spring 4.3+):

@SpringBootApplication
public class SampleMybatisApplication implements CommandLineRunner {

  private final CityMapper cityMapper;

  public SampleMybatisApplication(CityMapper cityMapper) {
    this.cityMapper = cityMapper;
  }

  public static void main(String[] args) {
    SpringApplication.run(SampleMybatisApplication.class, args);
  }

  @Override
  public void run(String... args) throws Exception {
    System.out.println(this.cityMapper.findByState("CA"));
  }

}

This is all you have to do. You application can now be run as a normal Spring Boot application.

Advanced scanning

The MyBatis-Spring-Boot-Starter will search, by default, for mappers marked with the @Mapper annotation.

You may want to specify a custom annotation or a marker interface for scanning. If so, you must use the @MapperScan annotation. See more about it in the MyBatis-Spring reference page.

The MyBatis-Spring-Boot-Starter will not start the scanning process if it finds at least one MapperFactoryBean in the Spring's context so if you want to stop the scanning at all you should register your mappers explicitly with @Bean methods.

Using an SqlSession

An instance of a SqlSessionTemplate is created and added to the Spring context, so you can use the MyBatis API letting it be injected into your beans like follows(available on Spring 4.3+):

@Component
public class CityDao {

  private final SqlSession sqlSession;

  public CityDao(SqlSession sqlSession) {
    this.sqlSession = sqlSession;
  }

  public City selectCityById(long id) {
    return this.sqlSession.selectOne("selectCityById", id);
  }

}

Configuration

As any other Spring Boot application a MyBatis-Spring-Boot-Application configuration parameters are stored inside the application.properties(or application.yml).

MyBatis uses the prefix mybatis for its properties.

Available properties are:

For example:

# application.properties
mybatis.type-aliases-package=com.example.domain.model
mybatis.type-handlers-package=com.example.typehandler
mybatis.configuration.map-underscore-to-camel-case=true
mybatis.configuration.default-fetch-size=100
mybatis.configuration.default-statement-timeout=30
...

# application.yml
mybatis:
    type-aliases-package: com.example.domain.model
    type-handlers-package: com.example.typehandler
    configuration:
        map-underscore-to-camel-case: true
        default-fetch-size: 100
        default-statement-timeout: 30
...

Using a ConfigurationCustomizer

The MyBatis-Spring-Boot-Starter provide opportunity to customize a MyBatis configuration generated by auto-configuration using Java Config. The MyBatis-Spring-Boot-Starter will search beans that implement the ConfigurationCustomizer interface by automatically, and call a method that customize a MyBatis configuration. (Available since 1.2.1 or above)

For example:

@Configuration
public class MyBatisConfig {
  @Bean
  ConfigurationCustomizer mybatisConfigurationCustomizer() {
    return new ConfigurationCustomizer() {
      @Override
      public void customize(Configuration configuration) {
        // customize ...
      }
    };
  }
}

Using a SqlSessionFactoryBeanCustomizer

The MyBatis-Spring-Boot-Starter provide opportunity to customize a SqlSessionFactoryBean generated by auto-configuration using Java Config. The MyBatis-Spring-Boot-Starter will search beans that implement the SqlSessionFactoryBeanCustomizer interface by automatically, and call a method that customize a SqlSessionFactoryBean. (Available since 2.2.2 or above)

For example:

@Configuration
public class MyBatisConfig {
  @Bean
  SqlSessionFactoryBeanCustomizer sqlSessionFactoryBeanCustomizer() {
    return new SqlSessionFactoryBeanCustomizer() {
      @Override
      public void customize(SqlSessionFactoryBean factoryBean) {
        // customize ...
      }
    };
  }
}

Using the SpringBootVFS

The MyBatis-Spring-Boot-Starter provides the SpringBootVFS as an implementation class of VFS. The VFS is used for searching classes (e.g. target class of type alias, type handler class) from an application (or application server). If you run a Spring Boot application using the executable jar, you need to use the SpringBootVFS. The auto-configuration feature provided by the MyBatis-Spring-Boot-Starter used it automatically, but it does not use automatically by a manual configuration (e.g. when uses multiple DataSource).

How to use the SpringBootVFS on manual configuration:

@Configuration
public class MyBatisConfig {
  @Bean
  public SqlSessionFactory masterSqlSessionFactory() throws Exception {
    SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
    factoryBean.setDataSource(masterDataSource());
    factoryBean.setVfs(SpringBootVFS.class); // Sets the SpringBootVFS class into SqlSessionFactoryBean
    // ...
    return factoryBean.getObject();
  }
}

Detecting MyBatis components

The MyBatis-Spring-Boot-Starter will detects beans that implements following interface provided by MyBatis.

• Interceptor
• TypeHandler
• LanguageDriver (Requires to use together with mybatis-spring 2.0.2+)
• DatabaseIdProvider

@Configuration
public class MyBatisConfig {
  @Bean
  MyInterceptor myInterceptor() {
    return MyInterceptor();
  }
  @Bean
  MyTypeHandler myTypeHandler() {
    return MyTypeHandler();
  }
  @Bean
  MyLanguageDriver myLanguageDriver() {
    return MyLanguageDriver();
  }
  @Bean
  VendorDatabaseIdProvider databaseIdProvider() {
    VendorDatabaseIdProvider databaseIdProvider = new VendorDatabaseIdProvider();
    Properties properties = new Properties();
    properties.put("SQL Server", "sqlserver");
    properties.put("DB2", "db2");
    properties.put("H2", "h2");
    databaseIdProvider.setProperties(properties);
    return databaseIdProvider;
  }  
}

NOTE: If detected LangaugeDriver's count is one, it set to default scripting language automatically.

Customization for LanguageDriver

If you want to customize the LanguageDriver that creating by auto-configure, please register user defined bean.

@Configuration
public class MyBatisConfig {
  @Bean
  ThymeleafLanguageDriverConfig thymeleafLanguageDriverConfig() {
    return ThymeleafLanguageDriverConfig.newInstance(c -> {
      // ... customization code
    });
  }
}

@Configuration
public class MyBatisConfig {
  @Bean
  FreeMarkerLanguageDriverConfig freeMarkerLanguageDriverConfig() {
    return FreeMarkerLanguageDriverConfig.newInstance(c -> {
      // ... customization code
    });
  }
}

@Configuration
public class MyBatisConfig {
  @Bean
  VelocityLanguageDriverConfig velocityLanguageDriverConfig() {
    return VelocityLanguageDriverConfig.newInstance(c -> {
      // ... customization code
    });
  }
}