GNUmed Server Upgrade

на русском языке

For those who may desire or require it, a somewhat comprehensive background to the GNUmed installation / upgrade process is available in the devel archive.

Upgrading a GNUmed database

Apply this method if you have an existing database with patient data which you wish to keep. Do not upgrade a production database based on release candidates, as revisions to the database structure would not have been finalized until the official release, as a result of which any additions or changes made to patient data (if this had been done in a "release candidate" versioned database) would be lost if an official upgrade is then performed on the last official-versioned production database.

GNUmed will upgrade any earlier database in single-steps only, say, from v10 to v11, with multiple single steps able to be done in series. There is no way to skip any steps. During the upgrade, an existing database will be cloned, and the new database generated from the clone. The original database will remain entirely unscathed. Also, during upgrade, GNUmed will attempt to produce a timely backup (which can be a bit costly in time and disk-space) for safekeeping of your precious data. Nevertheless, it is a wise idea to keep a second, independently acquired, recent backup around, as outlined at Data Backup and Restore procedures, just in case.

To allow the bootstrapper to generate backups in the course of applying upgrades, ensure that the following line has already been configured into the appropriate position in pg_hba.conf as per the topic ConfigurePostgreSQL:

Before applying an upgrade

You can know what versions of GNUmed database exist in the server's cluster by logging into psql (for example with psql -d gnumed_v16 -U gm-dbo) and, from within the session, issuing \l to list the existing databases including the major database version(s) of GNUmed.

You next need to keep in mind two groups of requirements:

  1. In order for any upgrade to be successful:
    • it must be applied as root (or via sudo) AND
    • no users can be connected to the database while it is being upgraded
    • the existing database tables and column names and types must match the known, official-release fingerprint 'hash' for that version
      • the latter can be found in [...]/client/pycommon/gmPG2.py
      • the full reference fingerprint can be found in [...]/server/sql/vXX-vYY/gm_db-gnumed_vXX-fingerprint.txt
      • the fingerprint of the to-be-upgraded database can be generated from the python script in [...]/server/ using ./gm-fingerprint_db.py <gm-dbo-password> e.g. ./gm-fingerprint_db.py gnumed_v16 gm-dbo
  2. For "production" (real-use) databases
    • you are hereby warned to refer to the precautions that are detailed below (see "A final… ")

Generic local upgrade (multi-version, Linux, MacOSX)

Use the upgrade-db.sh script available from the server tarball or VCS tree like this:

upgrade-db.sh N N+1 where

Before you would do this from a copy of the VCS, check (ls -al) to ensure that the symlink Gnumed from within .../gnumed/gnumed/ (same level as client directory) points to client/ (that is: .../gnumed/gnumed/Gnumed -> .../gnumed/gnumed/client/).

Example of single-step upgrading e.g. gnumed_v10 to gnumed_v11: 
sh upgrade-db.sh 10 11

The versions must be consecutive. Repeat from the relevant starting version (your most recent production version), until the desired version is reached e.g. 
...
upgrade-db.sh 8 9
upgrade-db.sh 9 10
upgrade-db.sh 10 11
...

Debian/Ubuntu: standard upgrade using debian packages

Make sure you've got the gnumed-server package installed that you want to upgrade to. Use apt-cache policy gnumed-server to check. Note that just having the appropriate package installed does not mean your database has been upgraded to the new version yet. This is so that you can decide when to actually upgrade the database.

When time has come to upgrade as root run the following command (which will already have been installed by the gnumed-server package):

gm-upgrade_server N N+1

where

just like in the generic upgrade procedure (in fact, the above command is but a convenient wrapper around the generic approach).

Debian, (*)buntu, SuSE, Mandriva: net upgrade

This script will only upgrade from the previous to the current official release (and, again, it is just a convenient wrapper around a generic upgrade).

Windows

Introduced with the server software (beginning with v7 database) are database upgrade scripts selectable from the Windows Start menu. Naturally, they are just pretty links to the very same procedure described above.

A final, but important, production note

Since old versions of the client will continue to grant access to the old database, you definitely do not want new clinical entries or clinical revisions to be split between two databases and the same goes for any importers at risk of continuing to import data into the old database. Accordingly, in preparation for migrating your production database,

Applying bug fixes to in-production databases

Despite the utmost care it will be necessary to apply a bug fix SQL script to a running database from time to time. Such scripts are provided in the server/sql/vN_vN+1/fixups/ directory of a GNUmed-server.vN+1.x package (say, GNUmed-server.v9.2). To apply them use the server/bootstrap/fixup-db.sh script. Your package maintainer may also have installed a shortcut gm-fixup_server for your convenience.

To apply fixups manually follow those steps on the database host (assuming v9.2):

This will apply all the bug fixes, and will also log (in the table gm.schema_revision) the filenames of the scripts which have been run. In case of trouble feel free to ask on the mailing list. Note that fixup scripts will be prepared only for fixes that follow official releases (not during the process of release candidates). This is one reason for the warning to not upgrade a production database using release candidates, above.