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, for instance, you could still restore the database even though Wednesday’s checkpoint hadn’t yet been made.

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.

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.

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

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

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

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 P4 Command 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.