Core concepts

Row

Describes a row from the database. It is essentially a tuple of data, but we also store some metadata about each column, such as its name, type and initial Kotlin class.

Row exposes the generic get<T>(column) and getOrNull<T>(column) methods, which can be used to fetch data from a column.

Mikrom supports adding type converters, so that you can work with i.e. java.time.Instant even though it'll be stored as a java.sql.Timestamp in the database. There are default converters stored added for relevant platform types, but you can also pass your own.

val mikrom = Mikrom {
  registerConverter<String, Int> { it.toIntOrNull() ?: error("Expected String $it to be convertible to Int") }
  // can be called multiple times to register further converters.
}

RowMapper

Describes how to map a Row to a Kotlin class. Can be manually created by using registerRowMapper in the Mikrom DSL:

val mikrom = Mikrom {
  registerRowMapper<Foo> { row ->
    Foo(
      row.get<String>("bar")
    )
  }
}

ParameterMapper

Use structured query types with parameter mappers!

Should probably primarily be generated by the compiler plugin, but you can also manually create it.

data class SearchBooksByNumberOfPages(val minPages: Int)

val mikrom = Mikrom {
  // Again, this can be auto-generated based on your data class using the compiler plugin.
  registerParameterMapper<SearchBooksByNumberOfPages> { request ->
    mapOf("minPages" to request.minPages)
  }
}

dataSource.transaction {
  mikrom.queryFor<Book>(
    "SELECT * FROM books WHERE number_of_pages > :minPages",
    SearchBooksByNumberOfPages(320),
  )
}