Tutorials/Exposed vs Storm: the model

One model instead of three

Exposed and Storm are both type-safe Kotlin data layers. They differ in where joins and row mappings live. Exposed writes them with each query; Storm declares them once, in the data class, and every query reuses them.

Series · Exposed to Storm5 min readKotlin

01The task

Two tables, pets and owners, with one foreign key. One query lists the pets of the owners named Davis with the owner's name, a second filters pets on name, and a service returns typed results that a controller serializes.

02The Exposed way

Exposed, built by JetBrains, declares the schema in table objects, and the compiler checks every column reference. With the DSL the task looks like this:

Pets.kt Kotlin · Exposed DSL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// The schema lives in table objects ...
object Owners : Table("owner") {
    val id = integer("id").autoIncrement()
    val firstName = varchar("first_name", 30)
    val lastName = varchar("last_name", 30)
    override val primaryKey = PrimaryKey(id)
}

object Pets : Table("pet") {
    val id = integer("id").autoIncrement()
    val name = varchar("name", 30)
    val ownerId = integer("owner_id") references Owners.id
    override val primaryKey = PrimaryKey(id)
}

// ... the shape you pass around is a separate declaration ...
data class PetRow(val name: String, val ownerName: String)

// ... and each query bridges the two
val ofDavis = transaction {
    (Pets innerJoin Owners)
        .selectAll()
        .where { Owners.lastName eq "Davis" }
        .map { PetRow(it[Pets.name], it[Owners.lastName]) }
}

// The next query writes the same join and the same mapping again
val namedLeo = transaction {
    (Pets innerJoin Owners)
        .selectAll()
        .where { Pets.name eq "Leo" }
        .map { PetRow(it[Pets.name], it[Owners.lastName]) }
}

All of it is type-safe. The join and the row mapping belong to each query, so the second query states both again. A schema with hundreds of queries carries hundreds of these, and a column added to PetRow means a change in each query that fills it. The DAO layer removes the mapping and adds a third declaration of the same data:

Pet.kt Kotlin · Exposed DAO
1
2
3
4
5
6
7
8
9
10
11
// The DAO layer replaces the mapping with a third declaration
class Pet(id: EntityID<Int>) : IntEntity(id) {
    companion object : IntEntityClass<Pet>(Pets)
    var name by Pets.name
    var owner by Owner referencedOn Pets.ownerId
}

val lines = transaction {
    Pet.all().with(Pet::owner)   // with() loads the owners eagerly for this call
        .map { "${it.name} belongs to ${it.owner.lastName}" }
}

DAO entities are mutable, and the transaction writes the changes made to them. A reference loads on first access unless with() loads it eagerly for that call, so Pet.all() with and without .with(Pet::owner) differ by one call and run a different number of statements. The eager loading tutorial compares the two approaches.

03The Storm way

In Storm a relation is part of the model. The data class declares the join once, and every query uses it:

Entities.kt Kotlin · Storm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// The data class maps the table and is the value a query returns
data class Owner(
    @PK val id: Int = 0,
    val firstName: String,
    val lastName: String,
) : Entity<Int>

data class Pet(
    @PK val id: Int = 0,
    val name: String,
    @FK val owner: Owner,   // the join is declared here, once
) : Entity<Int>

val pets = orm.entity(Pet::class)

val ofDavis = pets.findAll(Pet_.owner.lastName eq "Davis")

// The next query uses the same model and states no join
val namedLeo = pets.findAll(Pet_.name eq "Leo")
↳ generated sql
-- both queries derive the join and the column list from the model
SELECT p.id, p.name, o.id, o.first_name, o.last_name
FROM pet p
INNER JOIN owner o ON p.owner_id = o.id
WHERE o.last_name = ?

SELECT p.id, p.name, o.id, o.first_name, o.last_name
FROM pet p
INNER JOIN owner o ON p.owner_id = o.id
WHERE p.name = ?

The second query does not mention the join. Pet_.owner.lastName is a compile-checked path through the one declaration. On type safety the two libraries are even. The difference is in the count: joins and mappings written per query grow with the number of queries, while the model grows with the number of tables.

04Results are values

The DSL's mapped rows are plain values too; it is the DAO's entities that belong to their transaction. Storm returns immutable data classes without a mapping step:

PetService.kt Kotlin · Storm
1
2
3
4
5
6
7
// Results are immutable values
fun petsOf(lastName: String): List<Pet> =
    pets.findAll(Pet_.owner.lastName eq lastName)

// They depend on no session or transaction, so they can be serialized,
// cached or handed to another thread
val json = objectMapper.writeValueAsString(petsOf("Davis"))

Reads need no transaction { }: repositories take a connection per operation, and a transaction comes in where atomicity matters. Lazy loading exists in Storm as a type. A field declared Ref<Owner> holds the key, and loading the owner is an explicit fetch() call. The N+1 tutorial covers that model.

05Side by side

ExposedStorm
Type safetyCompile-checked column referencesCompile-checked metamodel paths
Model declarationsTable object plus row mapping (DSL), plus entity class (DAO)One data class per table
JoinsWritten per queryDeclared once via @FK, reused by every query
Results areRows to map, or mutable entities tied to their transactionImmutable values
ReadsInside transaction { }Without one; transaction { } where atomicity matters

06Keep going

The reference documentation covers the mechanics in depth: