Using Archival Logging
This section explains the procedures you must follow to set up Archival Logging, make backups, and restore data files. It is divided into the following sub-topics:
•
General Procedures
•
Setting up Archival Logging
•
Roll Forward Command
General Procedures
For Archival Logging to work properly, you must follow a clearly defined procedure to set it up, and another procedure in the event that a restore from backup is necessary.
*Caution: If any steps of the procedures are omitted or compromised, you may not be able to restore your data to its pre-crash state.
►
To use Archival Logging properly
1
Turn on Archival Logging, if it is not already in effect. See Setting up Archival Logging for the detailed set-up procedure.
2
Shut down the database engine.
3
Backup the data files.
4
After a successful backup, delete all existing archival logs.
*Caution: Delete the corresponding log files before you resume working with the data files. Synchronizing the backup data files and the corresponding log files is a critical factor of successful recovery.
5
Restart the database engine.
►
To restore data files from backup and apply changes from the archival logs
*Note: You cannot use this procedure to roll forward the archival logs if you experienced a hard disk crash and your archival logs and data files were both located on the lost hard disk.
1
When the computer re-starts after the system failure, ensure that the database engine is not running, and ensure no other database engine is accessing the data files you wish to restore.
2
Restore the data files from backup.
3
Start the database engine, ensuring that no applications of any kind are connected to the engine.
*Caution: It is crucial that no database access occurs before the archival logs have been applied to the data files. Make sure no other database engine accesses the files. You must roll forward the archival logs using the same engine that encountered the system failure.
4
Issue the Roll Forward command as described in Roll Forward Command.
5
After the Roll Forward completes successfully, stop the database engine and make a new backup of the data files.
6
After you have successfully backed up the data files, delete the archival log files. You may now re-start the database engine and allow applications to access the data files.
Setting up Archival Logging
Setting up Archival Logging requires two steps:
•
turning on the Archival Logging feature
•
specifying the files to archive and their respective log files
*Note: To perform these procedures, you must have full administrative permissions on the machine where the database engine is running or be a member of the Pervasive_Admin group on the machine where the database engine is running.
►
To turn on Archival Logging
1
Access Control Center from the operating system Start menu or Apps screen.
2
In PSQL Explorer, expand the Engines node in the tree (click the expand icon to the left of the node).
3
Right-click the database engine for which you want to specify archival logging.
4
Click Properties.
5
Click Data Integrity in the tree to display the settings for that category of options.
6
Click Archival Logging Selected Files.
7
Click OK.
A message informs you that the engines must be restarted for the setting to take effect.
8
Click Yes to restart the engine.
►
To specify files to archive
You specify the files for which you want the MicroKernel to perform Archival Logging by adding entries to an archival log configuration file you create on the volume that contains the files. To set up the configuration file, follow these steps:
1
Create the directory \BLOG in a real root directory of the physical drive that contains data files you want to log. (That is, do not use a mapped root directory.) If your files are on multiple volumes, create a \BLOG directory on each volume.
For example, if you have data files located on C:\ and D:\, and both drives are physical drives located on the same computer as the database engine, then you would create two BLOG directories, as next:
C:\BLOG\
D:\BLOG\
*Note: On Linux and OS X, the log directory must be named blog and must be created in the directory specified by the PVSW_ROOT environment variable (by default, /usr/local/psql).
2
In each \BLOG directory, create an empty BLOG.CFG file. You can use any text editor, such as Notepad, to create the BLOG.CFG file. On Linux and OS X, the file must be named blog.cfg (lowercase).
3
In each BLOG.CFG file, create entries for the data files on that drive for which you want to perform Archival Logging. Use the following format to create each entry:
\path1\dataFile1[=\path2\logFile1]
path1
The path to the data file to be logged. The path cannot include a drive letter.
dataFile1
The name of the data file to be logged.
path2
The path to the log file. Because the log file and the data file can be on different drives, the path can include a drive letter.
logFile1
The name of the log file. If you do not specify a name, the default value is the same directory and file name prefix as the data file, but replace the file name suffix with “.log.” You may specify a different physical drive, so that the log and the data files are not on the same drive. Each data file being logged requires a different log file.
A single entry cannot contain spaces and must fit completely on one line. Each line can contain up to 256 characters. If you have room, you can place multiple entries on the same line. Entries must be separated by white space.
*Caution: You must use a different log file for every data file that you wish to log. If you use the same log file for more than one data file, the MicroKernel cannot use that log file in the event that a roll-forward is needed.
If you do not provide a name for a log file, the MicroKernel assigns the original file name plus a.LOG extension to the log file when you first open it. For example, for the file B.BTR, the MicroKernel assigns the name B.LOG to the log file.
*Caution: You are not required to log every file in your database. However, if your database has referential integrity (RI) rules defined, you must log all or none of the files involved in each RI relationship. If you log only a subset of the files involved in a given RI relationship, rolling the archival logs forward after a system crash may result in violations of your RI rules.
Examples
The following examples show three sample entries in the BLOG.CFG file on drive C. All three entries produce the same result: activity in the file C:\DATA\B.BTI is logged to the file C:\DATA\B.LOG.
\data\b.bti
\data\b.bti=\data\b.log
\data\b.bti=c:\data\b.log
The next example directs the engine to log activity in the file C:\DATA\B.BTI to the log file D:\DATA\B.LGF. This example shows that archival log files do not have to reside on the same drive as the data file and do not require the .LOG extension. (The .LOG extension is the default.)
\data\b.bti=d:\data\b.lgf
*Tip: Writing the log to a different physical drive on the same computer is recommended. If you experience a hard disk crash, having the log files on a different physical disk protects you from losing your log files and your data files at the same time.
The next example shows a BLOG.CFG file that makes the MicroKernel log multiple data files to a different drive (drive D:), assuming this BLOG.CFG file is on drive C:
\data\file1.mkd=d:\backup\
\data\file2.mkd=d:\backup\file2.log
\data\file3.mkd=d:\backup\file3.log
Roll Forward Command
The Btrieve Maintenance utility (GUI or BUTIL command line) provides a command allowing you to roll forward archival log files into the data files. See Performing Archival Logging.