Connecting to a Database

As an environment for collaborative scientific exploration, VisTrails supports both stand-alone, file-based storage and relational storage of vistrails. With a relational database supporting VisTrails, multiple users can easily collaborate on projects without copying files back and forth. At the same time, if you choose to work without being connected to a database, you can save your work locally to files. Finally, VisTrails can import and export to both types of storage so you can import a vistrail from the database, save it locally as a file on your computer, make and save changes, and export those changes back to the database. Remember that because the complete workflow evolution is always saved, other users will not overwrite your changes, and vice versa. This prevents users from “stepping on each other’s feet.”

By default, VisTrails works with local files stored in the ”.vt” format (essentially compressed XML). You can save a vistrail as uncompressed XML by saving the file with a ”.xml” extension. When saving a vistrail, the system displays a standard save dialog. These files have a version associated with them so when the schema for these files may change, VisTrails will be able to import older versions. The current version of the XML schema can be found in the distribution at:

vistrails/db/versions/v1_0_2/schemas/xml/vistrail.xsd

where v1_0_2 is the current version.

Setup

As described earlier, VisTrails supports relational database storage as well as file-based storage. Currently, VisTrails has been tested with MySQL, but in the future, we plan to support most standard relational database systems.

Setting up the database

Before using VisTrails with a relational database, you must have a database installed and have access to create, access, and modify that database. If you are planning to deploy for institution-wide access, you should consult your system administrator to determine the correct configuration. The database schema for VisTrails can be found in the distribution at:

vistrails/db/versions/v1_0_2/schemas/sql/vistrails.sql

where v1_0_2 is the current version. This schema contains a sequence of SQL commands that define the tables needed for storing vistrails.

After you or someone else has created the database for the vistrails, you will need the following information:

1. hostname: the name or IP address of the machine that stores the database (localhost if it is your own machine)
2. port: the port number that you connect to the database on
3. user: the username that should be used to access and modify the vistrails database
4. password: the password for the account corresponding to the given user
5. database name: the name of the database where the vistrails are to be stored.

Setting up VisTrails

If you are planning to use the database for most of your work, you can configure VisTrails to open vistrails from the database by default. To do so, select the Preferences option from the Edit menu. (On Mac OS X, the Preferences option is found under the VisTrails menu.) When the Preferences window opens, select the appropriate option from the “Read/Write to database by default” box in the General Configuration tab.

Opening from a database

To open a vistrail from a relational database, choose the Import option from the File menu. You should see a dialog like the one pictured in Figure Opening a vistrail from the database. (Alternatively, if you have set VisTrails to use a relational database by default (see Section Setting up VisTrails), then you should select File Open from the menu or the Open button on the toolbar.)

If you have previously connected to databases using VisTrails, you should see a list of these databases in the left column of the dialog. If not, you will need to add one. To do so, click the + icon in the lower-left corner. This will bring up a dialog like that shown in Figure Creating a new database connection. To set up a connection, you will need the database connection information outlined in Section Setting up the database. After filling in that information, you can test the connection by clicking the Test button. If the test succeeds, click the Create button to add the database to the available sources for vistrails.

The database you wish to use should now be listed in the left column. Clicking on that row will query the database for a list of vistrails available from the database and display them in the right column. To open a vistrail, select the desired vistrail and click the Open button or simply double-click the vistrail. When the vistrail has loaded, you will be able to interact with it in exactly the same way as a vistrail loaded from a file.

Opening a vistrail from the database

Creating a new database connection

Saving to a database

If you opened a vistrail from the database, the default save action will be to save that vistrail back to the database. There will be no dialogs displayed—the database the vistrail was loaded from will be automatically updated.

If you opened the vistrail from a file, you will need to select either Save As or Export from the File menu, depending on whether VisTrails uses the database by default (see Section Setting up VisTrails). You will be shown a dialog similar to the one in Figure Saving a vistrail to the database. As discussed in Section Opening from a database, you can create a new connection to the database or use an existing one. Note that the name of the vistrail must differ from those already stored on the database, and clicking the Save button will persist the changes to the database.

Saving a vistrail to the database

Known Issues

Currently, saving a vistrail to the database will overwrite the vistrail currently stored on the database. However, we plan to add synchronization soon so that all explorations are captured. Thus, be aware that if two users have the same vistrail loaded from the database at the same time, and both users save their changes, only the second user’s changes will be captured.