The Database Dumper and Loaders

Rekall can dump databases to a set of XML formatted files, and load a database from such a set of files. These are accessed by selecting a database in the main database window under the servers tab, then using the entries under the View menu.

Please note that Rekall can only dump and load those parts of the database that it knows about. Currently, this effectively means just tables and the data they contain (which can include form, etc., definitions of these are stored in the database). This may be extended in due course, but you should not expect to be able to dump and load arbitrary database structures. In addition, the data is stored in XML format and, internally, Rekall uses the copier mechanism. This means that loading large tables is not very quick!

When using either the dumper or the loader, Rekall will prompt for a directory. Tables definitions and data will be written to, and loaded from, the specified directory. Files are named with the object name, with an extension as listed below:

Table definition tabledef
View definition viewdef
Sequence definition seqdef
Table data tabledata

Please note that the dumper and loader functions are intended to allow you to dump a database that was created with Rekall, and to install that database on another machine or system. It should not be used as a means to make database backups, and, repeating from above, it cannot handle abitrary database specific structures (such as stored procedures) that Rekall knows nothing about.

The Database Dumper

The database dumper dialog is shown below. This screenshot is taken from a PostgreSQL database that contains sequences and views as well as tables.

You can either dump all objects, by checking Dump all objects, or you can select individual objects. Also, you can dump either object definitions or object data, or both. However note that there is no data associated with a view, nor with a sequence (strictly, a sequence does have data - such as the current value - but it is inextricably bound up with the definition).

The dump to single file option is described later on.

Rekall will check whether the selected directory contains any dumper files, and show a warning message if so.

The Database Loader

The database loader is shown below. Again, this is taken from a PostgreSQL database that contains tables, views and sequences.

As for the dumper, you can choose to load all, or selected objects, and you can load either definitions or data or both (but again note that views have no data, and sequences are entirely defined by their definition). Using use best column match option will attempt to pick an appropriate column type where the target database does not have the same column types as the database which was dumped. Note that this is driver dependant, and may or may not make a sensible choice!

The dialog displays the object type, whether it already exists in the database, and whether there are associated definition and data files. You can choose whether to replace existing objects with their saved definitions, or whether to leave them unchanged and ignore the definition files.

In addition, the loader has options to map table and column names. The buttons to the top-right provide operations over all the tables and columns; to map names to upper or lower case, and to reset (unmap) all mappings; you can save mappings to a file for later use. Right clicking on a table name or a column name (which you can see by expanding the table) brings up a popup menu with options to map that name or to reset (unmap) the name. This allows you to change individual names (for instance, if a column or table name clashes with a keyword for the target database).

Make you Database Publicly Available

You can make a Rekall database publicly available - that is, you can package it up so that it can be loaded and installed from the database connection wizard - from the database dumper. Actually, even if you don't want to make it publicly available, this provides a means of dumping the database into a single file.

To dump the database this way, use the dumper as above, but check the Dump to single file option and enter a file name. Rekall will then dump the database into the named file, adding the extension .dbspec.

You also need to create a manifest file. This has to be done "by hand". The file should be called manifest.xml and be placed in the same directory as the database dump file. The example below is the manifest file for the demo database.

<dbspecification>
  <database name="Orders" asfiles="1">
    <description>
       <b>Orders: Demonstration Orders Database</b>
       <p>
       This is a simple customers, products and orders database. It
       is really only intended as a simple example database to show
       some of Rekall's capabilties.
       </p>
    </description>
    <validdb db="xbase"/>
    <url>demo.dbspec</url>
  </database>
</dbspecification>
        

The asfiles attribute should be zero of the forms, etc., are stored in the database or one if they are stored in the file system. The text within the description takes will be displayed in a QT RichText control, so simple HTML-like formatting can be used. There should be one or more validdb elements, specifying which server databases can be used; in practice there is likely only to be the one from which you dumped. This should be the server database tag, like xbase, mysql or pgsql. Finally, the url element contains the URL of the database dump file. If this is in the same directory as the manifest file, a simple file name can be used.

You can check that your dumped database loads correctly (into an empty server database) by using the database connection wizard and specifying the path to the manifest file.

If you want to look at the files for the stock databases that are distributed with Rekall, look in the stock/databases directory in the installed files.