Exposed Spring Boot JDBC Integration

Latest stable Based on Exposed release 1.11.0

Spring Data repositories for Exposed DAO entities, backed by an application DataSource and an explicit transaction manager choice.

Problem

This module maps classes marked with @ExposedEntity into Spring Data repository metadata and creates repository proxies for Exposed DAO entities. The auto-configuration is active when Exposed EntityClass is present. With a caller-provided DataSource, it calls Database.connect(dataSource) and creates a bean named springTransactionManager only when a bean with that name is missing.

Spring Boot JDBC auto-configuration

When to use it

Use it when a Spring Boot JDBC application models persistence with Exposed DAO entities and wants Spring Data repository scanning, CRUD, paging/sorting, query-by-example, and the supported derived-query subset. Use the lower-level Exposed JDBC repositories when entities are not DAO Entity types or when repository proxy conventions do not fit the application.

Coordinates

Import the ecosystem BOM and omit the module version:

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-spring-boot-jdbc")
}

Core concepts

An ExposedJdbcRepository<E, ID> works with an Exposed DAO Entity and its IdTable. DAO identity, the entity cache, and change tracking live in the current Exposed transaction. Creating or mutating a DAO entity outside a transaction is therefore invalid. Spring’s service transaction should own the business unit of work; repositories perform entity operations inside that boundary.

Quick start

Mark the DAO entity with @ExposedEntity, define a repository that supplies table and extractId, and enable scanning:

@EnableExposedJdbcRepositories(basePackageClasses = [MemberRepository::class])
class PersistenceConfiguration

interface MemberRepository : ExposedJdbcRepository<Member, Long> {
    override val table get() = Members
    override fun extractId(entity: Member): Long? = entity.id.value.takeIf { it != 0L }
}

Provide the application DataSource. If the application does not define springTransactionManager, auto-configuration connects Exposed to that datasource and supplies the named manager. Put the business operation on a Spring-managed service method.

API by task

Use @EnableExposedJdbcRepositories to set repository packages, query strategy, and transactionManagerRef.
Extend ExposedJdbcRepository for list CRUD, paging/sorting, query-by-example, and findAll/count/exists with an Exposed Op<Boolean>.
Use supported method-name queries through PartTreeExposedQuery.
Create new DAO entities and change tracked properties only inside the service transaction.
Use an explicit repository implementation or Exposed DSL when a query is outside the derived-query subset.

Recommended patterns

Place the business transaction at the service layer so several repository calls and DAO mutations share one entity cache and commit decision. Return detached DTOs across asynchronous or remote boundaries rather than retaining DAO entities after the transaction. Keep repository scanning narrow and make the transaction manager name explicit in multi-datasource applications.

Integrations

ExposedSpringDataAutoConfiguration supplies the mapping context and the conditional named transaction manager. @EnableExposedJdbcRepositories imports the registrar and uses ExposedJdbcRepositoryFactoryBean. Repository proxies use the configured transactionManagerRef; they do not discover the correct datasource from a DAO entity at runtime.

Configuration

The caller configures and owns the DataSource, driver, pool, credentials, validation, and shutdown. The default repository manager name is springTransactionManager. With multiple transaction managers, set transactionManagerRef and use a service qualifier consistently. A bean with the default name suppresses the auto-configured manager, allowing the application or demo to replace it deliberately.

Failure modes

Repository entity is not recognized: verify the DAO class has @ExposedEntity and exposes the required EntityClass/table mapping.
springTransactionManager is absent: verify a DataSource bean exists or provide the named manager explicitly.
Wrong database is updated: set transactionManagerRef and the service transaction qualifier to the same manager.
DAO entity access fails after return: map it to a DTO before leaving the transaction.
Derived method cannot be parsed: stay within the bounded PartTreeExposedQuery support or provide an explicit query/implementation.

Operations

Observe datasource acquisition time, active/idle connections, transaction duration, rollback count, query latency, and pool shutdown. Log the selected transaction manager and datasource identity at startup in multi-datasource services. Do not treat repository proxy creation as a database readiness check.

Testing

Use the production database family through Testcontainers. Verify repository scanning, DAO creation and dirty-property flush inside a transaction, service-level rollback across multiple repository calls, paging/sorting, each derived-query form actually used, and the selected manager in a multi-manager context. Include a test where a custom springTransactionManager overrides auto-configuration.

Workshops and learning path

Run the Spring Boot JDBC example, then read transaction boundaries and JDBC repository patterns. The Exposed workshop expands the service and repository design.

Limitations

The module does not create a DataSource, choose among multiple transaction managers, or support every Spring Data derived-query operator. It is DAO-entity oriented: identity and change tracking require an active Exposed transaction. The demo’s explicit transaction-manager override is a supported configuration, so applications must not assume the default manager is always auto-created.

Release diagrams

These diagrams are loaded directly from README assets published with the 1.11.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

Spring Boot Exposed JDBC repository wiring diagram

Release README: spring-boot/jdbc/README.md

Spring Boot Exposed JDBC query resolution flow diagram