Database Transaction Replayer
ObjectDB can record its internal engine operations in special binary recording (journal) files. Recording is enabled by default and can be disabled in the configuration.
The ObjectDB Replayer tool can apply recorded database operations on a matching database backup (if available). This ability is useful for two different purposes:
- It enables recovery from a database failure by replaying the recorded operations.
- It enables reproducing problems during debugging by repeating a failure.
This page covers the following topics:
Backup & Recording Files
When recording is enabled, ObjectDB maintains for every database file a recording directory whose name is the name of the database file with the odr (ObjectDB Recording) suffix.
By default, the recording directory is generated in the directory that contains the database file. If the purpose of the recording is data durability it might be useful to keep the recording directory on a different physical device by setting the path attribute in the configuration.
The recording directory contains two types of files:
- Backup files - with names of the form
<transaction-id>.odb - Recording files - with names of the form
<transaction-id>.odr
A backup file is an ordinary ObjectDB database file that reflects the state of the database at the end of a specific transaction. The ID of that transaction is used as the name of the file.
A recording file, with the same transaction ID in its name, contains database operations that have been recorded after that transaction.
Recorded operations can be replayed only if a proper backup file exists. Therefore, when recording is enabled and the required backup file does not exist, ObjectDB automatically creates a backup file as a copy of the existing ObjectDB database file when the database is opened. Preparation of the initial backup might be slow if the database is large.
Running the ObjectDB Replayer
The ObjectDB Replayer tool is bundled in the objectdb.jar file.
It can be run from the command line:
> java -cp objectdb.jar com.objectdb.Replayer my.odb
If objectdb.jar is not in the current directory a path to it has to be specified.
The tool's main class is com.objectdb.Replayer and the required argument is the path to the database file (e.g. my.odb as shown above). ObjectDB automatically locates the proper backup and recording files and tries to apply all the recorded operations. The resulting database file is also generated in the recording directory as <transaction-id>.odb, which specifies by its name the last executed transaction.
The Replayer can also be run up to a specified transaction, e.g.:
> java -cp objectdb.jar com.objectdb.Replayer my.odb 1000
When a transaction ID is specified as a second argument the Replayer applies recorded operations only until that specific transaction is reached.
If the above run succeeds, and all the operations until transaction 1000 are applied, the generated result file is expected to be 1000.odb.