To use MyBatis with Spring Boot, add the MyBatis Spring Boot starter version that matches your Spring Boot and Java versions. With a suitable Spring-managed DataSource, the starter auto-configures a SqlSessionFactory and SqlSessionTemplate, and can register mapper interfaces annotated with @Mapper. Use @MapperScan when you need explicit package control or a custom mapper marker.
Which MyBatis starter version works with your Spring Boot version?
Choose the starter line by the compatibility range documented for your application, not simply by selecting the newest release. The official [MyBatis Spring Boot starter requirements and configuration guide] and [starter repository README] list these compatibility ranges:
| Starter line | MyBatis-Spring | Spring Boot | Java |
|---|---|---|---|
| 4.0 | 4.0 | 4.0 or later | 17 or later |
| 3.0 | 3.0 | 3.2–3.5 | 17 or later |
| 2.3 | 2.1 | 2.7 | 8 or later |
These are the ranges listed by the project documentation; check the project’s current requirements when starting or upgrading an application, since supported release lines can change. The starter guide’s dependency example uses version 4.0.0, but that is not a universal choice for applications on older Spring Boot lines.
How do you add MyBatis to a Spring Boot application?
Add org.mybatis.spring.boot:mybatis-spring-boot-starter to the application’s dependencies, using a version compatible with its Spring Boot and Java baselines. Configure a Spring Boot DataSource for the database. When the starter detects that data source, it provides the MyBatis session infrastructure; you normally do not create a SqlSessionFactory or SqlSessionTemplate yourself.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
A mapper can be an interface annotated with @Mapper. When it is within the application’s mapper-scanning path, the starter can register it as a Spring bean for injection. For example, a service can receive the mapper through constructor injection:
@Service
public class CustomerService {
private final CustomerMapper customerMapper;
public CustomerService(CustomerMapper customerMapper) {
this.customerMapper = customerMapper;
}
}The mapper interface must still have corresponding SQL, supplied through annotations or a mapper XML file. The starter’s automatic wiring does not create queries or database tables.
How do you configure MyBatis properties and mapper XML?
Starter settings use the mybatis prefix in Spring Boot configuration. For example, these properties point to mapper XML resources, identify packages to scan, and adjust MyBatis Core behavior:
mybatis.mapper-locations=classpath:/mappers/**/*.xml
mybatis.type-aliases-package=com.example.app.domain
mybatis.type-handlers-package=com.example.app.persistence
mybatis.executor-type=SIMPLE
mybatis.configuration.map-underscore-to-camel-case=true
mybatis.configuration.default-fetch-size=100
mybatis.configuration.default-statement-timeout=30The values for fetch size and statement timeout are examples, not universal recommendations; choose them for the application and database. The documented executor types are SIMPLE, REUSE, and BATCH. These properties are also configurable in YAML using the same property names as nested keys.
If you prefer a MyBatis XML configuration file, set mybatis.config-location to its resource location. The starter documentation says not to combine mybatis.config-location with mybatis.configuration.* settings: choose the XML configuration route or the nested Boot properties for MyBatis Core settings.
When should you use @MapperScan?
Use @MapperScan when mapper interfaces are outside the default application scanning path, when you want to limit scanning to specific packages, or when mappers use a custom annotation or marker interface rather than @Mapper. For example:
@SpringBootApplication
@MapperScan("com.example.app.persistence.mapper")
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}Explicit registration can change whether the starter’s automatic mapper scan applies. The auto-configuration is conditional on existing mapper registration or scanning configuration, so avoid layering another scanner or manually registered MapperFactoryBean without checking what is already configured.
If Spring reports that a mapper bean cannot be found, check the relevant configuration in this order:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →- Confirm the mapper interface is annotated with
@Mapper, or covered by the marker configured for scanning. - Check that its package is under the application scan path or is named in
@MapperScan. - Look for existing
MapperFactoryBeanor mapper-scanner beans that may affect automatic scanning. - Verify that the application has a configured
DataSourceand that the starter dependency is on the classpath.
What does MyBatis-Spring do, and what does the starter add?
MyBatis-Spring provides the integration with Spring: it connects MyBatis sessions and mappers to Spring’s dependency injection and transaction management, and translates MyBatis exceptions into Spring’s DataAccessException hierarchy. The [MyBatis-Spring integration overview] describes those responsibilities.
The Spring Boot starter builds on that integration. It supplies Boot-oriented dependency wiring, configuration-property binding, and conditional auto-configuration around the application’s DataSource. This distinction helps when troubleshooting: mapper and session behavior belongs to MyBatis-Spring, while the starter’s role is to make that integration fit Boot conventions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
