Updater Guide

 

The Updater for xTuple ERP (PostBooks®, Distribution, and Manufacturing Editions) is an application which enables you to update your databases from one release to the next, to upgrade from one xTuple ERP edition to another, such as from PostBooks® to Distribution Edition, and to load supplemental extensions into your xTuple database. The Updater reads and processes upgrade scripts or packages, which are collections of files bundled together into .gz files. This document describes the processes involved with loading and running these packages using the Updater application.

But first, if you need help with specific problems related to upgrading your xTuple ERP database, there are several other pages you might want to look at:

Overview

xTuple ERP is a large application that conceptually can be divided into the following parts:

  • A client application: The program on your computer that you run - xtuple.exe on Windows, xTuple.app on Mac OS X, and xtuple on Linux.

  • A database server: The program (i.e., PostgreSQL) that runs on a central computer and is shared by all users of an xTuple ERP installation.
  • A database schema: The way the data are stored and organized on that database server - the tables, views, sequences, indexes, triggers, and other constraints in the public and api schemas in the PostgreSQL database.

  • Stored procedures: Pieces of application code stored by the database server and run on the database server when requested by the client application - also stored in the public and api schemas in the PostgreSQL database.

  • Data: The actual values which the application uses, which fall into the following categories:
    • end-user data, such as purchase order headers and line items, bills of materials.
    • internal data, such as the list of privileges, the list of currencies, and the list of countries.
    • intermediate data, such as report definitions, which xTuple supplies but which individual sites can either add to or customize.

All of these parts have to be synchronized for any one of them to operate as expected. For example, xTuple did not support release 2.3.2 of xTuple ERP on PostgreSQL 8.3 because there were significant changes to the behavior of stored procedures between PostgreSQL 8.2 and 8.3; many stored procedures were modified to allow running them on PostgreSQL 8.3 and this work was done for xTuple ERP 3.0.

The Updater is xTuple's tool for making changes to the database schema and stored procedures that correspond to changes in the client application. These changes might include adding new tables, modifying the structure of existing tables, and adding internal data. On occasion the nature of the changes is such that end-user data need to be manipulated. An example of this was the introduction of item units of measure, for which data previously stored in the item table were moved to a separate table. The update package for this change created the new itemuom table and populated it from the existing data in the item table before dropping the no-longer-used columns in the item table. The vast majority of changes made during updates, however, do not change end-user data.

How to Update xTuple ERP

Before performing any updates to a database, you should first make a backup copy of the database you are updating. Having a backup ensures you can always go back to the original database if errors occur during the upgrade.

To perform an update on an existing system you need to assemble the following pieces:

  • A copy of the Updater application.
  • A copy of the update package or packages required to move from your current xTuple ERP database version to your target version.
  • A copy of the new xTuple ERP client application.

Then the process of updating is fairly simple:

  • Run the Updater application.
  • Within the Updater the update package and start the update.
  • Run the new xTuple ERP client application instead of the old.

Because this is an update to an existing system, presumably you already have:

  • The PostgreSQL database manager installed and running.
  • An xTuple ERP database installed and running on your PostgreSQL instance.
  • Access to administrative tools such as pgadminIII or pg_dump to back up your database.

Getting the Updater

To get the Updater application, go to the SourceForge downloads page for PostBooks and click on the version number link next to PostBooks®-Updater.

Getting the update packages

Get the update packages from the SourceForge downloads page for PostBooks® if you use PostBooks®. If you are a commercial edition user, then you should download your update packages from the xTuple website.

It's hard to be precise on the steps to follow at this point because some people will be upgrading from one release to the following release, while others will have skipped several releases and need to get caught up. The keys to understanding what files to get are:

  • the naming conventions for the update packages and
  • the sequence of release numbers.

If you are upgrading from one release to the one immediately following then you just have to find the one update package and download that. If you are upgrading after skipping several releases, you'll have to find the packages for each of the releases that you skipped. To know which files to download, you need to understand the naming conventions for the update packages.

PostBooks® update packages are named pbOLDtoNEW.gz, where OLD and NEW are version numbers corresponding to releases of xTuple ERP. If you are upgrading production databases you should only download update packages where OLD and NEW are simple 3 digit numbers, such as pb300to301.gz - this is the upgrade package for PostBooks from release 3.0.0 to 3.0.1. Anything else, such as pb310alphato310beta.gz, is an upgrade from an intermediate release to another intermediate release (in this case from an alpha to a beta) and should only be used if you want to test upcoming functionality in a test database. In this test case you'll need to get all of the individual update packages for all of the intervening alpha, beta, and possibly release candidate releases, and apply them in turn. The naming convention for Distribution Edition is similar to that for PostBooks, using std instead of pb as the prefix (e.g. std300to301.gz; OpenMFG is also similar but has no prefix at all (e.g. 300to301.gz).

In summary using examples:

  • If you are updating PostBooks® from 3.0.0 to 3.0.1, you need to download one update package: pb300to301.gz.

  • If you are updating PostBooks® from 2.3.1 to 3.1.0, you need to download several packages:

    • pb231to232.gz
    • pb232to300.gz
    • pb300to301.gz
    • pb301to310.gz
  • If you are an adventurous person and want to upgrade a copy of your 3.0.1 database to the 3.1.0BETA2, you need to download:

    • pb301to310alpha.gz
    • pb310alphato310beta.gz
    • pb310betato310beta2.gz

A note to Mac users: The Safari web browser uncompresses .gz files after it downloads them (read this article). For the time being, your options are to recompress the package files after downloading them (you can use gzip in a Terminal window or various GUI tools) or download them with a different web browser.

Getting the xTuple ERP application

To get the client application from SourceForge, go back to the downloads page and click on the version number link next to PostBooks-GUIclient. Then click on the link that corresponds to the platform on which you want to run the client (Linux, Windows, or Macintosh). You should also read the Release Notes posted there.

Updating (the fun part:-)

First things first - upgrading is always risky, no matter how careful everybody is. Do your part: back up your database before you upgrade.

Practice to check for errors

Now use that backup to create a copy of your database. By upgrading a copy you can test for problems that might arise during the upgrade:

  • Prerequisite check failures.
  • Upgrade performance.
  • Failures caused by false assumptions about the data or schema.

Start the Updater application and log in to the database you want to upgrade. This login procedure is the same as when logging into any xTuple application. Once you have logged in, select the "File | Open..." menu option and choose the first package you want to use.

You should log in to the Updater as the default xTuple superuser (e.g., admin or mfgadmin) to ensure your upgrades are performed successfully. The Updater warns you if you try to log in without being a superuser.

By default, the latest version of the Updater runs an entire series of upgrade scripts as a single commit that will be rolled back if any errors are encountered. This ensures that databases will not be left in a partially-upgraded state if errors are encountered during the uprgrade process. Either a databse is upgraded to the next version successfully, or the upgrade is cancelled and the database is restored to its original state.

When a package is loaded it will first check to see if your database meets a series of prerequisites. If those requirements are met, the updater will indicate the check for requirements has been successful. This means you may proceed with the update. If those requirements are not met, you will see a list of messages describing the problems and you will need to fix the data before you can upgrade. See DebuggingUpgradeErrors if you are unsure how to proceed at this point.

Version Upgrade Package Loaded in Updater

After a successful requirements check, click the START UPDATE button to start update processing. As the update progresses, you will see various messages indicating the progress of the update. You will also see a progress bar just below the START UPDATE button.

Depending on the exact state of your database, you may get some error messages. Some of these errors may be safely ignored-- especially those which indicate plainly that they were ignored. Other errors may require you to take specific actions. You should examine such errors closely. After examination, you may either choose to ignore the error, retry after correcting the problem on the database, or abort the update altogether. If there were some errors which were ignored during the processing, newer versions of the Updater (2.0.0) will ask if you want to roll back the changes or accept them in spite of the errors. Either way, you can always go back to your original database as long as you remembered to make a backup copy before you started the upgrade.

Once all the structural database changes have been made, the updater will update any new reports that are available.

Reports have grades. When printing reports, the report with the highest grade is the one printed first. You can have any number of reports with varying grades loaded into your database. Reports with a grade of 0 are considered xTuple stock reports. Reports with a grade higher than 0 are considered custom reports. If you have a custom report, you should be sure to save it with a grade of 1 or higher. Grading your custom reports appropriately will prevent custom reports from being overwritten by stock reports during the update process. xTuple reserves the right to upgrade any and all reports having a grade of 0 during the update process.

When the updater progress bar reaches 100%, you may open a new package or close the updater application. Your database is now updated to the next version.

Note that if you are updating over several releases, practicing now will help you find a lot of problems before you attempt to update your production database.

The Real Deal

Once you have updated the practice database successfully, you can now switch to updating the production database. Back up your database again, since it's probably changed since you did your backup for testing the update process. Follow the same steps as you did during practice, but fix any data that might have failed prerequisite checks before you try to run the update package.

Use the new client application

Now that the database is up to date, make sure you use the right version of the client application with it. This might mean loading a new version on a file server for all of your users to share or putting a copy on every client machine. However it gets done, make sure it happens.

Extension Packages

The Updater application is also used to load extension packages for xTuple ERP. When loaded into an existing xTuple ERP installation, these packages extend the ERP's base functionality. The Manufacturing Edition (xtMFG), the Batch Manager (xtBatch),  and the Point of Sale system (xtPOS) are all examples of extension packages for xTuple ERP. The process for installing extensions is fundamentally no different from the process for updating the xTuple ERP version, as described above:

  1. Download the extension package (also uses .gz file extension)
  2. Make a backup copy of target database
  3. Connect Updater to target database
  4. Use File | Open to select package
  5. Select the START UPDATE button to begin
  6. Wait for upate to finish
  7. Log in to xTuple ERP
  8. View new features

Depending on the nature and scope of the extension package you've loaded, it may or may not be necessary to grant additional privileges to users who will need access to the new functionality. In addtion, system administrators can manage extension packages, once they have been loaded, under the System > Design menu.

Migrating from PostBooks

If you are moving from PostBooks® to one of the commercial editions of xTuple ERP, the Updater is also used to perform that migration. Just as when updating the xTuple ERP version or loading an extension package, you should use the Updater to load the commercial migration package (also uses. gz extension) into your target database. Once the update is finished, both your database and your xTuple client application will contain all the features of the commercial edition you purchased.

In short, here are the steps you would follow:

  1. Purchase licenses for commercial edition
  2. Download migration package
  3. Make a backup copy of target PostBooks® database
  4. Connect Updater to target PostBooks® database
  5. Use File | Open to select package
  6. Select the START UPDATE button to begin
  7. Wait for upate to finish
  8. Log in to xTuple ERP
  9. View new features