Client Database Model

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 expected to be immutable or, at the very least, rarely changed -- name, age, etc.
• 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
• misc: a table for storing miscellaneous values persistently; it is expected to have at most one row, and each value is represented by a single column

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.

MsfRecordsProvider is the primary ContentProvider for the application, which delegates requests to individual classes implementing the ProviderDelegate interface. 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 current database and recreating it, including any changed fields or tables. This should be a safe operation, as the database will be repopulated with server data the next time a user logs in.

Future Improvements

Improve database security

Currently, the database is secured by a password that is the same for all sites. In the future, this should be replaced by a proper key management policy.