Roll-forward recovery

Derby supports
roll-forward recovery to restore a damaged database to the most recent state
before a failure occurred.

Derby restores a database
from full backup and replays all the transactions after the backup. All the
log files after a backup are required to replay the transactions after the
backup. By default, the database keeps only logs that are required for crash-recovery.
For roll-forward recovery to be successful, all log files must be archived
after a backup. Log files can be archived using the backup function calls
that enable log archiving.

In roll-forward recovery the log archival mode ensures that all old log
files are available. The log files are available only from the time that the
log archival mode is enabled.

To restore a database by using roll-forward recovery, you must already
have a backup copy of the database, all the archived logs since the backup
was created, and the active log files. All the log files should be in the
database log directory.

There are two types of log files in Derby:
active logs and online archived logs.

Active logs

Active logs are used during crash recovery to prevent a failure that might
leave a database in an inconsistent state. Roll-forward recovery can also
use the active logs to recover to the end of the log files. Active logs are
located in the database log path directory.

Online archived logs

Log files that are stored for roll-forward recovery use when they are
no longer needed for crash recovery. Online archived logs are also kept in
the database log path directory.

Enabling log archival mode

Online archive logs are available only if the database is enabled for log
archival mode. You can use the following system procedure to enable the database
for log archival mode:

The input parameters for the calls in the previous example specify the
location where the backup should be stored and specify whether or not the
database should keep online archived logs for the backup. Existing online
archived log files that were created before this backup will be deleted if
the input parameter value for the deleteOnlineArchivedLogFiles parameter
is non-zero. The log files are deleted only after a successful backup.

Note: Make
sure to store the backup database in a safe place when you choose the log
file removal option.

The SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE procedure
will issue an error if there are any unlogged operations in the same transaction
as backup procedure.

If any unlogged operations are in progress in other transactions in the
system when the backup starts, this procedure will block until those transactions
are complete before performing the backup. Derby automatically converts unlogged
operations to logged mode if they are started while the backup is in progress
(except operations that maintain application jar files in the database). Procedures
to install, replace, and remove jar files in a database are blocked while
the backup is in progress.

If you do not want backup to block until unlogged operations in other transactions
are complete, use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT
procedure. This procedure issues an error immediately at the start of the
backup if there are any transactions in progress with unlogged operations,
instead of waiting for those transactions to complete.

Disabling log archival mode:

After you enable log archival mode, the database will always have the log
archival mode enabled even if it is subsequently booted or backed up. The
only way to disable the log archive mode is to run the following procedure:

This system procedure disables the log archive mode and deletes any existing
online archived log files if the input parameter DELETE_ARCHIVED_LOG_FILES is
non-zero.

Performing roll-forward recovery:

By using the full backup copy, archived logs, and active logs, you can
restore a database to its most recent state by performing roll-forward recovery.
You perform a roll-forward recovery by specifying the connection URL attribute rollForwardRecoveryFrom=path at
boot time. This brings the database to its most recent state by using full
backup copy, archived logs, and active logs. All the log files should be in
the database log path directory.

For more information, see "rollForwardRecoveryFrom=path attribute"
in the Derby Reference Manual.

Backing up a database:

In the following example, a database named wombat is backed up to the d:/backup
directory with log archive mode enabled: