The beauty of an upgrade framework

Today we upgraded HostedQA, which required the schema to be changed a bit. It is a time like this that the value of an automated upgrade framework really pays off.

INFO: Looking up upgrade class com.hostedqa.upgrade.UpgradeToBuild1
INFO: Upgrading to build 1…
INFO: Upgrade to build 1 SUCCESS
INFO: Looking up upgrade class com.hostedqa.upgrade.UpgradeToBuild2
INFO: Upgrading to build 2…
INFO: Upgrade to build 2 SUCCESS
INFO: Looking up upgrade class com.hostedqa.upgrade.UpgradeToBuild3
INFO: Upgrading to build 3…
INFO: Upgrade to build 3 SUCCESS

Simply using something like Hibernate’s schema update utilities isn’t good enough. It takes you from step A to Z without giving you an opportunity to make iterative changes to the data, as I had to do today. To really make software easy to deploy, you need to streamline the upgrade process to be trivial while also automating upgrades from any arbitrary version to any other arbitrary version.

Part of doing that is building an upgrade framework that will handle changing your data using a combination of Java code and SQL. The reason you need both is because sometimes there is complex logic that is required to shuffle data around. Again, today we had that very need so simple SQL scripts wouldn’t suffice.

Word is that Jive Software has a pretty sweet upgrade framework in their latest version of Jive Forums. I think more software needs to take the approach that HostedQA, JIRA, Confluence, and Jive Forums do: make upgrades painless by investing in a upgrade framework.

Not just for enterprise software

Because HostedQA is, well, hosted, it doesn’t really need an upgrade framework as much as the other enterprise software listed do. Atlassian has been doing this for years (though I don’t think theirs is advanced as it could or should be). However, we invested in the framework anyway because we believe that not only is it nice for customers, it makes development easier.

How many times has an engineer in your team sent out an email along these lines:

Gang,
I recently made some pretty big changes to the whiz_bang table. You’ll need to add these 3 columns to your local database before you can use the latest code checked in to SVN. Sorry about the trouble!

Bob

I’ve seen this all the time. It’s a problem because it puts a larger burden on good communication when a simple automatic solution is readily available with very limited development. If your team had an upgrade framework, “Bob” wouldn’t have to send out an email and depend on each team member reading the email and correctly executing his recommended steps. In short: it eliminates room for human error during development.

So I recommend making an upgrade framework core to any application. Enterprise software? Definitely. Hosted applications, like HostedQA? Absolutely. Internal applications? Why not! It is a big win all around and requires very little effort to get a basic framework in place.

Restrictions on your framework

One word of advice if you decide to add an upgrade framework to your application, do not depend on your OR framework (ie: Hibernate) to update the schema. As mentioned previously, it doesn’t give you the opportunity to take the iterative steps needed when upgrading from very old builds/versions. It also doesn’t give you the opportunity to execute Java code to populate data as the schema changes, which often is required.

On top of that, don’t make your upgrade scripts (such as the class UpgradeToBuild2, as seen in the HostedQA logs) depend on much of your application. If you can, avoid calling any of your APIs and stick to straight JDBC. Even better, make your upgrade framework a standalone project so you can’t get caught doing something like that.

The reason? Simple: your code will change over time. Suppose in Whizbang Version 1.0 your FooService understood that the foo table had three columns and mapped it to Foo objects appropriately. Then in Version 2.0, you write an upgrade task that uses FooService to do some data manipulation. Then in Version 3.0, you change the foo table to have two additional columns.

Now imagine someone upgrades from Version 1.0 to Version 3.0 by dropping in whizbang.war to their webapps directory. When the Version 2.0 upgrade task runs, it will run the FooService that was built for Version 3.0 (the one that assumes there are five columns instead of three). Of course, the Version 3.0 schema changes haven’t been executed yet, and so the FooService will fail with SQL query errors.

So by avoiding your APIs and OR mapping frameworks and sticking to straight JDBC, you can make a truly robust upgrade framework that benefits customers, developers, sales, and support. It’s truly a win-win for everyone!

Advanced upgrade framework features

HostedQA’s upgrade framework, like Atlassian’s, is pretty simplistic: it runs and if there is an error it stops. There are opportunities to make the end user experience better if you’re willing to invest a little extra time.

Jive went ahead and made their upgrade framework prompt the user that an upgrade needs to take place (asking the user for the admin password before proceeding). Then, when any error happens, the individual task that failed is reported to the user and manual upgrade steps are presented. The user can stop the upgrade at that point and call support or do the manual steps and continue the upgrade.

This type of stuff is great for users of your software, but typically isn’t required for software like HostedQA or internal-only applications. But if you’re writing enterprise software, you might want to take your upgrade framework one step further and implement something like what Jive has. Your users and your support team will thank you!

Update 8/4/2006:

A few follow up blog entries

• Don Brown implements one in Spring
• InfoQ picks up this story and has some good comments
• Mark Derricutt blogged about this a few months ago and has some example code