Checkpoint files

A checkpoint is a file that contains the information necessary to re-create the metadata in the Helix Server database. When you create a checkpoint, the database is locked, enabling you to take an internally consistent snapshot of that database with transactional integrity. You can restore changelists, labels, jobs, and so on, from a checkpoint.

To guarantee database integrity upon restoration, the checkpoint must be as old as, or older than, the versioned files in the depot. This means that the database must be checkpointed, and the checkpoint generation must be complete, before the backup of the versioned files starts.

Regular checkpointing is important to keep the journal from getting too long. Making a checkpoint immediately before backing up your system is good practice.

Creating a checkpoint

Checkpoints are not created automatically. Someone or something must run the checkpoint command on the Helix Server machine. To create a checkpoint, invoke the p4d program with the -jc (journal-create) flag:

$ p4d -r server_root -jc

You can create a checkpoint while the Perforce service (p4d) is running. The checkpoint is created in your server root directory, that is, the P4ROOT directory, unless the optional server_root is specified).

To make the checkpoint, p4d locks the database and then dumps its contents to a file named checkpoint.n in the P4ROOT directory, where n is a sequence number.

Before unlocking the database, p4d also copies (on UNIX where the journal is uncompressed, renames) the journal file to a file named journal.n-1 in the P4ROOT directory (regardless of the directory in which the current journal is stored), and then truncates the current journal. The MD5 checksum of the checkpoint is written to a separate file, checkpoint.n.md5, and the lastCheckpointAction counter is updated to reflect successful completion.

This guarantees that the last checkpoint (checkpoint.n) combined with the current journal (journal) always reflects the full contents of the database at the time the checkpoint was created.

The sequence numbers reflect the roll-forward nature of the journal. To restore databases to older checkpoints, match the sequence numbers. That is, you can restore the state of Helix Server as it was when checkpoint.6 was taken by restoring checkpoint.5 and then loading journal.5 which contains all the changes made between checkpoint.5 and checkpoint.6. In most cases, you’re only interested in restoring the current database, which is reflected by the highest-numbered checkpoint.n rolled forward with the changes in the current journal.

To specify a prefix or directory location for the checkpoint and journal, use the -jc option. For example, you might create a checkpoint with:

$ p4d -jc prefix

In this case, your checkpoint and journal files are named prefix.ckp.n and prefix.jnl.n respectively, where prefix is as specified on the command line and n is a sequence number. If no prefix is specified, the default filenames checkpoint.n and journal.n are used. You can store checkpoints and journals in the directory of your choice by specifying the directory as part of the prefix. For example:

$ p4d -r . -J /where/my/journal/lives/journal -z -jc
             /Users/bruges/server151/checkpoints/mybackup

returns

Checkpointing to /Users/bruges/server151/checkpoints/mybackup.ckp.299.gz...
MD5 (/Users/bruges/server151/checkpoints/mybackup.ckp.299) = 5D7D8E548D080B16ECB66AD6CE0F2E5D
Rotating journal to /Users/bruges/server151/checkpoints/mybackup.jnl.298.gz...

You can also specify the prefix for a server with:

$ p4 configure set journalPrefix=prefix

When the journalPrefix configurable is set, the configured prefix takes precedence over the default filenames. This behavior is particularly useful in multi-server and replicated environments.

To create a checkpoint without being logged in to the machine running the Perforce service, use the command:

$ p4 admin checkpoint [-z | -Z] [prefix]

Running p4 admin checkpoint is equivalent to p4d -jc except that using p4 admin checkpoint requires that you be connected to the server. You must be a Helix Server superuser to use the p4 admin command.

You can set up an automated program to create your checkpoints on a regular schedule. Be sure to always check the program’s output to ensure that checkpoint creation was started. Compare the checkpoint’s actual MD5 checksum with that recorded in the .md5 file, and back up the .md5 file along with the checkpoint. After successful creation, a checkpoint file can be compressed, archived, or moved onto another disk. At that time or shortly thereafter, back up the versioned files stored in the depot subdirectories.

To restore from a backup, the checkpoint must be at least as old as the files in the depots, that is, the versioned files can be newer than the checkpoint, but not the other way around. As you might expect, the shorter this time gap, the better.

If the checkpoint command itself fails, Request Support immediately. Checkpoint failure is usually a symptom of a resource problem that can put your database at risk if not handled correctly.