Overview

Relevant source files

• .github/workflows/build.yml
• .github/workflows/release.yml
• .sdkmanrc
• DESIGN_DOC.md
• README.md
• build.gradle.kts
• gradle-plugin/build.gradle.kts
• gradle.properties
• gradle/libs.versions.toml
• komapper-processor/build.gradle.kts
• settings.gradle.kts

Purpose and Scope

This document provides a high-level introduction to Komapper, a Kotlin ORM library for JDBC and R2DBC. It covers the project's purpose, architectural philosophy, module structure, and key technical characteristics.

For detailed information on specific subsystems:

• For setting up a new project, see Getting Started
• For entity mapping details, see Entity Mapping
• For query construction, see Query DSL
• For database connectivity, see Database Support
• For build system details, see Build and Development

Sources: README.md1-11 gradle.properties8-11

---

What is Komapper

Komapper is an ORM (Object-Relational Mapping) library for server-side Kotlin that provides database access through both JDBC (blocking) and R2DBC (reactive) connectivity. It generates type-safe metamodels at compile-time using Kotlin Symbol Processing (KSP), enabling developers to write database queries without runtime reflection or string-based SQL.

Key Characteristics:

Aspect	Details
Current Version	5.7.1-SNAPSHOT
Language	Kotlin 2.3.0
Code Generation	KSP 2.3.4 (with KSP2 enabled)
Connectivity	JDBC 4.3 and R2DBC 1.0.0
Minimum JRE	Java 11
Repository	github.com/komapper/komapper
Package Group	org.komapper

Sources: gradle.properties1-11 gradle/libs.versions.toml1-7 README.md1-11

---

Core Design Philosophy

Komapper follows several architectural principles that distinguish it from other Kotlin ORMs:

Compile-Time Code Generation

Komapper uses the KSP (Kotlin Symbol Processing API) to generate entity metamodels at compile-time. This approach avoids runtime reflection calls and database metadata reading, which results in:

• Simpler code structure
• Compile-time error detection
• Native image compatibility without additional configuration
• Faster startup times

The komapper-processor module processes entities annotated with @KomapperEntity and generates type-safe metamodel classes.

Immutable Data Models

Entity classes must be Kotlin data classes, enforcing immutability. This design choice reduces defects by preventing unexpected state mutations during database operations.

Query Construction vs Execution Separation

Query construction (via QueryDsl) is separate from query execution (via JdbcDatabase or R2dbcDatabase). A single Query object can be executed by either JDBC or R2DBC database instances, enabling code reuse across blocking and reactive paradigms.

Modular Architecture

The codebase is organized into 90+ independent modules registered in settings.gradle.kts1-94 Core functionality is separated from database-specific dialects, connectivity implementations, and framework integrations. Modules are composed at runtime using Java's ServiceLoader mechanism.

Minimal Data Caching

Komapper generally avoids caching database results to reduce complexity. The only exception is sequence value caching for ID generation optimization.

Sources: DESIGN_DOC.md1-118 README.md15-28

---

High-Level Architecture

Module Categories

Sources: settings.gradle.kts1-94 README.md15-28

Development to Runtime Flow

Sources: gradle.properties3 README.md56-76 komapper-processor/build.gradle.kts1-27

---

Module Structure

The project contains 90+ modules organized into functional categories:

Core Modules

Module	Purpose	Location
komapper-core	Query DSL, SQL builder, core abstractions	settings.gradle.kts12
komapper-annotation	Entity annotations (@KomapperEntity, @KomapperId, etc.)	settings.gradle.kts16
komapper-processor	KSP annotation processor for metamodel generation	settings.gradle.kts17
komapper-tx-core	Transaction management abstraction	settings.gradle.kts13

JDBC Stack

Module	Purpose	Location
komapper-jdbc	JDBC implementation of Database interface	settings.gradle.kts21
komapper-tx-jdbc	JDBC transaction management	settings.gradle.kts23
komapper-starter-jdbc	Standalone JDBC starter	settings.gradle.kts22
komapper-dialect-{db}-jdbc	Database-specific JDBC dialects (6 databases)	settings.gradle.kts32-49

R2DBC Stack

Module	Purpose	Location
komapper-r2dbc	R2DBC reactive implementation	settings.gradle.kts27
komapper-tx-r2dbc	R2DBC transaction management	settings.gradle.kts29
komapper-starter-r2dbc	Standalone R2DBC starter	settings.gradle.kts28
komapper-dialect-{db}-r2dbc	Database-specific R2DBC dialects (6 databases)	settings.gradle.kts32-49

Spring Integration

Module	Purpose	Location
komapper-spring-jdbc	Spring JDBC integration	settings.gradle.kts53
komapper-spring-r2dbc	Spring R2DBC integration	settings.gradle.kts54
komapper-spring-boot-starter-jdbc	Spring Boot JDBC starter with auto-configuration	settings.gradle.kts57
komapper-spring-boot-starter-r2dbc	Spring Boot R2DBC starter with auto-configuration	settings.gradle.kts58

Optional Feature Modules

Module	Purpose	Location
komapper-template	Template-based SQL query support	settings.gradle.kts65
komapper-slf4j	SLF4J logging integration	settings.gradle.kts67
komapper-sqlcommenter	SQL comment injection for tracing	settings.gradle.kts68
komapper-codegen	Runtime code generation utilities	settings.gradle.kts66

Experimental Modules

Module	Purpose	Location
komapper-quarkus-jdbc	Quarkus JDBC integration	settings.gradle.kts77
komapper-tx-context-jdbc	Context receiver-based JDBC transactions	settings.gradle.kts79
komapper-tx-context-r2dbc	Context receiver-based R2DBC transactions	settings.gradle.kts80

Testing Infrastructure

Module	Purpose	Location
integration-test-core	Shared test utilities and base classes	settings.gradle.kts91
integration-test-jdbc	JDBC integration tests for 7 databases	settings.gradle.kts92
integration-test-r2dbc	R2DBC integration tests for 7 databases	settings.gradle.kts93

Sources: settings.gradle.kts1-94

---

Database Support Matrix

Komapper supports 6 major database systems with parallel JDBC and R2DBC implementations:

Database	Version	JDBC Module	R2DBC Module	Status
H2	2.4.240	komapper-dialect-h2-jdbc	komapper-dialect-h2-r2dbc	Stable
MariaDB	10.6.3	komapper-dialect-mariadb-jdbc	komapper-dialect-mariadb-r2dbc	Stable
MySQL 5.x	5.7.44	komapper-dialect-mysql-jdbc	komapper-dialect-mysql-r2dbc	Stable
MySQL 8.x	8.0.25	komapper-dialect-mysql-jdbc	komapper-dialect-mysql-r2dbc	Stable
Oracle XE	18.4.0	komapper-dialect-oracle-jdbc	komapper-dialect-oracle-r2dbc	Stable
PostgreSQL	12.9	komapper-dialect-postgresql-jdbc	komapper-dialect-postgresql-r2dbc	Stable
SQL Server	2019	komapper-dialect-sqlserver-jdbc	komapper-dialect-sqlserver-r2dbc	R2DBC Unstable

Connectivity Types

• JDBC 4.3: Blocking I/O using JDBC drivers with HikariCP connection pooling
• R2DBC 1.0.0: Non-blocking reactive I/O using R2DBC drivers with r2dbc-pool

Sources: README.md36-54 gradle/libs.versions.toml24-39

---

Technology Stack

Core Dependencies

Build Configuration

The project uses Gradle with a centralized version catalog:

• Version Catalog: gradle/libs.versions.toml1-100 defines all dependency versions
• Platform BOM: komapper-platform provides bill-of-materials for version management
• Multi-Module Build: build.gradle.kts1-233 configures 90+ modules
• Release Automation: gradle.properties16-21 and release plugin handle versioning

Build Features

Feature	Configuration	Location
KSP2 Support	ksp.useKSP2=true	gradle.properties3
Parallel Builds	org.gradle.parallel=true	gradle.properties5
Build Cache	org.gradle.caching=true	gradle.properties6
JVM Memory	-Xmx4096m -XX:MaxMetaspaceSize=1024m	gradle.properties4
Code Style	Spotless with ktlint 1.8.0	build.gradle.kts42-47

Sources: gradle.properties1-22 gradle/libs.versions.toml1-100 build.gradle.kts1-233

---

CI/CD Pipeline

Continuous Integration

The GitHub Actions build workflow executes on every push and pull request:

The CI pipeline runs 14 parallel test jobs (7 databases × 2 connectivity types) on Ubuntu with JDK 17. Test tasks are defined with fail-fast: false to ensure all database combinations are tested even if one fails.

Release Workflow

The release process is automated via .github/workflows/release.yml1-63:

1. Trigger manual workflow with version number (or auto-detect from draft release)
2. Execute ./gradlew release -Prelease.releaseVersion=X.Y.Z
3. Update version in README.md65 via replaceVersion task
4. Create git tag vX.Y.Z
5. Publish artifacts to Maven Central and Gradle Plugin Portal
6. Increment to next SNAPSHOT version

Sources: .github/workflows/build.yml1-141 .github/workflows/release.yml1-63 build.gradle.kts199-232

---

Prerequisites and Requirements

To use or develop Komapper:

Requirement	Minimum Version	Recommended
Kotlin	1.9.24	2.3.0+
JRE	11	17+
Gradle	6.8.3	7.6.4+
KSP	Matching Kotlin version	2.3.4

For Spring integration projects, JRE 17 is required due to Spring Boot 3.x compatibility.

Sources: README.md30-35 build.gradle.kts64-95

---

Quick Start Example

A minimal Komapper project requires:

1. Gradle Configuration (README.md56-76):

   • Apply kotlin("jvm") and com.google.devtools.ksp plugins
   • Add komapper-platform as both implementation and ksp platform
   • Add komapper-starter-jdbc or komapper-starter-r2dbc
   • Add database-specific dialect (e.g., komapper-dialect-h2-jdbc)
   • Add komapper-processor to ksp configuration

2. Entity Definition (README.md86-103):

   • Create data class with @KomapperEntity
   • Mark primary key with @KomapperId
   • Optionally add @KomapperAutoIncrement, @KomapperVersion, @KomapperCreatedAt, @KomapperUpdatedAt

3. Database Operations (README.md105-162):

   • Create JdbcDatabase or R2dbcDatabase instance with connection URL
   • Access generated metamodel via Meta.{entityName}
   • Build queries using QueryDsl.from(), QueryDsl.insert(), etc.
   • Execute with database.runQuery() inside database.withTransaction {}

Sources: README.md56-162

---

Next Steps

For detailed information on specific aspects of Komapper:

• Installation and Project Setup: See Getting Started
• Entity Mapping and Annotations: See Entity Mapping
• Query DSL Syntax: See Query DSL
• Transaction Management: See Transaction Management
• Spring Boot Integration: See Framework Integration
• Building from Source: See Build and Development