Spring Boot + MyBatis: XML vs Annotations – Which to Pick?

If you've ever fought with Hibernate's lazy loading exceptions or watched in horror as it generated 10+ SQL queries for a simple join, you're not alone. JPA is powerful, but sometimes you need to take the wheel. That's where MyBatis comes in.

MyBatis is a persistence framework that gives you full control over SQL. You write the queries, you decide the mappings. No magic, no surprises. It's the go-to choice for teams working with legacy databases, complex reporting, or performance-critical systems where every millisecond counts.

In this article, I'll show you how to integrate MyBatis with Spring Boot 3.2, covering both XML mappings and annotations. You'll learn when to use each, how to avoid common pitfalls, and what the official documentation conveniently leaves out. By the end, you'll know exactly which approach fits your project and how to debug it when things go sideways.

Why MyBatis Still Matters in 2025

Let's get one thing straight: JPA is not the answer to everything. I've seen teams spend weeks trying to tune Hibernate's second-level cache, only to rip it out and replace it with MyBatis. MyBatis gives you raw SQL power without the overhead of an ORM. You write the SQL, you control the mapping.

Here's the hard truth: most teams get this wrong. They start with JPA because it's the 'standard,' then hit a wall with complex queries or legacy schemas. MyBatis shines when: - You have a legacy database with weird column names and no control over schema. - You need to write dynamic SQL with conditional WHERE clauses, pagination, and batch updates. - Performance is critical and you can't afford Hibernate's query generation overhead. - You're working with stored procedures or database-specific features.

Spring Boot 3.2 makes integration trivial. Add the starter, configure a datasource, define mappers, and you're off. But the devil is in the details—especially when mixing XML and annotations.

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Getting Started: Dependencies and Configuration

First, add the MyBatis Spring Boot Starter. I recommend version 3.0.3 with Spring Boot 3.2. If you're still on Boot 2.x, use 2.3.x. Don't mix versions—I've seen ClassNotFoundException because of incompatible MyBatis core versions.

In your application.properties (or YAML), configure the datasource and MyBatis settings:

```properties spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true spring.datasource.username=root spring.datasource.password=secret spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

mybatis.mapper-locations=classpath:mapper/*/.xml mybatis.configuration.map-underscore-to-camel-case=true mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl ```

The map-underscore-to-camel-case setting is a lifesaver. It automatically maps user_name to userName in your Java POJO. Without it, you'll spend hours writing explicit mappings.

Now create a Mapper interface. You can use either XML or annotations—or both. I'll show you both approaches.

spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false
spring.datasource.username=root
spring.datasource.password=secret
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

mybatis.mapper-locations=classpath:mapper/**/*.xml
mybatis.configuration.map-underscore-to-camel-case=true
mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

Annotation-Based Mappings: Simple and Direct

For straightforward CRUD operations, annotations are perfect. You define SQL directly on the method using @Select, @Insert, @Update, @Delete. No XML files needed.

Here's an example for a Payment entity:

```java @Mapper public interface PaymentMapper { @Select("SELECT * FROM payments WHERE id = #{id}") Payment findById(Long id);

@Insert("INSERT INTO payments(amount, currency, status) VALUES(#{amount}, #{currency}, #{status})") @Options(useGeneratedKeys = true, keyProperty = "id") int insert(Payment payment);

@Update("UPDATE payments SET status = #{status} WHERE id = #{id}") int update(Payment payment);

@Delete("DELETE FROM payments WHERE id = #{id}") int delete(Long id); } ```

Notice @Options(useGeneratedKeys = true). This is critical for auto-increment IDs. If you forget it, the generated key won't be populated in your object.

For complex queries with joins, annotations can get messy. You end up with long strings and no syntax highlighting. That's when XML shines.

@Mapper
public interface PaymentMapper {
    @Select("SELECT * FROM payments WHERE id = #{id}")
    Payment findById(Long id);

    @Insert("INSERT INTO payments(amount, currency, status) VALUES(#{amount}, #{currency}, #{status})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(Payment payment);

    @Update("UPDATE payments SET status = #{status} WHERE id = #{id}")
    int update(Payment payment);

    @Delete("DELETE FROM payments WHERE id = #{id}")
    int delete(Long id);

    @Select("SELECT * FROM payments WHERE status = #{status} ORDER BY created_at DESC")
    List<Payment> findByStatus(@Param("status") String status);
}

XML Mappings: Power and Flexibility

XML mappings give you the full power of MyBatis: dynamic SQL, result maps, and reusable fragments. They're essential for complex queries that would be a nightmare in annotations.

Create an XML file in src/main/resources/mapper/PaymentMapper.xml:

```xml <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.mapper.PaymentMapper">

<resultMap id="PaymentResultMap" type="com.example.model.Payment"> <id property="id" column="id" /> <result property="amount" column="amount" /> <result property="currency" column="currency" /> <result property="status" column="status" /> <result property="createdAt" column="created_at" /> </resultMap>

<select id="findById" resultMap="PaymentResultMap"> SELECT * FROM payments WHERE id = #{id} </select>

<select id="findByStatus" resultMap="PaymentResultMap"> SELECT * FROM payments <where> <if test="status != null and status != ''"> AND status = #{status} </if> </where> ORDER BY created_at DESC </select>

<insert id="insert" useGeneratedKeys="true" keyProperty="id"> INSERT INTO payments(amount, currency, status) VALUES(#{amount}, #{currency}, #{status}) </insert>

<update id="update"> UPDATE payments SET status = #{status} WHERE id = #{id} </update>

<delete id="delete"> DELETE FROM payments WHERE id = #{id} </delete> </mapper> ```

Notice the <where> and <if> tags. This is dynamic SQL—one of MyBatis's strongest features. You can build queries conditionally without string concatenation. The <where> tag automatically handles the first AND.

Also note the resultMap. This gives you explicit control over column-to-field mapping. It's verbose but bulletproof. For simple cases, you can use resultType instead, but I always prefer resultMap for clarity.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.PaymentMapper">
    <resultMap id="PaymentResultMap" type="com.example.model.Payment">
        <id property="id" column="id" />
        <result property="amount" column="amount" />
        <result property="currency" column="currency" />
        <result property="status" column="status" />
        <result property="createdAt" column="created_at" />
    </resultMap>
    <select id="findById" resultMap="PaymentResultMap">
        SELECT * FROM payments WHERE id = #{id}
    </select>
    <select id="findByStatus" resultMap="PaymentResultMap">
        SELECT * FROM payments
        <where>
            <if test="status != null and status != ''">
                AND status = #{status}
            </if>
        </where>
        ORDER BY created_at DESC
    </select>
    <insert id="insert" useGeneratedKeys="true" keyProperty="id">
        INSERT INTO payments(amount, currency, status)
        VALUES(#{amount}, #{currency}, #{status})
    </insert>
    <update id="update">
        UPDATE payments SET status = #{status} WHERE id = #{id}
    </update>
    <delete id="delete">
        DELETE FROM payments WHERE id = #{id}
    </delete>
</mapper>

When to Use Annotations vs XML: A Practical Guide

Here's my rule of thumb:

• Annotations: Use for simple CRUD, single-table operations, and when you have fewer than 10 queries per mapper. The code is self-contained and easy to read.
• XML: Use for complex queries with joins, dynamic SQL, stored procedures, and when you need result mappings that differ from column names. Also use XML when you want to keep SQL separate from Java code for DBA review.

But here's the twist: you can mix both in the same mapper. MyBatis allows it. I often define simple queries with annotations and complex ones in XML. Just be consistent within your team.

One thing the docs don't tell you: if you have both an annotation and an XML entry for the same method, the XML takes precedence. I've seen confusion when someone adds an annotation and wonders why it's not being used because an old XML file is still on the classpath.

@Mapper
public interface PaymentMapper {
    // Annotation-based simple query
    @Select("SELECT * FROM payments WHERE id = #{id}")
    Payment findById(Long id);

    // XML-based complex query (defined in PaymentMapper.xml)
    List<Payment> searchPayments(@Param("status") String status,
                                  @Param("minAmount") BigDecimal minAmount,
                                  @Param("maxAmount") BigDecimal maxAmount);
}

What the Official Docs Won't Tell You

Let me save you hours of debugging with these hard-earned lessons:

1. MyBatis Does Not Manage Transactions The official docs assume you know this, but many don't. MyBatis does not start or commit transactions. It delegates to the underlying JDBC connection. If you're using Spring Boot, you must use @Transactional or a TransactionTemplate. Without it, each statement auto-commits. The production incident earlier is a perfect example.

2. The 'Invalid Bound Statement' Error Is Usually a Classpath Issue You've added the XML file, but MyBatis can't find it. Check: - The namespace matches the interface FQN. - The XML file is in the path specified by mybatis.mapper-locations. - The XML file is not filtered by Maven resource plugin. Add <include>*/.xml</include> in your POM if needed.

3. Lazy Loading in MyBatis Is Not Like Hibernate MyBatis supports lazy loading for associations, but it's not enabled by default. You need to configure lazyLoadingEnabled=true and aggressiveLazyLoading=false. Even then, lazy loading requires a proxy and can lead to N+1 queries if you're not careful. I recommend using join queries instead.

4. Type Handlers Are Your Friend for Custom Types Need to map a PostgreSQL jsonb column to a Java Map? Write a custom TypeHandler. The docs cover it, but the real gotcha is that you must register it in MyBatis configuration. Use @MappedTypes and @MappedJdbcTypes annotations, or register globally via mybatis.type-handlers-package.

5. XML Mapper Files Are Not Hot-Reloaded Unlike JPA's automatic DDL, MyBatis XML files are loaded at startup. If you change an XML file, you must restart the application. In development, you can use Spring Boot DevTools with mybatis.configuration.cache-enabled=false to force reload, but it's not perfect. For production, treat XML files like code—they should be version-controlled and deployed with the app.

@MappedTypes(Map.class)
@MappedJdbcTypes(JdbcType.VARCHAR)
public class JsonbTypeHandler extends BaseTypeHandler<Map<String, Object>> {
    private static final ObjectMapper mapper = new ObjectMapper();

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, Map<String, Object> parameter, JdbcType jdbcType) throws SQLException {
        try {
            ps.setString(i, mapper.writeValueAsString(parameter));
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public Map<String, Object> getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String json = rs.getString(columnName);
        return parseJson(json);
    }

    @Override
    public Map<String, Object> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String json = rs.getString(columnIndex);
        return parseJson(json);
    }

    @Override
    public Map<String, Object> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String json = cs.getString(columnIndex);
        return parseJson(json);
    }

    private Map<String, Object> parseJson(String json) {
        try {
            return mapper.readValue(json, Map.class);
        } catch (IOException e) {
            return null;
        }
    }
}

Advanced: Dynamic SQL with

Feature	Annotations	XML Mappings
Setup	Simple, no extra files	Requires XML file per mapper
Readability	Good for simple queries	Better for complex queries
Dynamic SQL	Possible with <script> (ugly)	Native support with <if>, <where>
Result Mapping	Via @Results	Via <resultMap> (more explicit)
SQL Separation	SQL in Java code	SQL in separate XML files
Hot Reload	Yes (with DevTools)	No (requires restart)
Type Safety	Low (string SQL)	Low (string SQL)

⚙ Quick Reference

8 commands from this guide

File	Command / Code	Purpose
pom.xml		Why MyBatis Still Matters in 2025
application.properties	spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false	Getting Started
PaymentMapper.java	@Mapper	Annotation-Based Mappings
PaymentMapper.xml		XML Mappings
HybridMapper.java	@Mapper	When to Use Annotations vs XML
CustomTypeHandler.java	@MappedTypes(Map.class)	What the Official Docs Won't Tell You
AdvancedMapper.java	@Mapper	Advanced
PaymentMapperTest.java	@MybatisTest	Testing MyBatis Mappers

Key takeaways

1

MyBatis gives you full SQL control and is ideal for complex queries and legacy databases.

2

Use annotations for simple CRUD, XML for dynamic SQL and complex mappings.

3

Always manage transactions explicitly with @Transactional.

4

Enable camelCase mapping and use @Param for clarity.

5

Test mappers with @MybatisTest and ensure XML files are on the classpath.

INTERVIEW PREP · PRACTICE MODE

Interview Questions on This Topic

Practice List View

Q01SENIOR

Explain the difference between MyBatis and JPA/Hibernate. When would you...

Q02JUNIOR

How do you configure MyBatis to use camelCase mapping from underscore co...

Q03SENIOR

What is the purpose of @Param annotation in MyBatis mapper methods?

Q01 of 03SENIOR

Explain the difference between MyBatis and JPA/Hibernate. When would you choose MyBatis over JPA?

ANSWER

MyBatis is a SQL mapper that gives you full control over SQL, while JPA is an ORM that abstracts SQL. Choose MyBatis when you have legacy databases, complex queries, or need performance optimization that JPA's automatic query generation hinders. Also choose MyBatis when your team prefers writing SQL.

Q02 of 03JUNIOR

How do you configure MyBatis to use camelCase mapping from underscore column names?

ANSWER

Set 'mybatis.configuration.map-underscore-to-camel-case=true' in application.properties. This automatically maps column names like 'user_name' to Java property 'userName'.

Q03 of 03SENIOR

What is the purpose of @Param annotation in MyBatis mapper methods?

ANSWER

@Param is used to give explicit names to method parameters. Without it, MyBatis uses parameter names by reflection (Java 8+ with -parameters flag) or defaults to 'param1', 'param2', etc. It's especially important for multiple parameters and dynamic SQL.

01

Explain the difference between MyBatis and JPA/Hibernate. When would you choose MyBatis over JPA?

SENIOR

02

How do you configure MyBatis to use camelCase mapping from underscore column names?

JUNIOR

03

What is the purpose of @Param annotation in MyBatis mapper methods?

SENIOR

FAQ · 3 QUESTIONS

Frequently Asked Questions

01

Can I use both MyBatis and JPA in the same Spring Boot application?

Yes, you can. Many projects use JPA for simple CRUD and MyBatis for complex queries. Just be careful with transaction management—if both are used in the same transaction, ensure they share the same DataSource and transaction manager. Also, avoid mixing them in the same service method to prevent inconsistent state.

Was this helpful? 👍 Yes👎 No

02

How do I handle pagination with MyBatis?

MyBatis does not have built-in pagination like JPA. You can use a RowBounds parameter or write LIMIT/OFFSET in SQL. For more advanced pagination, consider using MyBatis-PageHelper or Spring Data's Pageable with a custom plugin. I recommend PageHelper for MySQL/PostgreSQL.

Was this helpful? 👍 Yes👎 No

03

What is the difference between #{} and ${} in MyBatis?

#{} is a parameter placeholder that gets replaced with a prepared statement parameter (safe from SQL injection). ${} is a string substitution that inserts raw text (vulnerable to SQL injection). Always use #{} for values. Use ${} only for dynamic table/column names, and never with user input.

Was this helpful? 👍 Yes👎 No

📖 What to Read Next

→Building REST APIs with Spring BootLearn how to build RESTful APIs using Spring Boot, the foundation for exposing MyBatis-backed services.→Spring Boot Annotations Cheat SheetA comprehensive guide to essential Spring Boot annotations, including @Mapper and @Transactional used with MyBatis.→Spring Boot Exception HandlingHandle exceptions gracefully in your MyBatis-backed Spring Boot applications.

From Other Categories

Public Key Infrastructure (PKI) ExplainedIntermediate

N

Naren Founder & Principal Engineer

20+ years shipping production Java in banking & fintech. Written from production experience, not tutorials.

Follow

✓ Verified

production tested

July 15, 2026

last updated

2,398

articles · all by Naren

🔥

That's Hibernate & JPA. Mark it forged?

5 min read · try the examples if you haven't

✓ Mark as read · go to Introduction to Spring Data Redis: CRUD Operations and Caching → Save for later