Background
Almost all applications require some kind of upgrade capability
because users do not like to lose data/configuration when
installing a newer version of your application. Between versions
the application may have made changes to
the database schema, structure of the configuration files and
directory structure. Therefore, an upgrade process has to convert the
existing data from the old format to the new format. This is often
a complex process. To make matters even more complicated, an
upgrade process may find the version of the installed application to be
1.0 and it is trying to upgrade it to version 10.0 and has to apply
all the changes spanning 10 releases.
As application developers, we typically wait until the last moment
to create upgrade scripts that migrate the data between one version
to another. Depending on the changes that has been made to the
application, this is a very complicated process since the developer(s)
creating the scripts have to remember or figure out the changes made during
the coding phase and create the necessary migration scripts.
Because the task is so complicated, it often results in buggy upgrade scripts
and the upgrade fails resulting in tense moments.
The Upgrader provides a framework and a tool using which application
developers can manage upgrades in a streamlined manner. The Upgrader
is a simple tool and can be used right out of the box. At the same
time, it can be extended easily in order to provide additional
functionality.
How does it work?
This section discusses how the tool works out of the box. As mentioned
earlier, the tool can be extended to provide additional functionality.
Tha aspect is discussed in the section -
Extending the Upgrader tool
.
- During the software development phase, when a developer identifies a
change that has an upgrade impact, he/she creates a patch script
for the upgrade. For example, while implementing a feature,
the developer determines that a column needs to be added to a table
in the database, he/she creates a SQL script containing an
"ALTER TABLE" statement. The file containing the script is named
following a naming convention described in the section -
Getting Started with the Upgrader
.
The developer
saves this script in the version control system along with the code
in a "patch" directory. Each of these scripts will be referred to as
patches from now on.
During the development life-cycle, many such
patches are added by the developers. The scripts may be SQL scripts
or ant scripts.
- During the packaging phase, the Upgrader tool and all the patches
created during the entire life of the product is bundled with the
distribution. In addition, a file called migration.properties
is also bundled. It contains database information and other
properties that are used during the installation/upgrade.
If the product is using an installer (RPM, Install Shield, etc.),
the post-installer script must be setup to run the Upgrader tool
using one of the invocation mechanisms discussed below in order
to upgrade the data.
Depending on the installer you are using, there may be a different
terminology used instead of "postinstaller". What we are referring to
as postinstaller here is a script that is run by an installer after
the new version of the software has been installed. If your
application is not using an installer, you will have to provide
instructions to the users to run the Upgrader tool manually.
- During the installation/upgrade phase, the Upgrader tool is run
either manually or by the installer. The Upgrader tool stores the
current patch level in a database table called - PATCHES
.
The database
connection information is stored in the migration.properties file as
explained above. When the Upgrader is run, it reads the current
level of the patch from the table. If the table does not exist,
it creates the table and sets the patch level to 0. Based on the
patch level saved in this table from an earlier installation/upgrade,
it determines the patch files that needs to be executed.
For example, if the patch level is 30, the tool knows that it
needs to execute patch scripts 31 onwards. It reads the
list of patches that is bundled and executes them sequentially.
At the end, it writes the current patch level to the PATCHES table.
This will ensure that next time, an upgrade is done, the upgrade
tool will start from the level set during this install/upgrade process.
Note that the Upgrader tool is invoked during upgrades as well as
during the initial installation because during the development
life-cycle, multiple patches may have been created and they need
to be installed. In fact, the first patch mostly deals with the
creation of database tables and the next patches deals with
altering the tables based on changes during the coding/testing
life-cycle.
Benefits
This upgrader tool and the associated conventions described above, ensure
that upgrade scripts are developed while in the development phase and not
left as the last task before the software is shipped. In fact, every time
a developer
updates his/her workspace from the code repository, he/she should execute
the Upgrader tool manually to update his/her development workspace.
This has two advantages:
- There is no need for separate instructions to be communicated to
the development team during the development phase when there
is a database changes, configuration file changes, etc. The
workspace of the developers are upgraded using this tool.
This there is less scope of error, confusion and time waste.
- Because the developers are running the Upgrade tool frequently during
the coding life-cycle, the patch scripts get tested thoroughly and
any bugs found in the patches are being eliminated. This results
in a better tested upgrade process.
The Upgrader tool automates the upgrade process and applications
don't have to worry about creating their own upgrade infrastructure.
In addition, if this tool is used from the start of a new application,
the upgrader can upgrade a installed application from any release to
any release.
Extending the tool
You can download and start using the tool right away if your needs are
simple. If you have an application that uses a database and your
upgrade involves running SQL scripts, you can use this tool from day one.
In addition, if you are ready to use Ant scripts to update the configuration
files and/or directory structure, you can also use this tool without
any modifications. But if you need to run stored procedures or other types
of shell scripts that the tool does not support, you can extend the tool
easily by providing custom
script runners that you can pass long to the main tool. We may include
some of these capabilities in an upcoming release or you can contribute
your custom script runner classes. Note that one of the reasons why we
have provided an Ant script runner is because, from an Ant
script, you can easily execute programs and other types of scripts that we
do not support out of the box.
For more details on the extension capability, read the section -
Extending the Upgrader tool
.
