Perforce Public Knowledge Base - Checkpoints and Journals
Reset Search
 

 

Article

Checkpoints and Journals

« Go Back

Information

 
Problem

Should you take the time to create checkpoints?
Should you keep recent checkpoints and journal files?

Solution

Absolutely yes! The Perforce System Administrator's Guide describes how to use checkpoints and journals for Perforce depot backup and recovery. This article is written for Perforce system administrators to explain why checkpoints and journals are so important.

Background

The Perforce Server stores two kinds of data: versioned files, and metadata (changelists, opened files, labels). Both versioned files and metadata are stored in the Perforce Server's root directory. Versioned files are stored in depot subdirectories; there is one subdirectory for each depot in your Perforce installation. Metadata are stored in the Perforce database. Each db.* file in the Perforce root directory is a single, binary-encoded database table.

Disk space shortages, hardware failures, and system crashes might corrupt any of the Perforce Server's files. That possible corruption is why the entire Perforce depot directory structure(s) should be backed up regularly using normal file system backups. Versioned files in the depot subdirectories can be restored from backups without any loss of integrity.

Perforce database files, on the other hand, may not have been in a state of transactional integrity at the moment they were copied to system backups. Restoring the db.* files from system backups may result in an inconsistent database. The only way to guarantee the integrity of the database after it has been damaged is to restore it from Perforce checkpoint and journal files.

Checkpoint files

A checkpoint is a file that contains all information necessary to recreate the Perforce database. Note that a checkpoint does not contain contents of versioned files -- you cannot restore any of your versioned files from a checkpoint. However, you can restore all changelists, labels, jobs, and so on from a checkpoint.

Checkpoints are not created automatically -- someone or something must run the checkpoint command on the Perforce Server machine. The command to create a checkpoint is described in the Perforce System Administrator's Guide.

You can set up an automated program to create your checkpoints on a regular schedule. Be sure to always check the program output to make sure checkpoints are successful. The first time you need a checkpoint is not a good time to discover your checkpoint program is not working correctly. Remember to specify the path to the running journal when creating a checkpoint.

If the checkpoint command itself fails, please contact support@perforce.com right away. Checkpoint failure is usually a symptom of a resource problem (disk space, permissions, and so on), which can put your database at risk if not handled correctly.

Journal files

The journal is the running transaction log that keeps track of all database modifications since the last checkpoint. It is the bridge between two checkpoints. If you have Monday's checkpoint and the journal that was collected from then until Wednesday, those two files contain the same information as a checkpoint made Wednesday. So if a disk full condition on Wednesday causes corruption in your Perforce database, you can still restore the database even if Wednesday's checkpoint had not been made yet.

Journal files are useful for auditing as well as for recovery. Since a checkpoint is only a snapshot, it can describe the state of the database only -- it contains no information about how the database got into that state. The journal, on the other hand, shows how and when the database was changed. To find out things like when a client workspace was deleted, who modified a label, or which users were active recently, you need journals.

Current journal location

By default, the current journal file name is journal and it is located in the P4ROOT directory. However, if a disk failure corrupts that root directory, your journal file is inaccessible, too. Therefore, you should not use the default but instead set up your journal file so that it is written to a filesystem other than the P4ROOT filesystem. You can set the P4JOURNAL environment variable on the Perforce Server (or in Unix, start Perforce with the -J flag) to indicate where to write the journal file. (See the System Administrator's Guide for more on this)

Managing the Journal file

The journal file is automatically created when you start the Perforce Server. Every checkpoint after that creates a new journal file and renames the old one. You will need to start making regular checkpoints to control the size of the journal file. An extremely large current journal is a sign that a checkpoint is needed. If your journal file does not get smaller (that is, truncate) after a checkpoint, call Perforce support or contact support@perforce.com.

Restoring the database and recovering lost data

If you lose data in the Perforce root directory due to system problems, you are best prepared to recover completely if you have:

  1. The last checkpoint file
  2. The current journal file
  3. The latest P4ROOT directory backup

Review the Backup and Recovery chapter in the Perforce System Administrator's Guide and follow the instructions under "to recover the database." If you have any problems restoring the database files, or restarting the Perforce Server, contact support@perforce.com.

If you are restoring the entire Perforce root directory because of a disk crash, your depot directories might not contain the newest file revisions. After restoring the Perforce database, check recent changelists for files that were submitted after the last system backup and before the disk crash. Usually the latest revisions of these files can be re-entered from client workspaces; contact support@perforce.com for help with this.

Additional information

The Backup and Recovery chapter of the Perforce System Administrator's Guide describes how to create checkpoints and recover from checkpoints and journals using the p4d command.

The p4 admin command found in the Perforce Command Reference describes checkpoint creation with the P4 command line client.

Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255