Use an ORM

MyBatis Persistence framework support for YugabyteDB

MyBatis is a Java persistence framework with support for custom SQL, stored procedures, and advanced object mapping. MyBatis eliminates the need for writing native JDBC code, manual results mapping, and setting of DB parameters. MyBatis provides simple XML- and annotation-based support for query-to-object mapping for retrieving database records.

YugabyteDB YSQL API has full compatibility with MyBatis for Data persistence in Java applications. This page provides details for building Java applications using MyBatis for connecting to a YugabyteDB database.

CRUD operations

Learn the basic steps required for connecting to the YugabyteDB database using MyBatis framework. The full working application is documented on the Java ORM example application page.

The following sections demonstrate how to perform common tasks required for Java application development using MyBatis persistence framework.

Step 1: Add the MyBatis dependency to your Java Project

Use the following Maven dependency in your project's pom.xml file:


If you're using Gradle, add the following dependency to your build.gradle file:

implementation 'org.mybatis:mybatis:3.5.9'

Note: MyBatis persistence framework can be used with the YugabyteDB JDBC driver and the PostgreSQL JDBC Driver.

Step 2: Implement the entity object

Create a file in the base package of the java project. Add the attributes for the User object and associated setters and getters.

public class User {

    private Long userId;

    private String firstName;

    private String lastName;

    private String email;

    // getters and setters

Step 3: Create the MyBatis data mapper for User object

MyBatis framework uses data mappers. Data mapper XML files are used for configuring DMLs that will be performed against an entity. Generally mappers are used for defining insert, update, delete, and select statements, and they are referred to as mapped SQL statements.

Create the XML file UserMapper.xml in the resources folder of your Java project and copy the following content:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-// Mapper 3.0//EN" "" >

<mapper namespace="mybatis.mapper.UserMapper">

	<insert id="save" useGeneratedKeys = "true" parameterType = "User">
        insert into users (email, first_name, last_name) values (#{email}, #{firstName}, #{lastName})
    <resultMap id="userResultMap" type="User">
        <id property="userId" column="user_id"/>
        <result property="email" column="email"/>
        <result property="firstName" column="first_name"/>
        <result property="lastName" column="last_ame"/>
    <select id="findById" resultMap="userResultMap">
        select * from users where user_id = #{userId}
    <select id="findAll" resultMap="userResultMap" fetchSize="10" flushCache="false" useCache="false" timeout="60000" statementType="PREPARED" resultSetType="FORWARD_ONLY">
        select * from users
    <delete id = "delete" parameterType = "User">
      delete from users where user_id = #{userId};

Step 4: Configure the data mappers and datasource in MyBatis configuration file

All the data mappers must be defined in the MyBatis configuration file. Create mybatis-config.xml in the resources folder to configure the MyBatis framework.

In mybatis-config.xml, define the User data mapper and the datasource for connecting to the YugabyteDB database.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- Mybatis config sample -->
<!DOCTYPE configuration
        PUBLIC "-// Config 3.0//EN" "">
        <!-- enabling default property values -->
        <property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/>
        <setting name="defaultFetchSize" value="100"/>
        <typeAlias type="User" alias="User"/>
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC" />
            <dataSource type="POOLED">
                <property name="driver" value="com.yugabyte.Driver" />
                <property name="url" value="jdbc:yugabytedb://" />
                <!-- default property values support -->
                <property name="username" value="${db.username:yugabyte}" />
                <property name="password" value="${db.password:}" />
        <mapper resource="UserMapper.xml" />

Step 5: Create MyBatis SQLSessionFactory object

SQLSession provides methods for performing database operations, retrieving mappers and result set mapping, and so forth.

SQLSessionFactory is not thread safe, so you need a thread safe way of instantiating SQLSession. Create the class in the base package to implement a thread-safe way of creating the SQLSessionFactory.


import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

public class MybatisUtil {
	private static SqlSessionFactory sqlSessionFactory;
	public static SqlSessionFactory getSessionFactory() {
        String resource = "mybatis-config.xml";
        InputStream inputStream;
		try {
			inputStream = Resources.getResourceAsStream(resource);
			sqlSessionFactory =
			          new SqlSessionFactoryBuilder().build(inputStream);
		} catch (IOException e) {
		return sqlSessionFactory;

Step 5: Create a DAO object for User object

Create a Data Access Object (DAO) in the base package. The DAO is used for implementing the basic CRUD operations for the domain object

Copy the following code into your project:

import java.util.List;

import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;

public class UserDAO {

    private SqlSessionFactory sqlSessionFactory;

    public UserDAO(SqlSessionFactory sqlSessionFactory) {
        this.sqlSessionFactory = sqlSessionFactory;

    public void save(final User entity) {
        try (SqlSession session = sqlSessionFactory.openSession()) {
        	session.insert("", entity);
         } catch (RuntimeException rte) {} 

    public User findById(final Long id) {
    	User user = null;

        try (SqlSession session = sqlSessionFactory.openSession()) {
        	user =  session.selectOne("mybatis.mapper.UserMapper.findById", id);
        } catch (RuntimeException rte) {} 
        return user;

    public List<User> findAll() {
    	List<User> users = null;
        try (SqlSession session = sqlSessionFactory.openSession()) {
            users = session.selectList("mybatis.mapper.UserMapper.findAll");
        } catch (RuntimeException rte) {}
    	return users;

    public void delete(final User user) {

        try (SqlSession session = sqlSessionFactory.openSession()) {
            session.delete("mybatis.mapper.UserMapper.delete", user.getUserId());
        } catch (RuntimeException rte) {}


Step 6: Query the YugabyteDB cluster using MyBatis Framework

Create a java class in the base package of your project. The following sample code inserts a user record and queries the table content using MyBatis.

import java.sql.SQLException;

import org.apache.ibatis.session.SqlSessionFactory;

public class MyBatisExample {
	  public static void main(String[] args) throws ClassNotFoundException, SQLException {

		  SqlSessionFactory sessionFactory = MybatisUtil.getSessionFactory();

		    System.out.println("Connected to the YugabyteDB Cluster successfully.");
			  UserDAO userDAO = new UserDAO(sessionFactory);
			  User user = new User();
			  // Save an user;
			  System.out.println("Inserted user record: " + user.getFirstName());

			  // Find the user
			  User userFromDB = userDAO.findById(new Long(201));
			  System.out.println("Query returned:" + userFromDB.toString());


When you run the Java project, should output the following:

Connected to the YugabyteDB Cluster successfully.
Inserted user record: Alice
Query returned:User [userId=101, firstName=Alice, lastName=Yugabeing,]

Learn more