1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
.. _chap-database:
************************
Connecting to a Database
************************
.. index:: database
.. \newcommand{\fixme}[1]{***#1}}}
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
=====
.. index::
pair: database; 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.
.. _sec-database-setup:
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:
#. *hostname*: the name or IP address of the machine that stores the database (``localhost`` if it is your own machine)
#. *port*: the port number that you connect to the database on
#. *user*: the username that should be used to access and modify the vistrails database
#. *password*: the password for the account corresponding to the given user
#. *database name*: the name of the database where the vistrails are to be stored.
.. _sec-database-config:
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.
.. _sec-database-open:
Opening from a database
=======================
.. index::
pair: database; opening from
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 :ref:`fig-database-open`.
(Alternatively, if
you have set |vistrails| to use a relational database by default
(see Section :ref:`sec-database-config`), then you should select ``File`` :math:`\rightarrow` ``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 :ref:`fig-database-create`. To set up a connection, you will
need the database connection information outlined in
Section :ref:`sec-database-setup`. 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.
.. _fig-database-open:
.. figure:: figures/database/open_dialog.png
:align: center
:width: 3in
Opening a vistrail from the database
.. _fig-database-create:
.. figure:: figures/database/create_dialog.png
:align: center
:width: 3in
Creating a new database connection
Saving to a database
====================
.. index::
pair: database; saving to
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 :ref:`sec-database-config`). You will
be shown a dialog similar to the one in
Figure :ref:`fig-database-save`. As discussed in
Section :ref:`sec-database-open`, 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.
.. _fig-database-save:
.. figure:: figures/database/save_dialog.png
:align: center
:width: 3in
Saving a vistrail to the database
Known Issues
============
.. index::
pair: database; 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.
.. index:: database
|
