Quarkus Doma

Introduction

Doma is a database access framework with support for type-safe Criteria API and SQL templates.

Quarkus Doma provides the following features for Doma:

  • Hot reloading

  • Automatic bean register

  • Automatic SQL execution on startup

  • Configuration

  • Multiple Datasources

  • Support for native images

Supported Version

Quarkus Doma supports Quarkus v3.7.0 and later.

Main Features

Hot reloading

In development mode, Doma extension reloads SQL and Script files when they are changed.

Automatic bean register

Doma extension registers all DAO beans to the Quarkus CDI container.

Automatic SQL import on startup

Doma extension executes import.sql when Quarkus starts.

Configuration

You can write the following configurations in your application.properties file:

quarkus.doma.sql-file-repository=greedy-cache
quarkus.doma.naming=none
quarkus.doma.exception-sql-log-type=none
quarkus.doma.dialect=h2
quarkus.doma.batch-size=10
quarkus.doma.fetch-size=50
quarkus.doma.max-rows=500
quarkus.doma.query-timeout=5000
quarkus.doma.sql-load-script=import.sql

The above properties are all optional.

Multiple Datasources

You can bind Doma’s configurations to each datasource as follows:

# default datasource
quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default
quarkus.datasource.jdbc.min-size=3
quarkus.datasource.jdbc.max-size=13

# inventory datasource
quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory
quarkus.datasource.inventory.jdbc.min-size=2
quarkus.datasource.inventory.jdbc.max-size=12

# Doma's configuration bound to the above default datasource
quarkus.doma.dialect=h2
quarkus.doma.batch-size=10
quarkus.doma.fetch-size=50
quarkus.doma.max-rows=500
quarkus.doma.query-timeout=5000
quarkus.doma.sql-load-script=import.sql

# Doma's configuration bound to the above inventory datasource
quarkus.doma.inventory.dialect=h2
quarkus.doma.inventory.batch-size=10
quarkus.doma.inventory.fetch-size=50
quarkus.doma.inventory.max-rows=500
quarkus.doma.inventory.query-timeout=5000
quarkus.doma.inventory.sql-load-script=import.sql

You can inject the named Doma’s resource using the io.quarkus.agroal.DataSource qualifier as follows:

@Inject
Config defaultConfig;

@Inject
Entityql defaultEntityql;

@Inject
NativeSql defaultNativeSql;

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

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

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

Support for native images

Doma extension recognizes reflective classes and resources, and includes them into your native image without additional configurations.

Installing

Gradle

dependencies {
    annotationProcessor("org.seasar.doma:doma-processor:2.55.1")
    implementation("org.seasar.doma:doma-core:2.55.1")
    implementation("io.quarkiverse.doma:quarkus-doma:0.0.9")
}

Maven

...
<properties>
    <doma.version>2.55.1</doma.version>
    <quarkus-doma.version>0.0.9</quarkus-doma.version>
    <compiler-plugin.version>3.9.0</compiler-plugin.version>
</properties>
...
<dependencies>
    <dependency>
        <groupId>org.seasar.doma</groupId>
        <artifactId>doma-core</artifactId>
        <version>${doma.version}</version>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.doma</groupId>
        <artifactId>quarkus-doma</artifactId>
        <version>${quarkus-doma.version}</version>
    </dependency>
</dependencies>
...
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>${compiler-plugin.version}</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <!-- the parameters=true option is critical so that RESTEasy works fine -->
                <parameters>true</parameters>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.seasar.doma</groupId>
                        <artifactId>doma-processor</artifactId>
                        <version>${doma.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Configuration References

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

The SQL dialect.

Environment variable: QUARKUS_DOMA_DIALECT

db2, h2, mssql, mysql, oracle, postgres, standard, sqlite

depends on 'quarkus.datasource.db-kind'

The batch size.

Environment variable: QUARKUS_DOMA_BATCH_SIZE

int

0

The fetch size.

Environment variable: QUARKUS_DOMA_FETCH_SIZE

int

0

The max rows.

Environment variable: QUARKUS_DOMA_MAX_ROWS

int

0

The query timeout limit in seconds.

Environment variable: QUARKUS_DOMA_QUERY_TIMEOUT

int

0

Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode:

* In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory and it will be picked up without having to set this property. Pass no-file to force Doma to ignore the SQL import file. * In production mode, it defaults to no-file. It means Doma won’t try to execute any SQL import file by default. Pass an explicit value to force Doma to execute the SQL import file.

Environment variable: QUARKUS_DOMA_SQL_LOAD_SCRIPT

string

import.sql in DEV, TEST ; no-file otherwise

The SQL file repository.

Environment variable: QUARKUS_DOMA_SQL_FILE_REPOSITORY

no-cache, greedy-cache

greedy-cache

The naming convention controller.

Environment variable: QUARKUS_DOMA_NAMING

none, lower-case, upper-case, snake-lower-case, snake-upper-case

none

The SQL log type that determines the SQL log format in exceptions.

Environment variable: QUARKUS_DOMA_EXCEPTION_SQL_LOG_TYPE

raw, formatted, none

none

Additional named datasources

Type

Default

The SQL dialect.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__DIALECT

db2, h2, mssql, mysql, oracle, postgres, standard, sqlite

depends on 'quarkus.datasource.db-kind'

The batch size.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__BATCH_SIZE

int

0

The fetch size.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__FETCH_SIZE

int

0

The max rows.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__MAX_ROWS

int

0

The query timeout limit in seconds.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__QUERY_TIMEOUT

int

0

Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode:

* In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory and it will be picked up without having to set this property. Pass no-file to force Doma to ignore the SQL import file. * In production mode, it defaults to no-file. It means Doma won’t try to execute any SQL import file by default. Pass an explicit value to force Doma to execute the SQL import file.

Environment variable: QUARKUS_DOMA__DATASOURCE_NAME__SQL_LOAD_SCRIPT

string

import.sql in DEV, TEST ; no-file otherwise