Upgrade to a new machine

If you have an existing system but you are installing OpenVPMS on a new machine, you essentially go through the steps for a new install, but instead of creating a new openpms database, you restore your existing one, and then migrate that to the new release.

The steps are as follows:

  1. Backup the existing database. See Upgrade|Preparation.
  2. Perform the New Installation steps, stopping at the Database Setup step
  3. Set up openvpms.properties
  4. Create an empty OpenVPMS database
  5. Restore the backup
  6. Perform the Upgrade Installation step: Migrate the database
  7. Perform the New Installation step: OpenOffice installation
  8. Perform the remaining Upgrade Installation steps, starting at Load Archetypes

Set up openvpms.properties

If the existing database is from OpenVPMS 2.2 or higher, the openvpms.properties file needs to be copied from the existing installation to the new installation.

This is located in <OPENVPMS_HOME>/conf.

If the existing database is from an earlier release, openvpms.properties needs to be configured. See Run 'toolbox configure'.


Creating an empty OpenVPMS database

To create an OpenVPMS database, run the following in a shell prompt:

> cd <OPENVPMS_HOME>/bin
> toolbox database --create --empty -u <admin-user> -p <admin-password>
Created openvpms

Replace <admin-user> with a user that has administrator privileges in MySQL and <admin-password> with their password.

If the OpenVPMS database already exists on the new server, this step will fail with the error message:

Cannot create openvpms as it already exists

The database should dropped and the command run again. Failure to do so may result in the database containing different versions of OpenVPMS tables. This can affect upgrades, and cause data corruption.


  • creates the database corresponding to the Database URL specified by the toolbox configure command
  • creates the user corresponding to the Database user and password specified by the toolbox configure command
    This user only has privileges to connect from localhost.


If the MySQL database is a different host to that running Tomcat, use the mysql utility to grant access using the command:

GRANT ALL PRIVILEGES ON <database-name>.* TO '<user-name>'@'%' IDENTIFIED BY '<user-password>' WITH GRANT OPTION;

Replace <database-name>, <user-name> and <user-password> with the corresponding values entered during toolbox configure.

To improve security, the '%' should be replaced with the host that Tomcat will connect from.


Restoring the backup

Once the database is created, the mysql utility can be used to restore the backup onto the new machine.  This is done using the command:

  > mysql -u <admin-user> -p openvpms < openvpms.sql


  • <admin-user> is the name of the MySQL administrator user
  • openvpms.sql is the dump from the old machine.


Dropping the database

If the database to restore a backup to already exists, it should be dropped first.

Only perform this step if the Creating an empty OpenVPMS database step failed.

Dropping the database destroys any data present, so ensure there is a backup before proceeding.


> mysql -u <admin-user> -p
> drop schema openvpms;
    Query OK, 46 rows affected (1.04 sec)
> quit

Syndicate content