Configuration - settings - 《MyBatis v3.5.13 Documentation》

settings

settings

These are extremely important tweaks that modify the way that MyBatis behaves at runtime. The following table describes the settings, their meanings and their default values.

Setting	Description	Valid Values	Default
cacheEnabled	Globally enables or disables any caches configured in any mapper under this configuration.	true \| false	true
lazyLoadingEnabled	Globally enables or disables lazy loading. When enabled, all relations will be lazily loaded. This value can be superseded for a specific relation by using the `fetchType` attribute on it.	true \| false	false
aggressiveLazyLoading	When enabled, any method call will load all the lazy properties of the object. Otherwise, each property is loaded on demand (see also `lazyLoadTriggerMethods`).	true \| false	false (true in ≤3.4.1)
multipleResultSetsEnabled	Allows or disallows multiple ResultSets to be returned from a single statement (compatible driver required).	true \| false	true
useColumnLabel	Uses the column label instead of the column name. Different drivers behave differently in this respect. Refer to the driver documentation, or test out both modes to determine how your driver behaves.	true \| false	true
useGeneratedKeys	Allows JDBC support for generated keys. A compatible driver is required. This setting forces generated keys to be used if set to true, as some drivers deny compatibility but still work (e.g. Derby).	true \| false	False
autoMappingBehavior	Specifies if and how MyBatis should automatically map columns to fields/properties. NONE disables auto-mapping. PARTIAL will only auto-map results with no nested result mappings defined inside. FULL will auto-map result mappings of any complexity (containing nested or otherwise).	NONE, PARTIAL, FULL	PARTIAL
autoMappingUnknownColumnBehavior	Specify the behavior when detects an unknown column (or unknown property type) of automatic mapping target. `NONE`: Do nothing `WARNING`: Output warning log (The log level of `‘org.apache.ibatis.session.AutoMappingUnknownColumnBehavior’` must be set to `WARN`) `FAILING`: Fail mapping (Throw `SqlSessionException`)	NONE, WARNING, FAILING	NONE
defaultExecutorType	Configures the default executor. SIMPLE executor does nothing special. REUSE executor reuses prepared statements. BATCH executor reuses statements and batches updates.	SIMPLE REUSE BATCH	SIMPLE
defaultStatementTimeout	Sets the number of seconds the driver will wait for a response from the database.	Any positive integer	Not Set (null)
defaultFetchSize	Sets the driver a hint as to control fetching size for return results. This parameter value can be override by a query setting.	Any positive integer	Not Set (null)
defaultResultSetType	Specifies a scroll strategy when omit it per statement settings. (Since: 3.5.2)	FORWARD_ONLY \| SCROLL_SENSITIVE \| SCROLL_INSENSITIVE \| DEFAULT(same behavior with ‘Not Set’)	Not Set (null)
safeRowBoundsEnabled	Allows using RowBounds on nested statements. If allow, set the false.	true \| false	False
safeResultHandlerEnabled	Allows using ResultHandler on nested statements. If allow, set the false.	true \| false	True
mapUnderscoreToCamelCase	Enables automatic mapping from classic database column names A_COLUMN to camel case classic Java property names aColumn.	true \| false	False
localCacheScope	MyBatis uses local cache to prevent circular references and speed up repeated nested queries. By default (SESSION) all queries executed during a session are cached. If localCacheScope=STATEMENT local session will be used just for statement execution, no data will be shared between two different calls to the same SqlSession.	SESSION \| STATEMENT	SESSION
jdbcTypeForNull	Specifies the JDBC type for null values when no specific JDBC type was provided for the parameter. Some drivers require specifying the column JDBC type but others work with generic values like NULL, VARCHAR or OTHER.	JdbcType enumeration. Most common are: NULL, VARCHAR and OTHER	OTHER
lazyLoadTriggerMethods	Specifies which Object’s methods trigger a lazy load	A method name list separated by commas	equals,clone,hashCode,toString
defaultScriptingLanguage	Specifies the language used by default for dynamic SQL generation.	A type alias or fully qualified class name.	org.apache.ibatis.scripting.xmltags.XMLLanguageDriver
defaultEnumTypeHandler	Specifies the `TypeHandler` used by default for Enum. (Since: 3.4.5)	A type alias or fully qualified class name.	org.apache.ibatis.type.EnumTypeHandler
callSettersOnNulls	Specifies if setters or map’s put method will be called when a retrieved value is null. It is useful when you rely on Map.keySet() or null value initialization. Note primitives such as (int,boolean,etc.) will not be set to null.	true \| false	false
returnInstanceForEmptyRow	MyBatis, by default, returns `null` when all the columns of a returned row are NULL. When this setting is enabled, MyBatis returns an empty instance instead. Note that it is also applied to nested results (i.e. collectioin and association). Since: 3.4.2	true \| false	false
logPrefix	Specifies the prefix string that MyBatis will add to the logger names.	Any String	Not set
logImpl	Specifies which logging implementation MyBatis should use. If this setting is not present logging implementation will be autodiscovered.	SLF4J \| LOG4J(deprecated since 3.5.9) \| LOG4J2 \| JDK_LOGGING \| COMMONS_LOGGING \| STDOUT_LOGGING \| NO_LOGGING	Not set
proxyFactory	Specifies the proxy tool that MyBatis will use for creating lazy loading capable objects.	CGLIB (deprecated since 3.5.10) \| JAVASSIST	JAVASSIST (MyBatis 3.3 or above)
vfsImpl	Specifies VFS implementations	Fully qualified class names of custom VFS implementation separated by commas.	Not set
useActualParamName	Allow referencing statement parameters by their actual names declared in the method signature. To use this feature, your project must be compiled in Java 8 with `-parameters` option. (Since: 3.4.1)	true \| false	true
configurationFactory	Specifies the class that provides an instance of `Configuration`. The returned Configuration instance is used to load lazy properties of deserialized objects. This class must have a method with a signature `static Configuration getConfiguration()`. (Since: 3.2.3)	A type alias or fully qualified class name.	Not set
shrinkWhitespacesInSql	Removes extra whitespace characters from the SQL. Note that this also affects literal strings in SQL. (Since 3.5.5)	true \| false	false
defaultSqlProviderType	Specifies an sql provider class that holds provider method (Since 3.5.6). This class apply to the `type`(or `value`) attribute on sql provider annotation(e.g. `@SelectProvider`), when these attribute was omitted.	A type alias or fully qualified class name	Not set
nullableOnForEach	Specifies the default value of ‘nullable’ attribute on ‘foreach’ tag. (Since 3.5.9)	true \| false	false
argNameBasedConstructorAutoMapping	When applying constructor auto-mapping, argument name is used to search the column to map instead of relying on the column order. (Since 3.5.10)	true \| false	false

An example of the settings element fully configured is as follows:

<settings>
  <setting name="cacheEnabled" value="true"/>
  <setting name="lazyLoadingEnabled" value="true"/>
  <setting name="aggressiveLazyLoading" value="true"/>
  <setting name="multipleResultSetsEnabled" value="true"/>
  <setting name="useColumnLabel" value="true"/>
  <setting name="useGeneratedKeys" value="false"/>
  <setting name="autoMappingBehavior" value="PARTIAL"/>
  <setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
  <setting name="defaultExecutorType" value="SIMPLE"/>
  <setting name="defaultStatementTimeout" value="25"/>
  <setting name="defaultFetchSize" value="100"/>
  <setting name="safeRowBoundsEnabled" value="false"/>
  <setting name="safeResultHandlerEnabled" value="true"/>
  <setting name="mapUnderscoreToCamelCase" value="false"/>
  <setting name="localCacheScope" value="SESSION"/>
  <setting name="jdbcTypeForNull" value="OTHER"/>
  <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
  <setting name="defaultScriptingLanguage" value="org.apache.ibatis.scripting.xmltags.XMLLanguageDriver"/>
  <setting name="defaultEnumTypeHandler" value="org.apache.ibatis.type.EnumTypeHandler"/>
  <setting name="callSettersOnNulls" value="false"/>
  <setting name="returnInstanceForEmptyRow" value="false"/>
  <setting name="logPrefix" value="exampleLogPreFix_"/>
  <setting name="logImpl" value="SLF4J | LOG4J | LOG4J2 | JDK_LOGGING | COMMONS_LOGGING | STDOUT_LOGGING | NO_LOGGING"/>
  <setting name="proxyFactory" value="CGLIB | JAVASSIST"/>
  <setting name="vfsImpl" value="org.mybatis.example.YourselfVfsImpl"/>
  <setting name="useActualParamName" value="true"/>
  <setting name="configurationFactory" value="org.mybatis.example.ConfigurationFactory"/>
</settings>