Ktorm v3.1.0 Release Notes

Release Date: 2020-09-19 // about 1 month ago
  • ⬆️ Upgrade to Kotlin 1.4

    ⬆️ To use the new features of Kotlin, we've upgraded its version to 1.4.10, which brings some changes to us:

    Explicit API mode to ensure we don't expose some internal things accidentally.

    👍 Contract support for database.useConnection { .. } & database.useTransaction { .. } to let the compiler know our callback functions are called in place exactly once.

    🗄 Deprecation of mapColumnsN & aggregateColumnsN functions. As Kotlin 1.4 supports overload resolution by lambda return type, we don't need these functions anymore, mapColumns & aggregateColumns is enough.

    database.employees .filter { it.departmentId eq 1 } .mapColumns { tupleOf(it.id, it.name) } .forEach { (id, name) -\>println("$id:$name") }
    

    ⚡️ Entity Based Update Function

    In Ktorm 3.1, we provide an update function that can update all the non-null properties of an entity object to the database. Using this function, the entity object is not required to be associated with a table first. That means, comparing to flushChanges, we don’t have to obtain an entity object from the database first before performing the update. The usage is as follows:

    val employee = Employee { id = 5 job = "engineer" salary = 100} database.employees.update(employee)
    

    Generated SQL:

    update t\_employee set job = ?, salary = ? where id = ?
    

    ♻️ Syntax Refactoring of Insert & Update DSL

    Previously, we inserted a record into the table like this:

    database.insert(Employees) { it.name to "jerry" it.job to "trainee" it.managerId to 1 it.hireDate to LocalDate.now() it.salary to 50 it.departmentId to 1}
    

    Here, we used it.name to "jerry" to set the name to jerry in the closure. And the to function is a member of AssignmentsBuilder, but not the to function used to create Pair instances of Kotlin standard lib.

    🚚 It is very easy for users to get confused with these two functions, so in Ktorm 3.1, we provide another set function as an alternative. The to function is marked deprecated and will be removed in the future. You can learn the new syntax here https://ktorm.liuwj.me/en/dml.html

    database.insert(Employees) { set(it.name, "jerry") set(it.job, "trainee") set(it.managerId, 1) set(it.hireDate, LocalDate.now()) set(it.salary, 50) set(it.departmentId, 1) }
    

    🛠 Other Optimizations and Bug Fixes

    • ➕ Add ShortSqlType. #160
    • ➕ Add MySQL IF function. #163
    • 👌 Support mixed-case column names & auto case transform. #175
    • 👍 Allow specify PostgreSQL insertOrUpdate conflict columns. #181
    • 👌 Support select .. for update. #69
    • 👌 Support catalog & schema in table definition. #89, #154, #183
    • Check max column name length. #122
    • 🛠 Fix timestamp fraction bug. #130
    • ⚡️ Update the syntax of defining JSON columns from json("foo", typeRef<List<Int>>) to json<List<Int>>("foo").

Previous changes from v3.0.0

  • Some break changes in Ktorm 3.0:

    • 🚚 Completely remove the deprecated global database APIs and provide equivalent things in a new module ktorm-global.
    • 👉 Use = instead of property delegation to define columns.
    • Query doesn't implement Iterable anymore.
    • 👌 Support compound primary keys.

    ⚡️ In addition to the break changes above, there are also many updates from enthusiasts in the open source community, thanks for their contributions:

    • ⚡️ MySQL bulkInsert function supports on duplcate key update. Thank @hangingman
    • PostgreSQL hstore data type and a series of operators for it. Thank @arustleund
    • 👍 ktorm-jackson supports simple Jackson annotations, like @JsonProperty, @JsonAlias, @JsonIgnore. Thank @onXoot

    👀 For more details about the new version, see https://ktorm.liuwj.me/en/break-changes-in-ktorm-3.0.html