- App Store
Debugging Upgrade Errors
Upgrading xTuple ERP is fairly simple:
- Download the Updater application if you don't have it already.
- Download an upgrade package from this site or the PostBooks project SourceForge page.
- Launch the Updater.
- Open the upgrade package.
- Click Upgrade.
Unfortunately the process often gets hung up in this last step. Sometimes the Updater reports that the data have failed a prerequisite check. Less frequently an error occurs during the actual upgrading processing. If either of these happen then you have to either ask for support or try to figure out what went wrong on your own.
This page describes how to figure out what went wrong and how to learn more about the failure. You can learn more about some of the more common--and also version-specific--errors on the Common Upgrade Issues page.
Unpacking The Upgrade Package
Upgrade packages are compressed tar files. Therefore you'll need a program that can unpack compressed tar files to look at the contents of an xTuple ERP upgrade package. On Linux and Macintosh you can simply use the tar utility. On Windows your choices include WinZIP and the version of tar included in such environments as the MKS toolkit and Cygwin. From a Terminal window, the following command will unpack the contents of the package designed to upgrade a PostBooks database from release 2.3.0 to 2.3.1:
tar xzf pb230to231.gz
This will create a directory named 230to231 full of files and directories used in the upgrade processing.
Understanding The Upgrade Sequence
Upgrading is controlled by a simple XML file named package.xml (contents.xml in older upgrade packages). The general sequence is always the same:
- Check prerequisites - if any of the prerequisite checks fail then the upgrade will not be processed.
- Mark the upgrade as started - set a flag in the database.
- Load functions needed to alter table structures - this is rare but sometimes occurs.
- Alter existing tables - this step may create backup copies of existing tables and often populates new columns added to the existing tables.
- Create new tables.
- Create new stored procedures.
- Create new triggers.
- Create new views.
- Load new report definitions.
- Mark the upgrade as complete.
When upgrading between pre-releases, such as between an alpha release and a beta, package.xml will contain a single copy of this sequence. However, the packages that upgrade between full releases of the software, such as pb230to231.gz, may contain a single set of prerequisite checks followed by several sets of the other steps.
Prerequisite checks have the following structure:
A prerequisite XML tag - the name attribute of this tag is displayed in the Updater window.
A query tag - the content of this tag is a SQL query that gets executed. If the query returns a boolean true value then the upgrade is allowed to continue.
A message tag - if the query returns false then the upgrade will abort and the contents of the message tag will be displayed in the Updater window.
As examples the first prerequisites checked are the application and database versions:
<prerequisite type="Query" name="Checking PostBooks Server Version" > <prerequisite type="Query" name="Checking PostBooks Server" > <query>SELECT TRUE FROM metric WHERE metric_name = 'Application' AND metric_value='PostBooks';</query> <message>This package requires that it be applied against the PostBooks Server Database.</message> <query>SELECT TRUE FROM metric WHERE (metric_name = 'OpenMFGServerVersion') AND ((metric_value = '.2.3.0-2.3.1') OR (metric_value = '2.3.0'));</query> <message>This package requires that it be applied against the 2.3.0 version of the PostBooks Server Database.</message> </prerequisite>
If Updater reports a prerequisite check failure and you want to investigate further, unpack the upgrade package, search for the message in package.xml, and manually execute the query associated with that check.
Unlike the application and database version checks above, many queries look at the number of rows with match certain selection criteria and return false if any such rows exist:
<prerequisite type="Query" name="Checking for unset Item Active" > <query>SELECT COUNT(*)=0 FROM item WHERE (item_active IS NULL);</query> <message>One or more Item records are missing an Item Active setting</message> </prerequisite>
This example looks for rows in the item table that have a NULL value in the item_active field, which should be either true or false. If any such rows exist then the prerequisite check fails and the upgrade will be aborted. To change this query from a prerequisite check to an investigative tool to find the troublesome rows, just replace the COUNT(*)=0 with * and run the query with your favorite SQL utility:
SELECT * FROM item WHERE (item_active IS NULL);
This will show the entire item record wherever the item_active flag isn't set.
You can usually use the xTuple ERP application to fix these problems. In this example, you would open the Item window for every record in the list you just selected, make sure the Active flag is set appropriately on that window, and *Save* the Item. Simply clicking the Cancel button won't fix the problem because it doesn't modify the data but saving the Item will update the item_active field with the value displayed on the window.
Analyzing Failures During Upgrade Processing