MyBatis with Spring

1. Introduction

MyBatis is one of the most commonly used open-source frameworks for implementing SQL databases access in Java applications.

In this quick tutorial, we’ll present how to integrate MyBatis with Spring and Spring Boot.

For those not yet familiar with this framework, be sure to check out our article on working with MyBatis.

2. Defining the Model

Let’s start by defining simple POJO that we’ll use throughout our article:

public class Article {
    private Long id;
    private String title;
    private String author;

    // constructor, standard getters and setters
}

And an equivalent SQL schema.sql file:

CREATE TABLE IF NOT EXISTS `ARTICLES`(
    `id`          INTEGER PRIMARY KEY,
    `title`       VARCHAR(100) NOT NULL,
    `author`      VARCHAR(100) NOT NULL
);

Next, let’s create a data.sql file, which simply inserts one record into our articles table:

INSERT INTO ARTICLES
VALUES (1, 'Working with MyBatis in Spring', 'VietMX Blog');

Both SQL files must be included in the classpath.

3. Spring Config

To start using MyBatis, we have to include two main dependencies — MyBatis and MyBatis-Spring:

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.2</version>
</dependency>

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>2.0.2</version>
</dependency>

Apart from that, we’ll need basic Spring dependencies:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.1.8.RELEASE</version>
</dependency>

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-beans</artifactId>
    <version>5.1.8.RELEASE</version>
</dependency>

In our examples, we’ll use the H2 embedded database to simplify the setup and EmbeddedDatabaseBuilder class from the spring-jdbc module for configuration:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.4.199</version>
</dependency>

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>5.1.8.RELEASE</version>
</dependency>

3.1. Annotation Based Configuration

Spring simplifies the configuration for MyBatis. The only required elements are javax.sql.Datasource, org.apache.ibatis.session.SqlSessionFactory, and at least one mapper.

First, let’s create a configuration class:

@Configuration
@MapperScan("com.maixuanviet.mybatis")
public class PersistenceConfig {

    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
          .setType(EmbeddedDatabaseType.H2)
          .addScript("schema.sql")
          .addScript("data.sql")
          .build();
    }

    @Bean
    public SqlSessionFactory sqlSessionFactory() throws Exception {
        SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
        factoryBean.setDataSource(dataSource());
        return factoryBean.getObject();
    }
}

We also applied a @MapperScan annotation from MyBatis-Spring that scans defined packages and automatically picks up interfaces using any of the mapper annotations, such as @Select or @Delete.

Using @MapperScan also ensures that every provided mapper is automatically registered as a Bean and can be later used with the @Autowired annotation.

We can now create a simple ArticleMapper interface:

public interface ArticleMapper {
    @Select("SELECT * FROM ARTICLES WHERE id = #{id}")
    Article getArticle(@Param("id") Long id);
}

And finally, test our setup:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = PersistenceConfig.class)
public class ArticleMapperIntegrationTest {

    @Autowired
    ArticleMapper articleMapper;

    @Test
    public void whenRecordsInDatabase_shouldReturnArticleWithGivenId() {
        Article article = articleMapper.getArticle(1L);

        assertThat(article).isNotNull();
        assertThat(article.getId()).isEqualTo(1L);
        assertThat(article.getAuthor()).isEqualTo("VietMX");
        assertThat(article.getTitle()).isEqualTo("Working with MyBatis in Spring");
    }
}

In the above example, we’ve used MyBatis to retrieve the only record we inserted previously in our data.sql file.

3.2. XML Based Configuration

As previously described, to use MyBatis with Spring, we need Datasource, SqlSessionFactory, and at least one mapper.

Let’s create the required bean definitions in the beans.xml configuration file:

<jdbc:embedded-database id="dataSource" type="H2">
    <jdbc:script location="schema.sql"/>
    <jdbc:script location="data.sql"/>
</jdbc:embedded-database>
    
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
</bean>

<bean id="articleMapper" class="org.mybatis.spring.mapper.MapperFactoryBean">
    <property name="mapperInterface" value="com.maixuanviet.mybatis.ArticleMapper" />
    <property name="sqlSessionFactory" ref="sqlSessionFactory" />
</bean>

In this example, we also used the custom XML schema provided by spring-jdbc to configure our H2 datasource.

To test this configuration, we can reuse the previously implemented test class. However, we have to adjust the context configuration, which we can do by applying the annotation:

@ContextConfiguration(locations = "classpath:/beans.xml")

4. Spring Boot

Spring Boot provides mechanisms that simplify the configuration of MyBatis with Spring even more.

First, let’s add the mybatis-spring-boot-starter dependency to our pom.xml:

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

By default, if we use an auto-configuration feature, Spring Boot detects the H2 dependency from our classpath and configures both Datasource and SqlSessionFactory for us. In addition, it also executes both schema.sql and data.sql on startup.

If we don’t use an embedded database, we can use configuration via an application.yml or application.properties file or define a Datasource bean pointing to our database.

The only thing we have left to do is to define a mapper interface, in the same manner as before, and annotate it with the @Mapper annotation from MyBatis. As a result, Spring Boot scans our project, looking for that annotation, and registers our mappers as beans.

After that, we can test our configuration using the previously defined test class by applying annotations from spring-boot-starter-test:

@RunWith(SpringRunner.class)
@SpringBootTest

5. Conclusion

In this article, we explored multiple ways of configuring MyBatis with Spring.

We looked at examples of using annotation-based and XML configuration and showed the auto-configuration features of MyBatis with Spring Boot.

As always, the complete code used in this article is available over on GitHub.