Tutorials/Exposed vs Storm: schema

Who owns the schema

Exposed can create the schema from code, which helps on the first day of a project. Storm leaves the schema to the database and your migrations, and checks that the entities still match it.

Series · Exposed to Storm4 min readKotlin

01The task

Two moments in a project. On day one you want the tables to exist. In year two the schema holds production data, migrations change it, and the risk is that the code and the database disagree about a column.

02The Exposed way

Exposed's table objects describe the columns and their types, so they can create the schema:

Setup.kt Kotlin · Exposed
1
2
3
4
// The table objects describe the columns, so they can create the tables
transaction {
    SchemaUtils.create(Cities, Users)
}

For prototypes, tests and a new project this is convenient, and Storm has no equivalent: it does not generate DDL. For later changes, MigrationUtils in the exposed-migration modules generates the statements a schema change needs; teams usually feed them into a migration tool such as Flyway or Liquibase. The table objects stay a second description of the schema, next to the migrations.

03The Storm way

In Storm the schema that your migration tool builds is the source of truth, and entities describe it. The Ktor plugin runs the migration and then validates the entities against the result:

Application.kt Kotlin · Storm + Ktor
1
2
3
4
5
6
7
install(Storm) {
    // runs before validation, so validation sees the migrated schema
    migration { dataSource ->
        Flyway.configure().dataSource(dataSource).load().migrate()
    }
    schemaValidation = "fail"   // "none", "load", "warn" or "fail"
}

fail is the default in Ktor and Spring Boot, so the check runs at startup without configuration. It reports tables and columns that do not exist, incompatible types, nullability mismatches, primary and foreign keys that differ from the entity, missing sequences, and NOT NULL columns without a default that no field maps. Constraints the entity declares but the database lacks are warnings; a unique index counts as the constraint behind a @UK field. An entity can map to a table, a view, a materialized view or a partitioned table.

strict turns the warnings into errors. Set it in application.conf, or under storm.validation in Spring Boot, where the mode is schema-mode:

application.conf HOCON · Storm
1
2
3
4
5
6
7
# application.conf
storm {
    validation {
        schemaMode = "fail"
        strict = true   # warnings fail validation too
    }
}

Outside the integrations, the same checks are methods on the template:

Startup.kt Kotlin · Storm
1
2
3
4
// Without the Ktor or Spring Boot integration, call it yourself
val errors: List<String> = orm.validateSchema()
orm.validateSchemaOrThrow()   // throws PersistenceException listing the errors
orm.loadSchema()             // reads the schema for advice, without validating

Validation also keeps the schema it read, indexes included, and Storm uses it to advise on a slow statement that no index serves. "load" reads the schema at startup without validating it. The advice tutorial shows what that adds. To catch drift before it ships, run validation in a test against the migrated database: @StormTest runs your schema scripts, on H2 or in a container of the database you deploy on.

04The trade

ExposedStorm
Creating the schemaSchemaUtils.create(...) from table objectsYour migration tool; Storm does not generate DDL
Changing the schemaMigrationUtils generates statements; a migration tool applies themYour migration tool; the entities follow
Checking the mappingMigrationUtils lists the statements that would align the database; a check you writeValidation at startup by default, validateSchemaOrThrow() elsewhere
Source of truthThe table objects, until migrations take overThe database

If a project spends most of its time as a prototype, Exposed's schema generation is the better workflow. Storm assumes a schema spends most of its life under migrations, and checks the mapping against it on every start.

05Keep going

The reference documentation covers the details: