Updater Guide

The Updater for xTuple ERP 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 Manufacturing to Enterprise 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 article 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:

  • Additional information on creating upgrade scripts and package scripts can be found on the Create Updater Packages page


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

Tip: 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

You can download the Updater application wherever you download xTuple software.

Getting the update packages

The update packages are used to upgrade your xTuple ERP to a newer version. The naming convention will vary, depending on the xTuple ERP edition you are running.  In summary using examples:

  • Enterprise edition upgrade file:

    • enterprise-upgrade-5.0.0.gz - Upgrades your xTuple ERP from any supported version to version 5.0.0

  • Manufacturing edition upgrade file:
    • manufacturing-upgrade-5.0.0.gz - Upgrades your xTuple ERP from any supported version to version 5.0.0

    Tip: A note to Mac users: The Safari web browser uncompresses .gz files after it downloads them. 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

    Download the Updater application wherever you download xTuple software. Be sure to download the Updater to match your operating system  (Linux, Windows, or Macintosh). 

    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.

    Info: 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.

    Note: 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 upgrade process. Either a database 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.

    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.

    Note: 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) and xTuple Connect  (xtbatch) are both 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 update 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 addition, system administrators can manage extension packages, once they have been loaded, under the System > Design menu.