Client Database Model

2019 status: Current

Summary

The Buendia client caches data it retrieves from the server in a local SQLite database. This document describes the structure of this database as well as how the database is accessed.

Database Structure

The database schema is defined in the PatientDatabase class using the SQLiteOpenHelper interface. PatientDatabase defines the following tables:

• patients: Information about patients that is rarely changed (name, age, sex)
• concepts: The set of OpenMRS concepts that the application will support, and the datatype of each concept
• concept_names: Localized names of OpenMRS concepts, mapping to concepts in the concepts table
• locations: The set of locations to be displayed in the app, including a field indicating parent location, so that we can construct a tree of related locations; currently, we make the assumption that there is a single root which represents a single treatment center
• location_names: Localized names for the locations in the locations table observations: The set of observations for all patients, where each row is a single observation for a single concept (e.g. one row may be a pulse measurement for a particular patient at a particular time)
• charts: The set of charts provided by the server that are relevant to the app, where each chart contains one or more ordered concept rows; this is used to determine what observations to retrieve in the patient chart activity and the order in which to display them
• users: User names and ids shown on the initial login screen
• misc: A table for storing miscellaneous values, with just one row, and a column for every field to be stored

For an up-to-date listing of the fields in each table, refer directly to the PatientDatabase class.

Database Access

Database access is encapsulated through the use of a ContentProvider. Classes requesting data from the database (which could, in theory, include other applications) request content using a ContentResolver, specifying a URI defined in the Contracts class. See URI's in the Contracts class for a full list of available URI's and corresponding fields.

BuendiaProvider is the primary ContentProvider for the application, which delegates requests to individual classes implementing the ProviderDelegate interface. All the ProviderDelegates are registered in the BuendiaProvider's getRegistry method. Each ProviderDelegate provides some subset of query, insert, bulk insert, delete, and update operations, throwing an UnsupportedOperationException for any unsupported operation.

Database Updates

PatientDatabase will "upgrade" an existing client database if the DATABASE_VERSION increases as the result of an application update, by dropping the entire database and creating a new, empty database with the new schema. This is inefficient but safe, as the database will be repopulated with server data the next time a user logs in.