= Using the NIF database backend =

Currently, the Mnesia based backend is the default,
therefore you have to specify a command line argument if you would like to use the NIF based backend.

After the system is installed, start !RefactorErl with
{{{
#!sh

bin/referl -db nif
}}}

NIF uses the !RefactorErl data directory to store its data. You can specify it by typing
{{{
#!sh

bin/referl -db nif -dir /path/to/your/data/dir
}}}

If you would like to start several instances of !RefactorErl/NIF,
you have to choose different node names.
It is also suggested to set different data directories as well,
although it is not strictly required.
{{{
#!sh

bin/referl -db nif -sname name1 -dir /path/to/your/data/dir1
bin/referl -db nif -sname name2 -dir /path/to/your/data/dir2

# or

bin/referl -db nif -name name1 -dir /path/to/your/data/dir1
bin/referl -db nif -name name2 -dir /path/to/your/data/dir2
}}}

After the system starts up, you can use is it like with the MNESIA database backend,
but there are some extra functions.
(For further informations see: [[ErlangShellInterface|ri]])

= Backup-system example =

After the system is started, the following operations work on the full database.

{{{
#!erlang
% Clear the whole database.
ri:reset().

% Make a checkpoint.
% This operation is always executed after transformations
% and file operations (e.g. adding or dropping a file).
ri:backup().
{ok, backup.1}
% This backup will be created in the directory of the graph
% (./data/graphs/<<graph name>>/).

% Make a checkpoint with a commit log message.
ri:backup("Something log message").

% It will print the following:
{ok, backup.2}
% That 'backup.2' will be created in the same directory as 'backup.1'.

% Now we want to know some informations about 'backup.2'.
% Note: Here you can specify either 'backup.2' or "backup.2" or just 2. 
ri:backup_info(2).
Informations about 'backup.2':
Commit-log: Something log message
Time of creation: Tue Apr 17 11:03:29 2012

% Lists all backups.
ri:ls_backups().

% You can restore a certain backup by specifying it as in ri:backup_info/1.
ri:restore(1).

% Removes all backups.
ri:clean().
}}}

= Graph operations example =
With the NIF database, you may have more graphs.
The graphs does not affect each other, so every graph has its own database, and
backups, etc. After restarting the tool, the last used graph will be loaded.
Let's see an example:

{{{
#!erlang
% By default a refactorerl_0 named graph created.
% So after the first start up, the ri:actual_graph/0
% operation should print refactorerl_0. 
ri:actual_graph().
refactorerl_0

% Now create a graph. The name of the graph must be an atom.
ri:create_graph(graph_name).

% You can list the created graphs.
ri:ls_graphs().
[graph_name, refactorerl_0]

% Load the previously created graph.
ri:load_graph(graph_name).
ok
ri:actual_graph().
graph_name

% You may want rename the refactorerl_0 graph to someting else.
% You can even rename the actual graph.
ri:rename_graph(refactorerl_0, some_other_name).
ok
ri:ls_graphs().
[graph_name, some_other_name]

% Now delete the graph which is not loaded.
% Of course, you cannot delete the actual graph.
% Warning: It deletes the whole graph from the disk,
% so it cannot be recovered later.
ri:delete_graph(some_other_name).

% ... or you can just delete all graphs.
% After the deletion, it creates the default refactorerl_0 graph.
ri:delete_all_graphs().
ok
ri:ls_graphs().
refactorerl_0

}}}

If something happened to database, then after start up you will get a message about it
and a new default graph will be created. If refactorerl_0 exists, then refactorerl_1 will
be created, and so on. The corrupted database will not be deleted by the system.
If the user wants to load a corrupted backup, then the system will print an error message,
and the backup will have a 'corrutped_' prefix (so the system renames it), and the graph
will remain the same.

= Comparison with the Mnesia backend =

While the [[MnesiaDB|Mnesia]] backend has been under development longer and can be expected to be more stable,
it is much slower than the NIF based backend;
you can expect about an order of magnitude of speed-up.
Also, the NIF backend may require less storage.
As an indication, loading ejabberd-2.1.8 (6.6 MB on disk) takes '''18323 sec''' and '''566 MB''' of RAM and '''66 MB''' of disk space, while the NIF backend on the same machine takes '''458 sec''' and '''556 MB''' of RAM and '''52 MB''' of disk space.