Doma

Doma is a database access framework for Java with several notable strengths:

• It checks and generates source code at compile time using annotation processing.
• It supports associations between entities.
• It offers a type-safe Criteria API.
• It includes SQL templates, known as “two-way SQL.”
• It runs independently, without relying on any other libraries.

Backers

If you use Doma in your project or enterprise and would like to support ongoing development, please consider becoming a backer.

Supported by

---

Prerequisite

The latest major version of Doma supports Java 17 and above. If you are using Java 8, please use Doma 2.

See also Major versions.

Supported databases

We are testing against the following databases:

Database	version	status
H2 Database	2.5.252	stable
MySQL v5	5.7	stable
MySQL v8	8.0.36	stable
Oracle Database Free	23.4	stable
PostgreSQL	12.20	stable
SQLite	3.54.1.0	stable
SQL Server	2019	stable

Examples

Type-safe Criteria API

This code uses a type-safe Criteria API to fetch employees from a specific department while establishing associations between the related entities:

var queryDsl = new QueryDsl(config);
var e = new Employee_();
var d = new Department_();

var employees = queryDsl
    .from(e)
    .innerJoin(d, on -> on.eq(e.departmentId, d.departmentId))
    .where(c -> c.eq(d.departmentName, "SALES"))
    .associate(e, d, (employee, department) -> {
        employee.setDepartment(department);
        department.getEmployeeList().add(employee);
    })
    .fetch();

See Unified Criteria API for more information.

SQL templates

This code uses an SQL template to fetch employees from a specific department while establishing associations between the related entities:

@Dao
public interface EmployeeDao {

  @Sql(
    """
    select
      /*%expand*/*
    from
      EMPLOYEE e
      inner join
      DEPARTMENT d
        on e.departmentId = d.departmentId
    where
      /*%if departmentName != null*/
      d.DEPARTMENT_NAME = /*departmentName*/'test'
      /*%end*/
    """)
  @Select(aggregateStrategy = EmployeeStrategy.class)
  List<Employee> selectByDepartmentName(String departmentName);

  @AggregateStrategy(root = Employee.class, tableAlias = "e")
  interface EmployeeStrategy {
    @AssociationLinker(propertyPath = "department", tableAlias = "d")
    BiFunction<Employee, Department, Employee> department = (e, d) -> {
      e.setDepartment(d);
      d.getEmployees().add(e);
      return e;
    };
  }
}

See SQL templates and Aggregate strategies for more information.

More Examples

Try Getting started and simple-examples.

Using Doma with AI coding agents

Doma checks SQL templates, bind variables and DAO signatures at compile time, so many mistakes in code written by AI coding agents fail the build with a DOMA error that the agent can read and fix, instead of failing later at runtime.

• llms.txt summarizes how to write Doma code, including the SQL template grammar and common pitfalls. Give it to your coding agent as context.
• doma-agent-bench measures how well coding agents build features with Doma and records where they fail. Its results guide improvements to Doma's documentation, error messages and compile-time checks.

Installing

Gradle

For Java projects:

plugins {
    id("org.domaframework.doma.compile") version "4.0.4"
}

dependencies {
    implementation("org.seasar.doma:doma-core:3.15.0")
    annotationProcessor("org.seasar.doma:doma-processor:3.15.0")
}

For Kotlin projects, use doma-kotlin instead of doma-core and use kapt in place of annotationProcessor:

plugins {
  id("org.domaframework.doma.compile") version "4.0.4"
}

dependencies {
    implementation("org.seasar.doma:doma-kotlin:3.15.0")
    kapt("org.seasar.doma:doma-processor:3.15.0")
}

Maven

We recommend using Gradle, but if you want to use Maven, see below.

For Java projects:

This is the beginning of the README. Read the rest at the original. Read the full README ↗