gnumed-doc 1.1.7-1 / usr / share / doc / gnumed / user-manual / GmManualServerUpgrade.html

<h1><a name="GNUmed_Server_Upgrade"></a>  GNUmed Server Upgrade </h1>
<p />
<div class="twikiToc"> <ul>
<li> <a href="#Before_applying_an_upgrade"> Before applying an upgrade</a>
</li> <li> <a href="#Generic_local_upgrade_multi_vers"> Generic local upgrade (multi-version, Linux, MacOSX)</a>
</li> <li> <a href="#Debian_Ubuntu_standard_upgrade_u"> Debian/Ubuntu: standard upgrade using debian packages</a>
</li> <li> <a href="#Debian_buntu_SuSE_Mandriva_net_u"> Debian, (*)buntu, SuSE, Mandriva: net upgrade</a>
</li> <li> <a href="#Windows"> Windows</a>
</li> <li> <a href="#A_final_but_important_production"> A final, but important, production note</a>
</li> <li> <a href="#Applying_bug_fixes_to_in_product"> Applying bug fixes to in-production databases</a>
</li></ul> 
</div>
<p />
For those who may desire or require it, a somewhat comprehensive background to the GNUmed installation / upgrade process is available in the <em>devel</em> <a href="http://lists.gnu.org/archive/html/gnumed-devel/2010-01/msg00002.html" rel="nofollow" target="_top">archive</a>.
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="Upgrading_a_GNUmed_database"></a>  Upgrading a GNUmed database </span></h2>
<p />
Apply this method if you have an existing database with patient data which you wish to keep. Do <strong>not</strong> 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 <em>official-versioned</em> production database.
<p />
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 <a href="GmManualDatabaseBackupRestore.html" class="twikiLink">Data Backup and Restore procedures</a>, just in case.
<p />
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 <code>pg_hba.conf</code> as per the topic <a href="ConfigurePostgreSQL.html" class="twikiLink">ConfigurePostgreSQL</a>:
<p /> <ul>
<li> <code>local &nbsp; samegroup &nbsp; +gm-logins &nbsp; md5</code>
</li></ul> 
<p />
<h3><a name="Before_applying_an_upgrade"></a> Before applying an upgrade </h3>
<p />
You can know what versions of GNUmed database exist in the server's cluster by logging into psql (for example with <code>psql -d gnumed_v16 -U gm-dbo</code>) and, from within the session, issuing <code>\l</code> to <em>list</em> the existing databases including the major database version(s) of GNUmed.
<p />
You next need to keep in mind two groups of requirements:
<p /> <ol>
<li> In order for any upgrade to be successful: <ul>
<li> it must be applied as <em>root</em> (or via <em>sudo</em>) AND
</li> <li> no users can be connected to the database while it is being upgraded
</li> <li> the existing database tables and column names and types must match the known, official-release fingerprint 'hash' for that version <ul>
<li> the latter can be found in [...]/client/pycommon/gmPG2.py
</li> <li> the full reference fingerprint can be found in [...]/server/sql/vXX-vYY/gm_db-gnumed_vXX-fingerprint.txt
</li> <li> the fingerprint of the to-be-upgraded database can be generated from the python script in [...]/server/ using <code>./gm-fingerprint_db.py <database> &lt;gm-dbo-password&gt;</code> e.g. <code>./gm-fingerprint_db.py gnumed_v16 gm-dbo</code>
</li></ul> 
</li></ul> 
</li> <li> For "production" (real-use) databases <ul>
<li> you are hereby <strong>warned</strong> to refer to the precautions that are detailed below (see "A final&#8230; ")
</li></ul> 
</li></ol> 
<p />
<h3><a name="Generic_local_upgrade_multi_vers"></a> Generic local upgrade (multi-version, Linux, MacOSX) </h3>
<p />
Use the <code>upgrade-db.sh</code> script available from the server tarball or VCS tree like this:
<p />
<code>upgrade-db.sh N N+1</code> where
<p /> <ul>
<li> <code>N</code>: existing database version you want to upgrade from
</li> <li> <code>N+1</code>: database version you want to upgrade to
</li></ul> 
<p />
Before you would do this from a copy of the VCS, check (<code>ls -al</code>) to ensure that the symlink <code>Gnumed</code> from within <code>.../gnumed/gnumed/</code> (same level as <code>client</code> directory) points to <code>client/</code> (that is: <code>.../gnumed/gnumed/Gnumed -&gt; .../gnumed/gnumed/client/</code>).
<p />
Example of single-step upgrading e.g. gnumed_v10 to gnumed_v11:
<pre>
sh upgrade-db.sh 10 11
</pre> 
<p />
The versions <strong>must</strong> be consecutive. Repeat from the relevant starting version (your most recent production version), until the desired version is reached e.g.
<pre>
...
upgrade-db.sh 8 9
upgrade-db.sh 9 10
upgrade-db.sh 10 11
...
</pre>
<p />
<h3><a name="Debian_Ubuntu_standard_upgrade_u"></a> Debian/Ubuntu: standard upgrade using debian packages </h3>
<p />
Make sure you've got the <code>gnumed-server</code> package installed that you want to upgrade to. Use <code>apt-cache policy gnumed-server</code> 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 <strong>decide</strong> when to actually upgrade the database.
<p />
When time has come to upgrade as <code>root</code> run the following command <em>(which will already have been installed by the <code>gnumed-server</code> package)</em>:
<p />
<code>gm-upgrade_server N N+1</code>
<p />
where
<p /> <ul>
<li> <code>N</code>: existing database version you want to upgrade from
</li> <li> <code>N+1</code>: database version you want to upgrade to
</li></ul> 
<p />
just like in the generic upgrade procedure (in fact, the above command is but a convenient wrapper around the generic approach).
<p />
<h3><a name="Debian_buntu_SuSE_Mandriva_net_u"></a> Debian, (*)buntu, SuSE, Mandriva: net upgrade </h3>
<p /> <ul>
<li> download the <a href="http://gitorious.org/gnumed/gnumed/blobs/master/gnumed/gnumed/server/gm-net_upgrade_server.sh" rel="nofollow" target="_top">network-based upgrade script</a>
</li> <li> make sure the file is executable
</li> <li> as <em>root</em> or with <em>sudo</em>, run the file <code>net_upgrade-gnumed_server.sh</code> <ul>
<li> yes, system-wide package installation is typically done as root
</li> <li> you may want to inspect the file for bogosities, before running it
</li></ul> 
</li></ul> 
<p />
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).
<p />
<h3><a name="Windows"></a> Windows </h3>
<p />
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.
<p />
<h3><a name="A_final_but_important_production"></a> A final, but important, production note </h3>
<p />
Since old versions of the client will continue to grant access to the old database, <strong>you definitely do not want new clinical entries or clinical revisions to be split between two databases</strong> and the same goes for any importers at risk of continuing to import data into the old database. Accordingly, in preparation for migrating your <strong>production</strong> database,
<p /> <ul>
<li> ensure that you have available suitably-configured copies of the client for the new production database
</li> <li> backup, and then insert a suitable logon banner into, the about-to-be-upgraded database
</li> <li> stop any and all importers, and point them to the about-to-be new database
</li> <li> upgrade the old database, resulting in a cloned "new" database
</li> <li> modify the logon banner of the new database
</li> <li> restart any and all importers
</li> <li> 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
</li></ul> 
<p />
<h3><a name="Applying_bug_fixes_to_in_product"></a> Applying bug fixes to in-production databases </h3>
<p />
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 <code>server/sql/vN_vN+1/fixups/</code> directory of a GNUmed-server.vN+1.x package (say, <em>GNUmed-server.v9.2</em>). To apply them use the <code>server/bootstrap/fixup-db.sh</code> script. Your package maintainer may also have installed a shortcut <code>gm-fixup_server</code> for your convenience.
<p />
To apply fixups manually follow those steps on the database host (assuming v9.2):
<p /> <ul>
<li> take a backup of your database just for good measure
</li> <li> log into your database machine
</li> <li> make sure you can connect to <em>gnumed_v9</em> as <em>gm-dbo</em> <ul>
<li> test: <code>psql -d gnumed_v9 -U gm-dbo</code>
</li></ul> 
</li> <li> go to the (on Debian, /var/lib/gnumed/...) <code>server/sql/v8_v9/fixups/</code> directory
</li> <li> in each file, change the line <ul>
<li> <code>--set default_transaction_read_only to off;</code> to <code>set default_transaction_read_only to off;</code> (IOW, remove the <code>--</code>)
</li></ul> 
</li> <li> for each script provided run: <ul>
<li> <code>psql -d gnumed_v9 -U gm-dbo -f script_name</code>
</li> <li> sometimes some files need to be run in a specific order, details are provided in the release notes
</li></ul> 
</li></ul> 
<p />
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 <strong>not</strong> upgrade a production database using release candidates, above.
<p />
<hr />
<p />
<hr />