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.


Versioned files are backed up separately from checkpoints. A checkpoint does not contain the contents of versioned files. Therefore, you cannot restore versioned files from a checkpoint.

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, P4ROOT if no 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.


When verifying the MD5 signature of a compressed checkpoint, the checkpoint must first be uncompressed into a form that reflects the line ending convention native to the system that produced the checkpoint. (That is, a compressed checkpoint generated by a Windows server should have CR/LF line endings, and a compressed checkpoint generated on a UNIX system should have LF line endings.)

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


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 p4 admin.

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.


You can verify the integrity of a checkpoint using the p4d -jv command.