Enables object-relational mapping with concepts like databases, schemas, and entities. Supports coroutines, custom queries, and automatic undo handling, aiming for simplicity and extensibility without annotations or SQL fragmentation.
Simple Kotlin Object Relational Mapping
The nicest Kotlin multiplatform ORM around. Fully multiplatform. Coroutines-enabled.
Five main concepts:
Database - Root container for your data model
Schema - Logical grouping of entities (see Configuration)
Entity - Corresponds to a table or view (defined in kddl syntax)
Instance - A single row in a table with CRUD operations
Attribute - Custom queries and mutations (see ksql syntax), with five variants:
Four main methods in the lifecycle of database objects instances (along with transaction handling):
Instance.insert()Entity.fetch(primaryKey)Instance.update()Instance.delete()Three main customization points (see Configuration):
Two model definition formats: kddl for DDL (schema structure), ksql for DML (custom queries and mutations). And two concrete database connectors, one for JDBC and one for a service API. More to come, hopefully.
One goal: maximum simplicity without conceeding anyting to extensibility.
Zero annotation. Zero SQL code fragmentation.
Let's create a simple todo list application.
todo.kddl)database todo_app {
schema todos {
table task {
title string(200)
completed boolean = false
}
}
}
todo.ksql, optional)database todo_app {
schema todos {
attr pendingCount: Int =
SELECT count(*) FROM task WHERE completed = false;
mut Task.toggle =
UPDATE task SET completed = NOT completed WHERE task_id = {task_id};
}
}
build.gradle.kts)plugins {
kotlin("multiplatform") version "2.3.0"
id("com.republicate.skorm") version "0.14"
}
skorm {
structure.set(File("src/commonMain/model/todo.kddl"))
runtimeModel.set(File("src/commonMain/model/todo.ksql")) // optional
destPackage.set("com.example.todo")
}
dependencies {
implementation()
implementation()
implementation()
}
// Initialize database (JVM)
val database = TodoAppDatabase(CoreProcessor(JdbcConnector()))
database.configure(mapOf(
"jdbc" to mapOf(
"url" to "jdbc:h2:mem:todo",
"user" to "sa"
)
))
database.initialize()
// Create a task
val task = Task().apply {
title = "Learn skorm"
completed = false
insert()
}
// Fetch and update
fetched = Task.fetch(task.taskId)
fetched?.let {
it.completed =
it.update()
}
Task.browse().forEach { println(it.title) }
That's it! The skorm Gradle plugin generates all the necessary Kotlin classes from your .kddl file.
You can also use skorm without the code generator, accessing entities dynamically:
// Navigate the model
val schema = database.schema("todos")
val taskEntity = schema.entity("task")
// CRUD operations
val task = taskEntity.new()
task["title"] = "Learn skorm"
task["completed"] = false
task.insert()
val fetched = taskEntity.fetch(task["taskId"])
fetched?.let {
it["completed"] =
it.update()
}
taskEntity.browse().forEach { println(it[]) }
This is useful for generic tools, migrations, or when the schema is only known at runtime.
Transactions are ambient: wrap any suspend code in database.transaction { ... } and every skorm operation against that database inside the block — entity ops, attributes, raw eval/perform — joins the same transaction, without passing any handle around.
database.transaction { // or transaction("schema") { ... } for multi-schema databases
task.update()
Task().apply { title = "follow-up"; insert() }
} // commit on exit; rollback (and rethrow) on any throw
Nested blocks on the same database join the enclosing transaction (single commit). The transaction holds one connection: don't fan out parallel coroutines inside the block, and iterate lazy Sequence results before the block exits. Not available in REST mode.
Database *—— Schema *—— Entity *—— Instance
Five main verbs to interact with attributes:
eval(name, params...) - returns a scalar valueretrieve(name, params...) - returns a single row (plus Entity.fetch(params...) to get an instance by ID)query(name, params...) - returns a rowsetperform(name, params...) - for atomic mutationsSkorm automatically maps between database identifiers and Kotlin property names:
database.configure(mapOf(
"core" to mapOf(
"mapping" to mapOf(
"read" to listOf("snakeToCamel"), // DB columns: user_name → Kotlin: userName
"write" to listOf("camelToSnake") // Kotlin: userName → DB columns: user_name
)
)
))
Built-in mappers:
snakeToCamel / camelToSnakelowercase / uppercaseTransform values during read/write operations:
database.configure(mapOf(
"core" to mapOf(
"filter" to mapOf(
"read" to mapOf(
"timestamp" to "epochToLocalDateTime"
),
"write" to mapOf(
"timestamp" to "localDateTimeToEpoch"
)
)
)
))
JDBC Connector:
database.configure(mapOf(
"jdbc" to mapOf(
"url" to "jdbc:postgresql://localhost:5432/mydb",
"user" to "dbuser",
"password" to "secret"
)
))
API Client (for JS/WASM):
val database = TodoAppDatabase(ApiClient("https://api.example.com"))
database.initialize()
// Same code works on browser/Node.js!
The kddl (Kotlin Data Definition Language) format defines your database structure. It generates both SQL DDL scripts and Kotlin classes.
database <name> {
schema <name> {
table <name> {
<field_name> <type> [modifiers]
}
}
}
? - nullable field! - unique constraint= <value> - default valueExample:
table user {
!email string(255) // unique, non-null
name string(100)? // nullable
age int =
status =
now()
}
Primary keys are auto-generated as <table_name>_id with type serial:
table book {
title string
}
// Generates: book_id serial PRIMARY KEY
-> - many-to-one (foreign key)*-* - many-to-many (creates join table)--> - one-to-many (reverse navigation)Examples:
author *-* book // many-to-many: creates author_book join table
borrowing -> book, user // borrowing has book_id and user_id foreign keys
The kddl compiler generates:
book.author(), author.books())For complete kddl documentation, see the kddl project.
Beyond the basic CRUD operations, skorm allows you to define custom queries and mutations using the ksql format. These definitions generate type-safe Kotlin objects and extension functions.
attr [Entity.]name: ReturnType = SQL
mut [Entity.]name[(params)] = SQL
attr - defines a query attribute (SELECT)mut - defines a mutation attribute (INSERT/UPDATE/DELETE)attr name - function on schemaattr Entity.name - function on entity instanceSupported scalar types: Int, Long, String, Boolean, Double, Float, LocalDate, LocalDateTime,
SQL parameters are enclosed in curly braces:
attr getUserByEmail: User? =
SELECT * FROM users WHERE email = {email};
For entity-level attributes, all entity fields are automatically available:
attr Book.currentBorrower: Dude? =
SELECT dude.* FROM borrowing
JOIN dude USING (dude_id)
WHERE book_id = {book_id} // book_id from Book instance
AND returned_date IS NULL;
Mutation parameters are declared in the signature:
mut Book.lend(dude_id: Long) =
INSERT INTO borrowing (book_id, dude_id, borrowed_date)
VALUES ({book_id}, {dude_id}, now());
Schema-level scalar:
attr booksCount: Int =
SELECT count(*) FROM book;
// Generates: suspend fun BookshelfSchema.booksCount(): Int
Entity-level composite object:
attr Book.currentBorrower: (Dude, borrowing_date: LocalDateTime)? =
SELECT dude.*, borrowing_date FROM bookshelf.borrowing
JOIN dude USING (dude_id)
WHERE book_id = {book_id}
AND restitution_date IS NULL;
// Generates:
// class CurrentBorrower: Dude { val borrowingDate: LocalDateTime }
// suspend fun Book.currentBorrower(): CurrentBorrower?
Mutation with parameters:
mut Book.lend(dude_id: Long) =
INSERT INTO borrowing (dude_id, book_id, borrowing_date)
VALUES ({dude_id}, {book_id}, now());
// Generates: suspend fun Book.lend(dude_id: Long): Long
Anonymous object:
attr Book.stats: (title_length: Int, borrowed: Int) =
SELECT
CHARACTER_LENGTH(title) title_length,
(SELECT COUNT(*) FROM borrowing WHERE book_id = {book_id}) borrowed
FROM book
WHERE book_id = {book_id};
// Generates:
// class Stats { val titleLength: Int; val borrowed: Int }
// suspend fun Book.stats(): Stats
Sequence (rowset):
attr topBorrowers: (dude_id: Long, borrow_count: Int)* =
SELECT dude_id, COUNT(*) borrow_count
FROM borrowing
GROUP BY dude_id
ORDER BY borrow_count DESC
LIMIT 10;
// Generates:
// class TopBorrowers { val dudeId: Long; val borrowCount: Int }
// suspend fun BookshelfSchema.topBorrowers(): Sequence<TopBorrowers>
All generated functions are coroutine-based (suspend) and type-safe, providing compile-time checking of parameters and return types.
Let's build a complete bookshelf application that tracks books and borrowings, demonstrating both JVM backend and JS frontend using the same business logic.
bookshelf.kddl)database example {
schema bookshelf {
table dude { name string }
table author { name string }
table book {
title string
genre enum('essay', 'literature', 'art')
language string(2)
}
table borrowing {
borrowing_date date = now()
restitution_date date?
}
author *-* book
book
borrowing -> book, dude
}
}
This generates:
Dude, Author, Book, Borrowingbook.author(), author.books(), , etc.bookshelf.ksql)database example {
schema bookshelf {
// Schema-level scalar attribute
attr booksCount: Int =
SELECT count(*) FROM book;
// Entity-level attribute returning a composite object
attr Book.currentBorrower: (Dude, borrowing_date: LocalDateTime)? =
SELECT dude.*, borrowing_date FROM bookshelf.borrowing
JOIN dude USING (dude_id)
WHERE book_id = {book_id}
AND restitution_date IS NULL;
mut Book.lend(dude_id: ) =
INSERT INTO borrowing (dude_id, book_id, borrowing_date)
VALUES ({dude_id}, {book_id}, now());
mut Book.restitute =
UPDATE borrowing SET restitution_date = NOW()
WHERE book_id = {book_id} AND restitution_date IS NULL;
attr Book.stats: (title_length: , borrowed: ) =
SELECT
CHARACTER_LENGTH(title) title_length,
(SELECT COUNT(*) FROM borrowing WHERE book_id = {book_id}) borrowed
FROM book
WHERE book_id = {book_id};
attr topBorrowers: (dude_id: , borrowed: )* =
SELECT dude_id,
COUNT(restitution_date) borrowed
FROM borrowing
GROUP BY dude_id
ORDER BY borrowed DESC;
}
}
import com.republicate.skorm.ApiClient
import kotlinx.browser.window
// Same database definition, different processor!
database = ExampleDatabase(ApiClient())
{
window.onload = {
database.initialize()
database.initJoins()
database.initRuntimeModel()
document.querySelector()?.addEventListener() { event ->
event.preventDefault()
GlobalScope.launch {
bookId = form.getAttribute()
book = Book.fetch(bookId) ?: error()
dudeId = selectElement.value.toLong()
book.lend(dudeId)
document.location?.reload()
}
}
}
}
The same business logic code works on both JVM and JS:
// This code is identical on server and client:
val book = Book.fetch(bookId)
book?.let {
val borrower = it.currentBorrower()
it.lend(dudeId)
it.restitute()
}
On JVM: CoreProcessor → JDBC → Database
On JS: ApiClient → HTTP → REST API → CoreProcessor → JDBC → Database
The Processor abstraction makes your code platform-agnostic!
attempt(name, params...) - for transactionsstring, string(length), textint, long, float, double, decimal(p,s)booleandate, time, datetime, timestampserial (auto-increment), uuid, jsonenum('value1', 'value2', ...)| Syntax | Description | Example |
|---|
Type | Non-nullable scalar | Int, String, LocalDate |
Type? | Nullable scalar | Int?, String? |
(Entity, field: Type, ...) | Composite object extending entity | (Dude, borrowing_date: LocalDateTime) |
(Entity, field: Type, ...)? | Nullable composite | (Dude, borrowing_date: LocalDateTime)? |
(field: Type, ...) | Anonymous object | (count: Int, total: Double) |
(field: Type, ...)? | Nullable anonymous | (count: Int, total: Double)? |
(...)* | Sequence of objects | (name: String, count: Int)* |
LocalTimebook.borrowings()import com.republicate.skorm.core.CoreProcessor
import com.republicate.skorm.jdbc.JdbcConnector
val database = ExampleDatabase(CoreProcessor(JdbcConnector()))
fun Application.configureDatabase() {
// Configure from application.conf
database.configure(environment.config.config("skorm").toMap())
database.initialize()
database.initJoins()
database.initRuntimeModel()
// Create test data
runBlocking {
val author = Author().apply {
name = "Isaac Asimov"
insert()
}
val book = Book().apply {
title = "Foundation"
authorId = author.authorId
insert()
}
Dude().apply {
name = "Alice"
insert()
}
}
}
fun Application.configureRouting() {
routing {
get("/") {
call.respondHtml {
body {
h1 { +"My Bookshelf" }
ul {
runBlocking {
for (book in Book) {
val author = book.author()
val borrower = book.currentBorrower()
li {
+book.title
i { +" by ${author.name}" }
if (borrower != null) {
+" - borrowed by ${borrower.name}"
} else {
+" - available"
}
}
}
}
}
}
}
}
// REST API endpoint
route("/api/example") {
rest(ExampleDatabase.bookshelf)
}
}
}
Surfaced from shared tags and platforms — no rankings paid for.