Introduction
pulse™ uses a database to store most state data, including the most important build data. Currently, the following databases are supported:
- An embedded HSQL database.
- PostgreSQL
- MySQL
When you first evaluate pulse™, you are likely to use the embedded database as it is the simplest to set up. However, when you put pulse™ into production, we strongly recommend migrating to one of the external databases. These databases have more sophisticated tools for management and monitoring, and in general are more robust.
 | Warning
Once you have migrated to an external database, pulse™ will no longer perform automatic backups of the database on upgrade. Instead, you should use the export command to dump the state of your database prior to all upgrades. |
Backup
Before migrating, you should create a backup of your current pulse™ database. Assuming you are using the embedded database:
- Shutdown pulse™
- Take a copy or archive of the $PULSE_DATA/database directory.
If you are already using an external database, we recommend using that database vendors' tools to back up.
Prepare the New Database
MySQL
Installation
You will need to install an instance of MySQL if you do not already have one available. We primarily test against MySQL 5.0, and therefore recommend this version. Earlier versions may not support all features required by pulse™, and later versions are not yet stable. Details of installation are outside the scope of this document.
Pulse Database
You should create a new database (also referred to as a "schema" in MySQL tools) for pulse™ to use. In this document we will assume that you call the database "pulse". It is also best to create a dedicated "pulse" user in your database. You must ensure this user has full write access to the "pulse" database, including the ability to create tables and apply constraints.
JDBC Driver
To allow pulse™ to access MySQL, you need to install the MySQL driver jar (also known as Connector/J). This file can be obtained for MySQL 5.0 from http://dev.mysql.com/downloads/connector/j/5.0.html
. Ensure you have a copy of the jar archive on your pulse™ master machine.
 | Linux Systems
Most Linux distributions will have a package that installs the driver jar, usually in a location like /usr/share/java. |
PostgreSQL
Installation
Naturally, you will need an instance of PostgreSQL running before you can migrate. We primarily test and therefore recommend version 8.1. Details for installing PostgreSQL are outside the scope of this document.
Pulse Database
Once PostgreSQL is installed, you will need to create an empty database for pulse™ to use. We also recommend creating a dedicated pulse user for connecting to the database. One way to achieve this is to use the createuser and createdb command line tools. For example, on a Unix-like system which already has a 'pulse' login account:
# sudo -u postgres createuser -U postgres -d -A -P pulse
# sudo -u pulse createdb -U pulse -E UNICODE pulse
JDBC Driver
To allow pulse™ to access PostgreSQL, you need to install the PostgreSQL JDBC 3 driver jar. This file can be obtained for your PostgreSQL version from http://jdbc.postgresql.org/download.html. Ensure you have a copy of the jar archive on your pulse™ master machine.
| Linux Systems
Most Linux distributions will have a package that installs the driver jar, usually in a location like /usr/share/java. |
Migration
As of version 2.0, pulse™ includes a wizard to simplify the migration process. To access the wizard, start pulse™ with the --migrate command-line argument:
You should see startup messages ending with something similar to:
[24/11/08 18:13:53] Database migration requested, requesting details via web UI.
[24/11/08 18:13:53] Now go to http:
Migration Wizard
As the prompt above indicates, the migration wizard is available via the web interface. When you go to the interface, you should see the following form:
Fill in details to match the database you created earlier. Select the local driver jar file to match your database server. Note that the driver jar is copied into $PULSE_DATA/driver where it will persist across pulse™ upgrades. You can click 'check' to establish a test connection to your database before continuing.
When you click 'next', you will see the migration progess:
All going well, you can click 'continue' and pulse™ will start up as normal, using the new database.
