KOS Developer's Portal

Database Intro

Introduction

One of the common requirements for applications is to store data persistently. The KOS SDK offers a convenient and reliable way to handle this task by enabling you to create, access, upgrade, downgrade, and manage one or more SQLite databases. You can use the KOS SDK to perform various operations on your databases, such as creating tables, inserting records, querying data, and updating or deleting records.

Overview

SQLite

SQLite is "a small, fast, self-contained, high-reliability, full-featured" SQL database engine.

Written in C, it is an "in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine".

SQLite does not have a separate server process. It reads and writes directly to ordinary disk files. A complete SQL database with multiple tables, indices, triggers, and views, is contained in a single disk file.

It is the most-used database engine in the world, running on all mobile phones, most computers and televisions, and is used by many millions of software applications.

Read all about SQLite on their website.

This page explains how the KOS SDK makes it easy to manage databases and their versioning.

API Components

Two main components are required to handle database creation and modifications:

DatabaseFactory (a KOS SDK class used to get a Java DataSource)
DatabaseMigrator (a KOS SDK interface used to generate your custom database migrator)

DatabaseFactory

For our current purposes, we’re interested in the getDataSource() method of the DatabaseFactory class.

API: DatabaseFactory class

public class DatabaseFactory {
    public DatabaseMigrator migrate(DatabaseMigrator migrator, String name, File dir) {
    }

    public DataSource getDataSource(DatabaseMigrator migrator, String name, File dir) {
    }

    public Jdbi getJdbi(DatabaseMigrator migrator, String name, File dir) {
    }
}

The method is:

getDataSource()

Creates a DataSource for the specified database file in the specified directory.
The supplied migrator will be used to migrate the database to the latest schema before the DataSource is finally returned.
If migration needs to occur, it will be performed with a temporary data source until everything is ready, and then setDataSource() is called on the migrator to indicate that things are stable and ready for use.

Database Migration

The database migration process ensures that the database schema matches what the code expects. This is executed every time the application starts. During this phase, the migrator does one of the following:

The database file does not exist, so the migrator creates it from scratch.
The code’s schema version is newer than the database’s, so the migrator updates the database.
The code’s schema version is older than the database’s, so the migrator rolls back to a previous database.
The code’s schema version matches the database’s schema version, so all is good: no action is taken.

Updating the database to a newer version is also called "rolling forward" or "roll-forward".

Downgrading the database to an older version is also called "rolling backward" or "rollback".

WARNING: Database Rollback

If the migrator rolls back to a previous database version, then ALL CHANGES TO THE DATA MADE SINCE THAT ORIGINAL DATABASE WAS UPDATED ARE LOST.

DatabaseMigrator

The DatabaseMigrator interface has methods that deal with database schema creation and modification. The two methods we’re focused on at the moment are getCurrentSchema() and migrateToSchema().

API: DatabaseMigrator interface

public interface DatabaseMigrator {

    int getCurrentSchema();

    default int getMinimumMigrationSchema() {
        return 0;
    }

    default int getMinimumRetentionSchema() {
        return 0;
    }

    default boolean purgeNewerSchema() {
        return true;
    }

    void migrateToSchema(Jbdi jbdi, int schema);

    default void setDataSource(DataSource datasource) {
    }

    default void setJdbi(Jdbi jdbi) {
    }
}

Summary

TODO