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 files 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 files 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).

When testing the changes with data from a production site, the migration files will be used. The process is as follows:

• Download the current SQL database data from the production site
• Install the new data on the database server being used in the testing
• Edit the .env file to set the environment variable DB_NAME to the desired site database name (eg, 'imck' for IMCK).
• Run 'yarn migrate' to produce a local file migrate-<site>.sql file containing the migration commands (from server/models/migrations/migrate.sql). NOTE:
  • In the past, all files in this directory ending in .sql would be included in 'yarn migrate'. This has changed (2020-11-11 in PR 5101) to include this specific files and any files that match server/models/migrations/migrate-<site>.sql), where is the DB_NAME for the desired production site. This change allows site-specific migration database changes.
• Execute these commands with your database server to update the site-specific test database to reflect the changes since the last release.

When a BHIMA software release is completed, the migration files will be moved into the directory for that specific release, eg:

• server/models/migrations/v1.15.0-v1.16.0/ and the server/models/migrations/migrate.sql file will be emptied, preparing for the next round of updates.