CREATE JOURNAL ARCHIVE

From InterBase
Jump to: navigation, search

Go Up to Statement and Function Reference (Language Reference Guide)


Activities journal archiving and performs the initial database dump to the archive directory.

CREATE JOURNAL ARCHIVE <journal archive directory>
Argument Description

journal archive directory

The location in which InterBase stores the journal archive. If the directory does not exist or is not accessible, InterBase returns an error message. The directory path can be a local drive, a mapped drive, or an UNC path (as long as the underlying file APIs can open the file using that specification). If you do not specify a journal archive directory in the CREATE JOURNAL ARCHIVE statement, InterBase uses the journal directory created with the CREATE JOURNAL statement.

Description: The CREATE JOURNAL ARCHIVE command performs two functions: it activates journal archiving in an InterBase database, and it automatically performs the initial full, physical dump of the database. InterBase stores the dump in the journal archive directory you specify in the CREATE statement. A journal archive enables you to recover to the last committed transaction in the most recently archived and completed journal file.

Important: CREATE JOURNAL ARCHIVE creates the archive and performs an initial dump. However, you must issue a specific gbak command to copy completed journal files to the journal archive. You use another gbak command to perform subsquent dumps to the archive. For information about the gbak archive commands, and about how to implement journaling and journal archiving, see the InterBase Operations Guide.

Journal Archive Management

You can manage the Journal Archive feature of InterBase V8. The archive is a directory that holds journal files, which have been archived from the local journal directory associated with a database. In addition, to storing copies of the local journal files, the archive also stores database dumps that are periodically backed up to the archive.

Description: Archived database dumps represent the starting point from which long-term database recovery is initiated. A set of archive journal files are applied to a copy of the archive database in the same way that local journal files are applied to a production database during short-term recovery. Also, an InterBase timestamp can be specified to indicate a point-in-time until which the journal files will be applied.

When the archive is used to recover a database, the resulting database is not a journaled database. This means that RDB$LOG_FILES, RDB$JOURNAL_FILES and the log page of the database are empty. This prevents the database from accidently using the journal and journal archive of an existing database. Database recovery is usually used when the original database is corrupted or unavailable due to hardware failures. However, it could be possible to recover a database on the same machine as the working production database or on a different machine where the journal and journal archive directories have no similarly-named directories. Therefore, if journaling and/or journal archiving is desired for the recovered database, it is necessary to execute the appropriate DDL commands to do so.

Examples: gbak is used to archive databases and journal files to the archive, and is also used to recover a database from the archive back to a specified local directory of the user's choice.

To archive a database:
gbak -archive_database <dbname>

To archive local journal files:

gbak -archive_journals <dbname>

To recover a database (optionally to a point-in-time)

gbak -archive_recover [-until <timestamp>] <archive_dbname> <local_dbname>

If the -until command line switch is not given, the database recover applies as many journal files as possible to recover a database to the most recent point-in-time. If possible, the database recovery attempts to "jump" from the archive to the local journal directory to apply the journal files that were never copied to the archive. In this way, a database may be recovered to the most recently committed transaction of the original database.

If allowed, the archive grows in storage size infinitely as the database and the most current journal files are continually archived. Gfix is used to manage and garbage collect archived items that are no longer required. As the number of journal files grows in the archive without have created more recent archived database dumps, so does the time that will be needed to recover the database from the archive. Therefore, it is desirable to periodically create additional database dumps in the archive. At some point, you may decided that older database dumps and the journal files on which they depend on are no longer necessary, as the basis of recovery will be on more recent database dumps and journal files.

All archive items are denoted by an archive sequence number that corresponds to the order in which the items were created in the archive.

To garbage collect archive items less than an archive sequence number.

gfix -archive_sweep [-force] <archive_sequence_no>

If an archive item cannot be swept for some reason, the sweep stops and returns an error status. In some cases, this could stop the command from ever succeeding. For example, if an archive is manually deleted with a shell OS command, the sweep always fails because it cannot find the file to drop. The -force option continues regardless of errors to delete as much as possible. The -force switch logs errors to the InterBase error log instead of returning an error status.

To specify how many database dumps to allow in the archive:

gfix -archive_dumps <number>

Once the number of database dumps in the archive exceeds the <number> given, all lower sequenced archive items are deleted from the archive. Sometimes all lower sequenced items cannot be deleted. For example, a database dump may depend on a lower sequenced journal file with which to start recovery. In that case, InterBase automatically adjusts the given sequence number lower so that this dependency is not lost.

To track that state of the archive, a new system table, RDB$JOURNAL_ARCHIVES, has been added for ODS 12 databases. The Gbak and Gfix commands listed above used this system table to decide which archive items are targets for the commands.

Important: Listed below are the requirements and constraints for managing the Journal Archive.
1. The archive is platform-specific. An archive created with InterBase for Windows cannot be directly used to recover on InterBase for Unix. Instead, an archived database dump could be logically backed up in transportable format and then logically restored on the other platform.
2. The journal and journal archive are restricted to a single directory. The number of items allowed to be archived will be limited to the number of files that are allowed in a directory for a give file system.
3. Only full database dumps are archived. In particular, it is not possible to archive incremental database dumps.
4. Journaling must be enabled for a database before the database can be configured for journal archiving.

See Also

Advance To: