Databases
Introduction
KOS provides a number of storage options, including database access via SQLite.
SQLite is a robust database implementation that has low overhead, is optimized for embedded systems, and utilizes simplified types. Java SQL support is quite complex to use directly, therefore KOS includes JDBI to simplify database access. This library provides a comprehensive set of functionality while also being very simple to use.
Upgrades and Rollbacks
One area of complexity around the use of a database is how to handle upgrades and rollbacks.
Upgrading a database involves updating the schema and modifying the data to get the database into the correct state for the new application code, and is a common need in most application development. Less common is the ability to rollback to an earlier version of the database in the event that current deployment is not stable. Given the complexity around these two use cases, KOS provides a built-in strategy for both migration and rollback.
Database migration is based on schema numbers. Each time the application code needs to change the schema, the schema number is incremented and code is added to migrate from the previous schema to the new schema.
When KOS opens a database, it automatically:
-
Detects changes in the schema number,
-
Copies the existing database, and then
-
Migrates the new copy to the latest schema.
Since the previous schema version still exists on disk, any rollback that looks for a previous version will find the old database file. So if a rollback occurs relatively soon after an upgrade, then the data in the database will tend to be up-to-date, and the rollback is generally seamless. The rollback can also optionally delete the newer schema database, so rolling forward will re-migrate the latest data.
To leverage this built-in KOS migration support, an application simply needs to provide a DatabaseMigrator implementation to the DatabaseFactory, which will return a DataSource to the migrated database. The migrator provides control over a number of migration and retention settings which allows the application fine-grained control over this policy.
For more detailed information about how to work with databases, see TODO page.
