Doma Database Access Framework

Scopes allow you to define and reuse common query conditions.

1. Define a Scope Class: Create a class where methods are annotated with @Scope. These methods typically return a Consumer<WhereDeclaration> or Consumer<OrderByNameDeclaration>.
2. Register the Scope: Add the scope class to the scopes element of the @Metamodel annotation on your @Entity.
3. Use the Scope: The metamodel (e.g., Department_) will now have methods corresponding to your scope definitions.

You can combine a scope with other conditions using the andThen method.

// 1. Define the scope
public class DepartmentScope {
    @Scope
    public Consumer<WhereDeclaration> onlyTokyo(Department_ d) {
        return c -> c.eq(d.location, "Tokyo");
    }
}

// 2. Register in Entity
@Entity(metamodel = @Metamodel(scopes = { DepartmentScope.class }))
public class Department { ... }

// 3. Use it
Department_ d = new Department_();
List<Department> list = entityql.from(d).where(d.onlyTokyo()).fetch();

// Combine with other conditions
List<Department> list = entityql.from(d).where(d.onlyTokyo().andThen(c -> c.gt(d.departmentNo, 50))).fetch();

To use Doma with multiple named datasources, prefix the Doma configuration properties with the datasource name. For example, if you have a datasource named inventory, use quarkus.doma.inventory.<property>.

To inject the specific Doma resources associated with a named datasource, use the @DataSource("name") qualifier from io.quarkus.agroal.DataSource.

# default datasource
quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default

# inventory datasource
quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory

# Doma's configuration bound to the default datasource
quarkus.doma.dialect=h2

# Doma's configuration bound to the inventory datasource
quarkus.doma.inventory.dialect=h2
quarkus.doma.inventory.batch-size=10

@Inject
Config defaultConfig;

@Inject
@DataSource("inventory")
Config inventoryConfig;

@Inject
@DataSource("inventory")
Entityql inventoryEntityql;

@Inject
@DataSource("inventory")
NativeSql inventoryNativeSql;

Search conditions are defined using method parameters. Doma supports several parameter types:

• Basic classes and Domain classes: Can be passed as null.
• Arbitrary types: Use a dot . in the bind variable directive to access fields or invoke methods (e.g., /* employee.name */).
• java.util.Optional: Can contain Basic, Domain, or arbitrary types.
• java.util.Iterable: Used for mapping to the SQL IN clause.
• Optional primitives: OptionalInt, OptionalLong, OptionalDouble.

Note: For all types other than Basic or Domain classes, the argument must not be null.

-- Using basic classes
select * from employee where employee_name = /* name */'hoge'

-- Using arbitrary types (accessing fields/methods)
select * from employee where employee_name = /* employee.name */'hoge' and salary > /* employee.getSalary() */100

-- Mapping to an IN clause
select * from employee where employee_name in /* names */('aaa','bbb','ccc')

Doma uses specific syntax to distinguish between standard SQL comments and template directives. Understanding this is crucial to avoid accidental directive execution or broken SQL.

Single-line comments

Any string starting with -- is always treated as a standard single-line comment and is never interpreted as a directive.

Multi-line comments vs. Directives

Multi-line comments start with /*. Doma determines if /* is a directive or a comment based on the character immediately following it:

• It is a Multi-line Comment if the character following /* is NOT a valid Java identifier start character and is NOT one of %, #, @, ", or '.
  • Examples: /**...*/, /*+...*/, /*=...*/, /*;...*/.
• It is a Directive if the character following /* is a valid Java identifier start character or one of the special directive characters.
  • Examples: /* ...*/, /*a...*/, /*$...*/, /*@...*/, /*"...*/, /*'...*/, /*#...*/, /*%...*/.

Recommendation: Always use /**...*/ for multi-line comments to ensure they are clearly distinguishable from directives.

Doma supports optimistic concurrency control during delete operations if the following conditions are met:

• The entity class in the parameter has a property annotated with @Version.
• The ignoreVersion property in the @Delete annotation is false.

When enabled, the version number is included in the WHERE clause along with the identifier. If the delete count is 0, an OptimisticLockException is thrown.

Configuration Options

• ignoreVersion = true: The version number is not included in the delete condition. OptimisticLockException is not thrown even if no rows are deleted.
• suppressOptimisticLockException = true: The version number is included in the delete condition, but OptimisticLockException is not thrown even if the delete count is 0.

// Version is ignored in the WHERE clause
@Delete(ignoreVersion = true)
int delete(Employee employee);

// Version is included, but no exception is thrown if 0 rows deleted
@Delete(suppressOptimisticLockException = true)
int delete(Employee employee);