Komapper: Kotlin ORM for JDBC and R2DBC

Komapper is an ORM library for server-side Kotlin.

For more documentation, go to our site:

• https://www.komapper.org/docs/

Features

Highlighted

• Support for both JDBC and R2DBC
• Code generation at compile-time using Kotlin Symbol Processing API
• Immutable and composable queries
• Support for Kotlin value classes
• Easy Spring Boot integration

Experimental

• Quarkus integration
• Transaction management using context receivers

Prerequisite

• Kotlin 2.3.21 or later
• JRE 17 or later
• Gradle 7.6.4 or later

Supported Databases

Komapper is tested with the following databases:

Database	version	JDBC support	R2DBC support
H2 Database	2.3.232	v	v
MariaDB	11.4.13	v	v
MySQL v5.x	5.7.44	v	v
MySQL v8.x	8.0.25	v	v
Oracle Database XE	18.4.0	v	v
PostgreSQL	12.9	v	v
SQL Server	2019	v	(unstable)

Supported connectivity types:

• JDBC 4.3
• R2DBC 1.0.0

Installation

Add the following code to the Gradle build script (gradle.build.kts).

plugins {
    kotlin("jvm") version "2.4.20"
    id("com.google.devtools.ksp") version "2.3.11"
}

val komapperVersion = "7.0.0"

dependencies {
    platform("org.komapper:komapper-platform:$komapperVersion").let {
        implementation(it)
        ksp(it)
    }
    implementation("org.komapper:komapper-starter-jdbc")
    implementation("org.komapper:komapper-dialect-h2-jdbc")
    ksp("org.komapper:komapper-processor")
}

See also Quickstart for more details:

• https://www.komapper.org/docs/quickstart/

Sample code

To get complete code, go to our example repository.

Entity class definition

@KomapperEntity
data class Address(
    @KomapperId
    @KomapperAutoIncrement
    @KomapperColumn(name = "ADDRESS_ID")
    val id: Int = 0,
    val street: String,
    @KomapperVersion
    val version: Int = 0,
    @KomapperCreatedAt
    val createdAt: LocalDateTime? = null,
    @KomapperUpdatedAt
    val updatedAt: LocalDateTime? = null,
)

Connecting with JDBC

fun main() {
    // create a Database instance
    val db = JdbcDatabase("jdbc:h2:mem:example;DB_CLOSE_DELAY=-1")

    // get a metamodel
    val a = Meta.address

    // execute simple operations in a transaction
    db.withTransaction {
        // create a schema
        db.runQuery {
            QueryDsl.create(a)
        }

        // INSERT
        val newAddress = db.runQuery {
            QueryDsl.insert(a).single(Address(street = "street A"))
        }

        // SELECT
        val address = db.runQuery {
            QueryDsl.from(a).where { a.id eq newAddress.id }.first()
        }
    }
}

Connecting with R2DBC

suspend fun main() {
    // create a Database instance
    val db = R2dbcDatabase("r2dbc:h2:mem:///example;DB_CLOSE_DELAY=-1")

    // get a metamodel
    val a = Meta.address

    // execute simple operations in a transaction
    db.withTransaction {
        // create a schema
        db.runQuery {
            QueryDsl.create(a)
        }

        // INSERT
        val newAddress = db.runQuery {
            QueryDsl.insert(a).single(Address(street = "street A"))
        }

        // SELECT
        val address = db.runQuery {
            QueryDsl.from(a).where { a.id eq newAddress.id }.first()
        }
    }
}

Design Policy

See DESIGN_DOC for the design policy of this project.

Compatibility Matrix

Kotlin and KSP version	Komapper version	KSP2 support?	JRE min version	Gradle min version
1.9.24-1.0.20	1.18.1 - 2.x	No	11	6.8.3
2.0.21-1.0.28	2.x - 5.x	Yes	11	7.6.4
2.1.21-2.0.2	5.x	Yes	11	7.6.4
2.2.20-2.0.3	5.x	Yes	11	7.6.4
2.3.0	5.x - 6.1.0	Yes	11	8.2
2.3.21	7.0.0 or later	Yes	17	8.2
2.4.0	7.0.0 or later	Yes	17	8.2

For Kotlin 2.3.0 and later, KSP is versioned independently of Kotlin (standalone KSP). These rows were verified with KSP 2.3.9.

Compatibility testing is performed in the komapper/compatibility-test repository.

Financial Contributors

Support Komapper's development on Open Collective.

Organizations

Individuals

Powered by