Database Transaction Replayer

ObjectDB can record its internal engine operations in special binary recording files (journal files). Recording is disabled by default and can be enabled in the configuration.

The ObjectDB Replayer tool can apply recorded database operations to a matching database backup, if available. This feature is useful for two purposes:

• Recovering from a database failure by replaying the recorded operations.
• Reproducing problems during debugging by repeating a failure.

Recording transactions

When recording is enabled, ObjectDB maintains a recording directory for each database file. The name of the recording directory is the database file name with the .odr (ObjectDB Recording) suffix.

By default, the recording directory is created in the same directory as the database file. If the purpose of recording is data durability, you can 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 in the format <transaction-id>.odb
• Recording files, with names in the format <transaction-id>.odr

A backup file is a standard ObjectDB database file that reflects the state of the database at the end of a specific transaction. The transaction ID is used as the file name.

A recording file, which has the same transaction ID in its name, contains the database operations that were recorded after that transaction.

Recorded operations can be replayed only if a corresponding backup file exists. Therefore, when recording is enabled and a required backup file does not exist, ObjectDB automatically creates one by copying the existing database file when the database is opened. Creating the initial backup might be slow if the database is large.

Replaying transactions

The ObjectDB Replayer tool is bundled in the objectdb.jar file.

You can run it from the command line:

$ java -cp objectdb.jar com.objectdb.Replayer my.odb

If objectdb.jar is not in the current directory, you must specify a path to it.

The tool's main class is com.objectdb.Replayer. The required argument is the path to the database file, such as my.odb in the example above. ObjectDB automatically locates the corresponding backup and recording files and attempts to apply all the recorded operations. The resulting database file is also created in the recording directory. Its name, <transaction-id>.odb, specifies the last executed transaction.

You can also run the Replayer up to a specified transaction. For example:

$ java -cp objectdb.jar com.objectdb.Replayer my.odb 1000

When you specify a transaction ID as a second argument, the Replayer applies recorded operations only until it reaches that transaction.

If this command succeeds and applies all operations up to transaction 1000, the resulting file is named 1000.odb.