GNUmed Server Upgrade

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 when having to perform the official upgrade from what was supposed to have been kept your production database.

GNUmed will upgrade the database in single steps only, say, from v10 to v11. 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:

• local   samegroup   +gm-logins   md5

Before applying an upgrade

You 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
2. For "production" (real-use) databases
   • you are hereby warned to refer to the precautions that are detailed below (see "A final… ")

Multi-version (v9 --> v11), generic Linux, MacOSX: local upgrade

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

upgrade-db.sh N N+1 where

• N: existing database version you want to upgrade from
• N+1: database version you want to upgrade to

Example upgrading the gnumed_v10 to gnumed_v11:

sh upgrade-db.sh 10 11

The versions must be consecutive. Repeat until the desired version is reached e.g.

...
upgrade-db.sh 8 9
upgrade-db.sh 9 10
upgrade-db.sh 10 11
...

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

• download the network-based upgrade script
• make sure the file is executable
• as root or with sudo, run the file net_upgrade-gnumed_server.sh
  • yes, system-wide package installation is typically done as root
  • you may want to inspect the file for bogosities, before running it

This script will only upgrade from the previous to the current official release.

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,

• ensure that you have available suitably-configured copies of the client for the new production database
• backup, and then insert a suitable logon banner into, the about-to-be-upgraded database
• stop any and all importers, and point them to the about-to-be new database
• upgrade the old database, resulting in a cloned "new" database
• modify the logon banner of the new database
• restart any and all importers
• depending if it is desired to keep the old database available, reconfigure it to not allow any further connections and/or remove or control the copies of the client that would point to it

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):

• take a backup of your database just for good measure
• log into your database machine
• make sure you can connect to gnumed_v9 as gm-dbo
  • test: psql -d gnumed_v9 -U gm-dbo
• go to the (on Debian, /var/lib/gnumed/...) server/sql/v8_v9/fixups/ directory
• in each file, change the line
  • --set default_transaction_read_only to off; to set default_transaction_read_only to off; (IOW, remove the --)
• for each script provided run:
  • psql -d gnumed_v9 -U gm-dbo -f script_name
  • sometimes some files need to be run in a specific order, details are provided in the release notes

This will apply all the bug fixes. 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.