Skip to content

Releases and Migration Notes

Jump to bottom
Jonathan Cameron edited this page Jan 4, 2022 · 21 revisions

This document gives an overview of BHIMA software releases and migrations

Basics

The BHIMA software 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 name/number such as v1.16.0.

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 lose 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 common 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 with the next release).

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

  • 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.

Migrating Test Environents for Production sites

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

  • Export the current SQL database data from the production site. It is important to dump binary data as a hex (--hex-blob) and to preserve the functions/triggers/stored procedures (--routines). Once this data has been exported, it should be built locally to run the migration script on. 
     mysqldump -u $USER -p$PASS $DATABASE --compress --add-drop-database --add-drop-table \
   --single-transaction --hex-blob --complete-insert \
   --disable-keys --quick --routines > production.sql
  • Install the new data on the database server being used in the testing 
     mysql -u $USER -p$PASS $DATABASE < production.sql
  • Edit the .env file to set the environment variable DB_NAME to the desired site database name (e.g., 'imck' for IMCK). Alternatively, pass the DB_NAME environmental variable in the call to yarn migrate as follows: DB_NAME=$DATABASE yarn migrate.
  • Run yarn migrate to produce a local file migrate-<site>.sql file containing the migration commands (from server/models/migrations/next/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 file and any files that match server/models/migrations/next/migrate-<site>.sql), where is the DB_NAME for the desired production site. This change allows site-specific migration database changes. Also note that the site-specific migration file will be inserted into the local version AFTER the basic migrate.sql file is included.
  • Execute these commands with your database server to update the site-specific test database to reflect the changes since the last release.

Migrating Production Sites

Once a release has occured, production sites can be upgraded by replacing the BHIMA software with the new version and the migrating the database.

First, the changes in the migration.sql in the release directory (e.g. server/models/migrations/v1.15.0-v1.16.0/) should be executed via the production sites database server to update the production site database. Then any site-specific migration files in that directory (which include the database name of that site) should be executed as well.

Clone this wiki locally