Using Configuration

MyBatis-Plus offers a comprehensive set of configuration options to meet different user requirements. Some of these configurations are inherited from native MyBatis supported settings, while others are specific extension configurations unique to MyBatis-Plus.

Usage

Spring Boot Configuration

In your Spring Boot project, you can configure MyBatis-Plus through the application.yml or application.properties file.

mybatis-plus:
  configuration:
    # MyBatis configuration
    map-underscore-to-camel-case: true
  global-config:
    # Global configuration
    db-config:
      # Database configuration
      id-type: auto

Spring MVC Configuration

In traditional Spring MVC projects, you can configure MyBatis-Plus using XML configuration files.

<bean id="sqlSessionFactory" class="com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="mapperLocations" value="classpath*:mapper/**/*.xml"/>
    <property name="typeAliasesPackage" value="com.your.domain"/>
    <!-- Other configurations -->
</bean>

Base

configLocation

Type: String
Default: null

Specifies the location of the MyBatis configuration file. If you have a separate MyBatis configuration file, you should configure its path in configLocation.

Configuration Example:

mybatis-plus:
  config-location: classpath:/mybatis-config.xml

mapperLocations

Type: String[]
Default: ["classpath*:/mapper/**/*.xml"]

Specifies the location of the XML files corresponding to your MyBatis Mappers. You need to configure this if you have custom methods in your Mappers.

Configuration Example:

mybatis-plus:
  mapper-locations: classpath:/mapper/**.xml

typeAliasesPackage

Type: String
Default: null

Specifies the package scan path for MyBatis type aliases, which registers aliases for classes in the package. After registration, you can use the class name directly in the Mapper XML files without needing to use the fully qualified class name.

Configuration Example:

mybatis-plus:
  type-aliases-package: com.your.domain

typeAliasesSuperType

Type: Class<?>
Default: null

Used together with typeAliasesPackage to scan only subclasses of the specified parent class.

Configuration Example:

mybatis-plus:
  type-aliases-super-type: com.your.domain.BaseEntity

typeHandlersPackage

Type: String
Default: null

Specifies the TypeHandler scan path for registering custom type converters.

Configuration Example:

mybatis-plus:
  type-handlers-package: com.your.typehandlers

typeEnumsPackage

Type: String
Default: null

Starting from version 3.5.2, this configuration is invalid. The general enum feature can be used without any configuration.

checkConfigLocation Spring Boot Only

Type: boolean
Default: false

Specifies whether to check for the existence of MyBatis XML files during startup. By default, this check is not performed.

Configuration Example:

mybatis-plus:
  check-config-location: true

executorType Spring Boot Only

Type: ExecutorType
Default: simple

Specifies the MyBatis executor type. Available options are SIMPLE, REUSE, and BATCH.

Configuration Example:

mybatis-plus:
  executor-type: reuse

configurationProperties

Type: Properties
Default: null

Specifies externalized MyBatis Properties configuration, used to extract configuration and enable deployment with different environment settings.

Configuration Example:

mybatis-plus:
  configuration-properties: classpath:/mybatis-properties.properties

configuration

Type: Configuration
Default: null

Configuration supported by native MyBatis. For details, please refer to Configuration.

globalConfig

Type: com.baomidou.mybatisplus.core.config.GlobalConfig
Default: GlobalConfig::new

Configures the global strategy for MyBatis-Plus. For details, see GlobalConfig.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      table-prefix: tbl_
      id-type: auto

Configuration

MyBatis-Plus’s Configuration inherits from MyBatis’s native supported configuration. This means you can configure it through MyBatis XML configuration files, or through Spring Boot or Spring MVC configuration files.

mapUnderscoreToCamelCase

Type: boolean
Default: true

Enables automatic camel case mapping, which converts classic database column names like A_COLUMN (underscore notation) to classic Java property names like aColumn (camel case notation).

Configuration Example:

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true

defaultEnumTypeHandler

Type: Class<? extends TypeHandler>
Default: org.apache.ibatis.type.EnumTypeHandler

The default enumeration type handler. If you configure this property, all enumerations will use the specified handler for processing.

Configuration Example:

mybatis-plus:
  configuration:
    default-enum-type-handler: org.apache.ibatis.type.EnumOrdinalTypeHandler

MyBatis-Plus supports multiple enumeration handling methods, including storing enum names, indices, or custom handling. Starting from version 3.5.2, the default enum handler is CompositeEnumTypeHandler, which automatically selects the appropriate handling method based on whether the enumeration is a MyBatis-Plus generic enum.

org.apache.ibatis.type.EnumTypeHandler : Stores the enum name
org.apache.ibatis.type.EnumOrdinalTypeHandler : Stores the enum index
com.baomidou.mybatisplus.extension.handlers.MybatisEnumTypeHandler : The enum class must implement the IEnum interface or have fields marked with the @EnumValue annotation. (In versions below 3.1.2, this was EnumTypeHandler)
~~com.baomidou.mybatisplus.extension.handlers.EnumAnnotationTypeHandler: Enum class fields must be marked with the @EnumValue annotation~~

Starting from version 3.5.2, the default enum handler is CompositeEnumTypeHandler. It uses MybatisEnumTypeHandler internally to process enums defined as MyBatis-Plus generic enums (those that implement IEnum or have the EnumValue annotation).

For other enums, it uses the internal property defaultEnumTypeHandler (default: org.apache.ibatis.type.EnumTypeHandler) for processing.

This configuration only changes the value of CompositeEnumTypeHandler#defaultEnumTypeHandler.

aggressiveLazyLoading

Type: boolean
Default: true

When set to true, lazy-loaded objects may be fully loaded by any lazy property. Otherwise, each property loads on demand. This must be used together with lazyLoadingEnabled.

Configuration Example:

mybatis-plus:
  configuration:
    aggressive-lazy-loading: false

autoMappingBehavior

Type: AutoMappingBehavior
Default: partial

Specifies MyBatis’ automatic mapping strategy. This configuration determines whether and how MyBatis automatically maps database table columns to object properties.

AutoMappingBehavior.NONE: Disables automatic mapping
AutoMappingBehavior.PARTIAL: Only performs automatic mapping for non-nested resultMaps
AutoMappingBehavior.FULL: Performs automatic mapping for all resultMaps

Configuration Example:

mybatis-plus:
  configuration:
    auto-mapping-behavior: full

autoMappingUnknownColumnBehavior

Type: AutoMappingUnknownColumnBehavior
Default: NONE

Specifies how MyBatis handles unknown columns or properties during automatic mapping. This configuration determines the behavior when MyBatis encounters unknown columns or properties during the auto-mapping process.

AutoMappingUnknownColumnBehavior.NONE: No action taken (default)
AutoMappingUnknownColumnBehavior.WARNING: Logs relevant warning messages
AutoMappingUnknownColumnBehavior.FAILING: Treats as mapping failure and throws an exception with detailed information

Configuration Example:

mybatis-plus:
  configuration:
    auto-mapping-unknown-column-behavior: warning

localCacheScope

Type: String
Default: SESSION

MyBatis Level 1 cache, defaults to SESSION.

SESSION: Session-level cache. The same query statement within the same Session will not query the database again.
STATEMENT: Disables the Level 1 cache.

Configuration Example:

mybatis-plus:
  configuration:
    local-cache-scope: statement

cacheEnabled

Type: boolean
Default: true

Specifies whether to enable the MyBatis second-level cache.

Configuration Example:

mybatis-plus:
  configuration:
    cache-enabled: false

callSettersOnNulls

Type: boolean
Default: false

Specifies whether to call the Setter methods of mapped objects (or put methods for Map objects) when values in the result set are null. This is typically used when you have dependencies on Map.keySet() or need to initialize null values.

Configuration example:

mybatis-plus:
  configuration:
    call-setters-on-nulls: true

configurationFactory

Type: Class<?>
Default: null

Specifies a factory class that provides a Configuration instance. The instance produced by this factory is used to load the lazy loading property values of deserialized objects. The factory class must contain a signature method: static Configuration getConfiguration().

Configuration Example:

mybatis-plus:
  configuration:
    configuration-factory: com.your.config.MyConfigurationFactory

GlobalConfig

GlobalConfig is a global strategy configuration provided by MyBatis-Plus that allows you to customize MyBatis-Plus behavior globally.

Type: boolean
Default: true

Controls whether to print the MyBatis-Plus LOGO in the console.

Configuration example:

mybatis-plus:
  global-config:
    banner: false

enableSqlRunner

Type: boolean
Default: false

Controls whether to initialize SqlRunner (com.baomidou.mybatisplus.extension.toolkit.SqlRunner).

Configuration Example:

mybatis-plus:
  global-config:
    enable-sql-runner: true

sqlInjector

Type: com.baomidou.mybatisplus.core.injector.ISqlInjector
Default: com.baomidou.mybatisplus.core.injector.DefaultSqlInjector

The SQL injector is used to inject the universal methods provided by MyBatis-Plus. When using the Starter, you can inject it via @Bean.

Configuration Example:

mybatis-plus:
  global-config:
    sql-injector: com.baomidou.mybatisplus.core.injector.DefaultSqlInjector

@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor());
    return interceptor;
}

superMapperClass

Type: Class
Default Value: com.baomidou.mybatisplus.core.mapper.Mapper.class

The generic Mapper parent class. Only Mapper classes that are subclasses of this parent class will have the methods from sqlInjector injected.

metaObjectHandler

Type: com.baomidou.mybatisplus.core.handlers.MetaObjectHandler
Default: null

Meta object field filler controller used for automatically populating entity class fields. Supports @Bean injection when using the Starter.

Configuration Example:

mybatis-plus:
  global-config:
    meta-object-handler: com.example.MyMetaObjectHandler

@Bean
public MetaObjectHandler metaObjectHandler() {
    return new MyMetaObjectHandler();
}

identifierGenerator Since 3.3.0

Type: com.baomidou.mybatisplus.core.incrementer.IdentifierGenerator
Default: com.baomidou.mybatisplus.core.incrementer.DefaultIdentifierGenerator

ID generator used to generate unique identifiers for entity classes. Supports @Bean injection in Starter environments.

Configuration Example:

mybatis-plus:
  global-config:
    identifier-generator: com.baomidou.mybatisplus.core.incrementer.DefaultIdentifierGenerator

@Bean
public IdentifierGenerator identifierGenerator() {
    return new CustomIdentifierGenerator();
}

dbConfig

Type: com.baomidou.mybatisplus.core.config.GlobalConfig$DbConfig
Default: null

Configures the database strategy within MyBatis-Plus’s global strategy. For details, see DbConfig.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      table-prefix: tbl_
      id-type: ASSIGN_ID

DbConfig

idType

Type: com.baomidou.mybatisplus.annotation.IdType
Default: ASSIGN_ID

Global default primary key type.

IdType.AUTO: Uses database auto-increment ID as the primary key.
IdType.NONE: No specific generation strategy. If global configuration contains IdType-related settings, it will follow the global configuration.
IdType.INPUT: You manually set the primary key value before inserting data.
IdType.ASSIGN_ID: Automatically assigns an ID, suitable for primary keys of type Long, Integer, or String. By default, it uses the snowflake algorithm implemented via IdentifierGenerator’s nextId method. @since 3.3.0
IdType.ASSIGN_UUID: Automatically assigns a UUID, suitable for primary keys of type String. The default implementation uses IdentifierGenerator’s nextUUID method. @since 3.3.0

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      id-type: ASSIGN_ID

tablePrefix

Type: String
Default: null

Specifies the prefix for table names.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      table-prefix: tbl_

schema

Type: String
Default: null

Specifies the database schema name. You typically don’t need to set this.

Configuration example:

mybatis-plus:
  global-config:
    db-config:
      schema: my_schema

columnFormat

Type: String
Default: null

Formats column names when generating SQL, for example by adding a prefix or suffix. This does not apply to primary keys. Example: %s.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      column-format: %s_field

tableFormat Since 3.5.3.2

Type: String
Default: null

Formats table names when generating SQL, for example: %s.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      table-format: tbl_%s

propertyFormat Since 3.3.0

Type: String
Default: null

Formats entity field names when they are mapped to database column names. This only applies to column as property scenarios and does not affect primary keys. Example: %s.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      property-format: %s_prop

tableUnderline

Type: boolean
Default value: true

Controls whether to convert table names from camel case to underscore notation.

Configuration example:

mybatis-plus:
  global-config:
    db-config:
      table-underline: false

capitalMode

Type: boolean
Default: false

Controls whether table names and column names use uppercase naming.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      capital-mode: true

keyGenerator

Type: com.baomidou.mybatisplus.core.incrementer.IKeyGenerator
Default: null

Custom table primary key generator. Supports @Bean injection in Starter environments.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      key-generator: com.example.CustomKeyGenerator

@Bean
public IKeyGenerator keyGenerator() {
    return new CustomKeyGenerator();
}

logicDeleteField

Type: String
Default: null

The global entity logical delete field property name. This setting only takes effect when the logical delete feature is enabled.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: deleted

logicDeleteValue

Type: String
Default: 1

The value that represents a logically deleted record. This setting only takes effect when the logic delete feature is enabled.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      logic-delete-value: true

logicNotDeleteValue

Type: String
Default value: 0

Specifies the value that represents a logically non-deleted record. This setting only takes effect when the logical delete feature is enabled.

Configuration example:

mybatis-plus:
  global-config:
    db-config:
      logic-not-delete-value: false

insertStrategy

Type: com.baomidou.mybatisplus.annotation.FieldStrategy
Default: NOT_NULL

Controls the field validation strategy during INSERT operations.

FieldStrategy.DEFAULT: Follows the global configuration strategy. If no global configuration is specified, the default behavior is to insert the field only when its value is not NULL.
FieldStrategy.ALWAYS: Always inserts the field, regardless of whether the field value is NULL or not.
FieldStrategy.NOT_NULL: Inserts the field only when its value is not NULL.
FieldStrategy.NOT_EMPTY: Inserts the field only when its value is not empty (for String types) or not NULL (for other types).
FieldStrategy.NEVER: Never inserts the field, even if the field value is not NULL.
FieldStrategy.IGNORED: Ignores validation check, effect is equivalent to “ALWAYS” @Deprecated

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      insert-strategy: NEVER

updateStrategy

Type: com.baomidou.mybatisplus.annotation.FieldStrategy
Default: NOT_NULL

Controls the field validation strategy during Update operations.

Configuration Example:

mybatis-plus:
  global-config:
    db-config:
      update-strategy: IGNORED

whereStrategy

Type: com.baomidou.mybatisplus.annotation.FieldStrategy
Default value: NOT_NULL

Controls the field validation strategy during Update operations. Specifically, it determines the WHERE conditions generated by the Wrapper based on the internal Entity.

Configuration example:

mybatis-plus:
  global-config:
    db-config:
      where-strategy: ALWAYS

Power by Astro Starlight | Sponsored by JetBrains