
Automatic Update Application
Karen Pease (karen-pease@uiowa.edu
------------------------------------

PURPOSE:

In order to upgrade the capabilities of the HID and to enable it to handle
changes in external applications, periodically changes must be made.
Traditionally, these have been sent out in update patches to the email list.
It was essential that all of these be caught and applied in the right order.
Versioning information in the database was not updated, and there was no easy
way to tell what patches had been applied.  This caused some applications to
mysteriously fail in the case of missing updates.

In order to remedy this situation, the automatic update system was
proposed.

PREPARATION:

This process requires that the user's database be updated manually with one
last script.  Please run AutoupdateSchemaChanges.sql in sqlplus before
continuing.  You should be fully patched before starting.

UPDATE CREATION:

When an update to the database is created, the author first thoroughly tests it
on their own.  When they are ready to give it to the general group, they run
create_update.sh as follows:

./create_update.sh UpdateFileName.sql

"cvs update" is called to make sure that the script knows what updates already
exist.  The script then asks you whether this is a MAJOR version increase or a
MINOR version increase.  In general, patches will represent a minor version
increase.  It then asks you for the name of the update; this will be used in
the filename.

If an update already has that name, the script asks if you want to upgrade the
existing update patch.  The update has its internal version number incremented,
and all of the remaining data is overwritten.  If you say that you don't want
to do this, the script exits.

The user is lastly prompted to enter a description.  This, along with metadata
like the current date (as the release date) is added to the update patch.
Additionally, a validation/versioning header and footer are added to the script.
The header makes sure that the database is the version right before the patch,
and inserts a row into nc_schemaversion stating that the patch is starting.
The footer inserts a row that the patch is completed.  It does all of these
actions via function calls, so that the script is independent of the actual
structure of nc_schemaversion.  If nc_schemaversion ever changes, the function
calls should be updated accordingly.

The script lastly prompts you to cvs add and commit the file.  Please do this
promptly.

UPDATE USAGE:

In order to update to a given version (lets say, 2.5), the database admin runs:

./apply_updates.sh TheirSqlplusConnectionString 2.5

The script iterates through all available patches sequentially in order from
the current schema version up to the version that you specify.  If there ever
is an error, the update *stops*.  Due to Oracle limitations, as there is no way
to automatically roll back a patch, the patch must be manually rolled back.
Please consult the patch author if you are unsure how to do this.



