Add MyBatis integration module (#1921)

* Apply PR thread fixes for MyBatis factory, test, and docs wording

Agent-Logs-Url: https://github.com/micronaut-projects/micronaut-sql/sessions/d0df09e1-b61d-443d-b470-4db856f6bab1

Co-authored-by: graemerocher <66626+graemerocher@users.noreply.github.com>

* Reapply MyBatis module and docs entries after base merge

Co-authored-by: graemerocher <66626+graemerocher@users.noreply.github.com>

* correct

* Update to micronaut-core 5.0.3 (#2023)

* [skip ci] Release v7.0.2

* chore: Bump version to 7.0.3-SNAPSHOT

* add logback.xml to mybatis

* binaryCompatibility after 7.1.0

* Fix MyBatis factory bean resolution

Update MyBatis configuration creation to resolve the datasource-specific TransactionFactory through BeanLocator, falling back to JdbcTransactionFactory when none is registered.

Also type the SqlSessionManager bean explicitly so it is exposed as SqlSessionManager.

* Update

* guides example

* fix docs

* Move mappers to example.micronaut.mappers

* fix binary compatibility

* remove duplicated

* use kotlin DSL

* Update mybatis/src/main/java/io/micronaut/configuration/mybatis/package-info.java

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: graemerocher <66626+graemerocher@users.noreply.github.com>
Co-authored-by: Radovan Radic <radicr@gmail.com>
Co-authored-by: micronaut-build <micronaut-build-account@grails.org>
Co-authored-by: Sergio del Amo <sergio.delamo@softamo.com>
Co-authored-by: Sergio del Amo <sergio.del.amo.caballero@oracle.com>

Author: 5 people

buildSrc/build.gradle

@@ -8,5 +8,7 @@ repositories {
 }
 
 dependencies {
-    implementation libs.gradle.micronaut
+    implementation(libs.gradle.micronaut)
+    implementation(providers.gradleProperty("micronaut-build-version").map { "io.micronaut.build.internal:micronaut-kotlin-build-plugins:${it}" }.get())
+
 }

gradle/libs.versions.toml

@@ -25,6 +25,7 @@ managed-jooq = "3.21.6"
 managed-hibernate = "7.4.4.Final"
 managed-hibernate-reactive = "4.5.1.Final"
 managed-jasync = "2.2.4"
+managed-mybatis = "3.5.19"
 managed-jdbi = "3.54.0"
 
 # JDBC Drivers
@@ -127,6 +128,10 @@ managed-ucp17 = { module = "com.oracle.database.jdbc:ucp17", version.ref = "mana
 # UCP
 
 dms = { module = "com.oracle.database.observability:dms", version.ref = "managed-dms" }
+
+# MyBatis
+managed-mybatis = { module = "org.mybatis:mybatis", version.ref = "managed-mybatis" }
+
 # JDBC drivers
 
 managed-postgresql = { module = "org.postgresql:postgresql", version.ref = "managed-postgres-driver" }

jdbc-unpooled/build.gradle

@@ -2,12 +2,6 @@ plugins {
     id 'io.micronaut.build.internal.sql-module'
 }
 
-micronautBuild {
-    binaryCompatibility {
-        enabledAfter("7.0.0")
-    }
-}
-
 dependencies {
     api projects.micronautJdbc
     api(mn.micronaut.inject)

mybatis/build.gradle.kts

@@ -0,0 +1,25 @@
+plugins {
+    id("io.micronaut.build.internal.sql-module")
+}
+dependencies {
+    api(projects.micronautJdbc)
+    api(mn.micronaut.context)
+    api(mn.micronaut.inject)
+    api(libs.managed.mybatis)
+    testAnnotationProcessor(mn.micronaut.inject.java)
+    testImplementation(mnTest.micronaut.test.junit5)
+    testRuntimeOnly(projects.micronautJdbcHikari)
+    testRuntimeOnly(libs.managed.h2)
+    testRuntimeOnly(mnTest.junit.jupiter.engine)
+    testRuntimeOnly(mnTest.junit.platform.launcher)
+}
+
+tasks.withType<Test> {
+    useJUnitPlatform()
+}
+
+micronautBuild {
+    binaryCompatibility {
+        enabledAfter("7.1.0")
+    }
+}

mybatis/src/main/java/io/micronaut/configuration/mybatis/MyBatisConfigurationCustomizer.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.configuration.mybatis;
+
+import org.apache.ibatis.session.Configuration;
+
+/**
+ * Allows custom actions to be performed on a MyBatis {@link Configuration}.
+ * Customizers may be annotated with {@link jakarta.inject.Named} to target a specific datasource.
+ *
+ * @author Graeme Rocher
+ * @since 7.1.0
+ */
+public interface MyBatisConfigurationCustomizer {
+
+    /**
+     * Performs custom configuration operations on the given MyBatis configuration.
+     *
+     * @param configuration The configuration to customize
+     */
+    void customize(Configuration configuration);
+}

mybatis/src/main/java/io/micronaut/configuration/mybatis/MyBatisFactory.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.configuration.mybatis;
+
+import io.micronaut.context.BeanLocator;
+import io.micronaut.context.annotation.Bean;
+import io.micronaut.context.annotation.EachBean;
+import io.micronaut.context.annotation.Factory;
+import io.micronaut.context.annotation.Parameter;
+import io.micronaut.inject.qualifiers.Qualifiers;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.apache.ibatis.session.SqlSessionFactoryBuilder;
+import org.apache.ibatis.session.SqlSessionManager;
+import org.apache.ibatis.transaction.TransactionFactory;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.jspecify.annotations.Nullable;
+
+import javax.sql.DataSource;
+
+/**
+ * Configures MyBatis beans from Micronaut {@link DataSource} beans.
+ *
+ * @author Graeme Rocher
+ * @since 7.1.0
+ */
+@Factory
+public class MyBatisFactory {
+
+    /**
+     * Creates the MyBatis {@link Configuration} for a datasource.
+     *
+     * @param name        The datasource name
+     * @param dataSource  The datasource
+     * @param beanLocator The bean locator
+     * @param transactionFactory Transaction Factory
+     * @return The MyBatis configuration
+     */
+    @EachBean(DataSource.class)
+    public Configuration myBatisConfiguration(
+        @Parameter String name,
+        @Parameter DataSource dataSource,
+        @Parameter @Nullable TransactionFactory transactionFactory,
+        BeanLocator beanLocator) {
+        TransactionFactory resolvedTransactionFactory = transactionFactory != null ? transactionFactory : new JdbcTransactionFactory();
+        Configuration configuration = new Configuration(new Environment(name, resolvedTransactionFactory, dataSource));
+        for (MyBatisConfigurationCustomizer customizer : beanLocator.getBeansOfType(
+            MyBatisConfigurationCustomizer.class,
+            Qualifiers.byName(name)
+        )) {
+            customizer.customize(configuration);
+        }
+        return configuration;
+    }
+
+    /**
+     * Creates the MyBatis {@link SqlSessionFactory} for a datasource.
+     *
+     * @param configuration The MyBatis configuration
+     * @return The session factory
+     */
+    @EachBean(Configuration.class)
+    public SqlSessionFactory sqlSessionFactory(Configuration configuration) {
+        return new SqlSessionFactoryBuilder().build(configuration);
+    }
+
+    /**
+     * Creates the thread-safe {@link SqlSessionManager} for a datasource.
+     *
+     * @param sqlSessionFactory The session factory
+     * @return The session manager
+     */
+    @EachBean(SqlSessionFactory.class)
+    @Bean(typed = SqlSessionManager.class)
+    public SqlSessionManager sqlSessionManager(SqlSessionFactory sqlSessionFactory) {
+        return SqlSessionManager.newInstance(sqlSessionFactory);
+    }
+}

mybatis/src/main/java/io/micronaut/configuration/mybatis/package-info.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Configuration for MyBatis integration.
+ *
+ * @author Graeme Rocher
+ * @since 7.1.0
+ */
+@Configuration
+@Requires(classes = SqlSessionFactory.class)
+package io.micronaut.configuration.mybatis;
+
+import io.micronaut.context.annotation.Configuration;
+import io.micronaut.context.annotation.Requires;
+import org.apache.ibatis.session.SqlSessionFactory;

mybatis/src/test/java/io/micronaut/configuration/mybatis/MyBatisFactoryTest.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.configuration.mybatis;
+
+import io.micronaut.context.ApplicationContext;
+import io.micronaut.inject.qualifiers.Qualifiers;
+import io.micronaut.configuration.mybatis.support.TestTransactionFactory;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.apache.ibatis.session.SqlSessionManager;
+import org.apache.ibatis.transaction.TransactionFactory;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.junit.jupiter.api.Test;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.Statement;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class MyBatisFactoryTest {
+
+    @Test
+    void doesNotCreateBeansWithoutDataSource() {
+        try (ApplicationContext applicationContext = ApplicationContext.builder("test").start()) {
+            assertFalse(applicationContext.containsBean(DataSource.class));
+            assertFalse(applicationContext.containsBean(Configuration.class));
+            assertFalse(applicationContext.containsBean(SqlSessionFactory.class));
+            assertFalse(applicationContext.containsBean(SqlSessionManager.class));
+        }
+    }
+
+    @Test
+    void createsMyBatisBeansForTheDefaultDataSource() throws Exception {
+        try (ApplicationContext applicationContext = ApplicationContext.builder("test")
+            .properties(Map.of("datasources.default", Map.of(), "spec.name", "MyBatisFactoryTest"))
+            .start()) {
+            assertTrue(applicationContext.containsBean(DataSource.class));
+            assertTrue(applicationContext.containsBean(Configuration.class));
+            assertTrue(applicationContext.containsBean(SqlSessionFactory.class));
+            assertTrue(applicationContext.containsBean(SqlSessionManager.class));
+
+            Configuration configuration = applicationContext.getBean(Configuration.class);
+            assertTrue(configuration.hasMapper(TestMapper.class));
+            assertTrue(configuration.isMapUnderscoreToCamelCase());
+            assertInstanceOf(TestTransactionFactory.class, configuration.getEnvironment().getTransactionFactory());
+            assertSame(
+                applicationContext.getBean(TransactionFactory.class, Qualifiers.byName("default")),
+                configuration.getEnvironment().getTransactionFactory()
+            );
+
+            SqlSessionFactory sqlSessionFactory = applicationContext.getBean(SqlSessionFactory.class);
+            assertNotNull(sqlSessionFactory.getConfiguration().getEnvironment());
+            assertEquals("default", sqlSessionFactory.getConfiguration().getEnvironment().getId());
+
+            initializeSchema(applicationContext.getBean(DataSource.class));
+
+            SqlSessionManager sqlSessionManager = applicationContext.getBean(SqlSessionManager.class);
+            TestMapper mapper = sqlSessionManager.getMapper(TestMapper.class);
+            assertEquals(1, mapper.count());
+            mapper.insert();
+            assertEquals(2, mapper.count());
+        }
+    }
+
+    @Test
+    void ignoresWronglyQualifiedBeansAndFallsBackToJdbcTransactions() {
+        try (ApplicationContext applicationContext = ApplicationContext.builder("test")
+            .properties(Map.of("datasources.default2", Map.of()))
+            .start()) {
+            assertTrue(applicationContext.containsBean(DataSource.class));
+            assertTrue(applicationContext.containsBean(Configuration.class));
+            assertTrue(applicationContext.containsBean(SqlSessionFactory.class));
+            assertTrue(applicationContext.containsBean(SqlSessionManager.class));
+
+            Configuration configuration = applicationContext.getBean(Configuration.class);
+            assertFalse(configuration.hasMapper(TestMapper.class));
+            assertInstanceOf(JdbcTransactionFactory.class, configuration.getEnvironment().getTransactionFactory());
+        }
+    }
+
+    private static void initializeSchema(DataSource dataSource) throws Exception {
+        try (Connection connection = dataSource.getConnection();
+             Statement statement = connection.createStatement()) {
+            statement.execute("CREATE TABLE foo(id INT PRIMARY KEY)");
+            statement.execute("INSERT INTO foo(id) VALUES(1)");
+        }
+    }
+}

mybatis/src/test/java/io/micronaut/configuration/mybatis/TestMapper.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.configuration.mybatis;
+
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Select;
+
+interface TestMapper {
+
+    @Select("SELECT COUNT(*) FROM foo")
+    int count();
+
+    @Insert("INSERT INTO foo(id) VALUES(2)")
+    void insert();
+}

mybatis/src/test/java/io/micronaut/configuration/mybatis/TestMyBatisConfigurationCustomizer.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.configuration.mybatis;
+
+import jakarta.inject.Named;
+import jakarta.inject.Singleton;
+import org.apache.ibatis.session.Configuration;
+
+@Named("default")
+@Singleton
+final class TestMyBatisConfigurationCustomizer implements MyBatisConfigurationCustomizer {
+
+    @Override
+    public void customize(Configuration configuration) {
+        configuration.addMapper(TestMapper.class);
+        configuration.setMapUnderscoreToCamelCase(true);
+    }
+}