Journal files

The journal is the running transaction log that keeps track of all database modifications since the last checkpoint. It’s the bridge between two checkpoints.

If you have Monday’s checkpoint file and the journal file that was collected from then until Wednesday, those two files contain the same information as a checkpoint made Wednesday. If a disk crash were to cause corruption in your Helix Server database on Wednesday at noon, you could still restore the database even though Wednesday’s checkpoint hadn’t yet been made.

Warning

By default, the current journal filename is journal, and the file resides in the P4ROOT directory. However, if a disk failure corrupts that root directory, your journal file will be inaccessible too.

We strongly recommend that you set up your system so that the journal is written to a filesystem other than the P4ROOT filesystem. To do this, specify the name of the journal file in the environment variable P4JOURNAL or use the -J filename flag when starting p4d.

To restore your database, you only need to keep the most recent journal file accessible, but it doesn’t hurt to archive old journals with old checkpoints, should you ever need to restore to an older checkpoint.

Journaling is automatically enabled on all Windows and UNIX platforms. If P4JOURNAL is left unset (and no location is specified on the command line), the default location for the journal is $P4ROOT/journal.

The journal file grows until a checkpoint is created; you’ll need make regular checkpoints to control the size of the journal file. An extremely large current journal is a sign that a checkpoint is needed.

Every checkpoint after your first checkpoint starts a new journal file and renames the old one. The old journal is renamed to journal.n, where n is a sequence number, and a new journal file is created.

By default, the journal is written to the file journal in the server root directory (P4ROOT. Because there is no sure protection against disk crashes, the journal file and the Helix Server root should be located on different filesystems, ideally on different physical drives. The name and location of the journal can be changed by specifying the name of the journal file in the environment variable P4JOURNAL or by providing the -J filename] flag to p4d.

Warning

If you create a journal file with the -J filename flag, make sure that subsequent checkpoints use the same file, or the journal will not be properly renamed.

Whether you use P4JOURNAL or the -J journalfile option to p4d, the journal filename can be provided either as an absolute path, or as a path relative to the server root.

Example   Specifying journal files

Starting the service with:

$ p4d -r $P4ROOT -p 1666 -J /usr/local/perforce/journalfile
Perforce Server starting...

requires that you either checkpoint with:

$ p4d -r $P4ROOT -J /usr/local/perforce/journalfile -jc
Checkpointing to checkpoint.19...
Saving journal to journal.18...
Truncating /usr/local/perforce/journalfile...

or set P4JOURNAL to /usr/local/perforce/journalfile and use the following command:

$ p4d -r $P4ROOT -jc
Checkpointing to checkpoint.19...
MD5(checkpoint.19)=48769A82387B04987568309823E784C9
Rotating /usr/local/perforce/journalfile to journal.18

If your P4JOURNAL environment variable (or command-line specification) doesn’t match the setting used when you started the Perforce service, the checkpoint is still created, but the journal is neither saved nor truncated. This is highly undesirable!

Checkpoint and journal history

You can use the p4 journals command to display the history of checkpoint and journal activity for the server. This history includes information about the following events: the server takes a checkpoint, journal rotation, journal replay, checkpoint scheduling. For detailed information about command output and options, see the description of the p4 journals command in the Helix Core Command-Line (P4) Reference.

Verifying journal integrity

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

Automating maintenance work after journal rotation

To configure Helix Server to run trigger scripts when journals are rotated, use the journal-rotate and journal-rotate-lock type triggers. Journal-rotate triggers are executed after the journal is rotated on a running server, but only if journals are rotated with the p4 admin journal or p4 admin checkpoint commands. Journals are not rotated if you invoke the p4d -jc or p4d --jj commands.

Journal-rotate triggers allow you to run maintenance routines on servers after the journal has been rotated, either while the database tables are still locked or after the locks have been released. These triggers are intended to be used on replicas or edge servers where journal rotation is triggered by journal records. The server must be running for these triggers to be invoked.

See Triggering on journal rotation for more information.

Disabling journaling

To disable journaling, stop the service, remove the existing journal file (if it exists), set the environment variable P4JOURNAL to off, and restart p4d without the -J flag.