Releases and Migration Notes

This document gives an overview of BHIMA software releases and migrations

Basics

The BHIMA sofware operates on two types of installations (or "sites" or "environment"): (1) production sites, and (2) test sites.

In most cases the BHIMA software that is installed on production servers is the latest released version. All production servers will receive and run the same BHIMA software. In some cases, installation of the software update may be delayed due to limited ability to access the remote systems involved.

The BHIMA software does most of its automated testing using a non-production test site called BHIMA Test.

Releases

As part of the normal development process for the BHIMA software, whenever a set of changes is complete and tested, a release is created. A release is defined as a set of the software parts of the BHIMA software that has been tested and verified that it works consistently in the test site. Releases have a release number such as 16.1.1.

A release generally includes bug fixes, new features, improved work-flows, and documentation. Once a release has been made, it is usually installed on each production site as soon as practical. The process of installing the updated software on production sites is called migration. Installing the updated BHIMA software on production sites is straightforward; it simply involves replacing the existing software with the newly released software. Updating the underlying database data is more complicated.

The database data (SQL) for each production site will vary. The primary setup of database tables and basic configuration data is the same for all installations, but each production site will have differences such as data about known users, patients, stock inventories, etc. So the process of updating the database for each production site will be somewhat different. Since we do not want to loose the data that the site already has about its local configuration, we use migrations.

Before describing migrations, it is useful to review how the database SQL files are structured.

Database SQL Data for BHIMA software

The BHIMA files defining the basic tables and data for the BHIMA software are in these files:

• server/models/*.sql

Key files are:

• server/models/schema.sql - Defines the database tables for the BHIMA installations
• server/models/bhima.sql - Adds data to the tables for basic BHIMA operations, menus, etc

The other files create functions and set up the database properly.

Note that the the schema.sql and bhima.sql are are only used to create the database data in BHIMA test environment or when creating a new production site. They are not used directly when migrating a production site (since they would destroy any existing data).

However, the two files schema.sql and bhima.sql are used when creating the BHIMA test environment database. Whenever we update the BHIMA test environment, the database data is completely created from scratch. Note that this means that migrations (as described below) do not apply to the BHIMA test site.

Migrations

Once a BHIMA release occurs, software development continues with updating the software--often including changes to database structure or contents. As each new change to the database is done, the schema.sql and bhima.sql files are updated so that the BHIMA test environment gets those changes for testing purposes. However, it is also necessary to add new changes to the database in the migration file:

• server/models/migrations/next/migrate.sql

The purpose of the SQL commands in this file is to capture the database changes that need to be applied to all production sites (when they eventually get upgraded).