Journal files

The journal A file containing a record of every change made to the Helix Server’s metadata since the time of the last checkpoint. This file grows as each Helix Server transaction is logged. The file should be automatically truncated and renamed into a numbered journal when a checkpoint is taken. is the running transaction log that keeps track of all database modifications since the last checkpoint A backup copy of the underlying metadata at a particular moment in time. A checkpoint can recreate db.user, db.protect, and other db.* files. See also metadata.. For example, suppose you have the weekly checkpoint file that you create every Monday, as well as the daily journal files for Monday, Tuesday, and Wednesday, those two files contain the same information as a checkpoint made Wednesday. If a disk crash causes corruption in your Helix Server database on Wednesday before you create Wednesday's checkpoint, you can still restore the database. In other words, to restore the database to the most recent point in time, you only need the most recent checkpoint and the current running journal file.

Important

Journal file rotation as an incremental metadata backup, and the checkpoint is a full metadata backup. Many customers reduce the risk by frequent journal rotation.

Journal file names

The journal file grows until it is rotated by a checkpoint or a journal rotation command, such as p4 admin journal. An extremely large current journal is a sign that a checkpoint is needed.

Every checkpoint, including your first checkpoint, starts a new journal file and renames the old journal file. We call this "journal rotation".

Rotated journals are in the P4ROOT directory and named journal.n, where

journal. represents the value of the journalPrefix configurable with the suffix .jnl.
n is the incrementing journal number

For example, if the journalPrefix is /p4/1/logs/master, the first three rotated journals are stored as

/p4/1/logs/master.jnl.1

/p4/1/logs/master.jnl.2

/p4/1/logs/master.jnl.3

For an example of making a checkpoint and rotated journal file, see the steps in the Backup procedure topic.

Location of the journal

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

Warning

To reduce risk, make sure that the journal file and the Helix Server root are located on different file systems, ideally on different physical drives.

To change the name and location of the journal, do one of the following:

specify the name and path of the journal file in the environment variable P4JOURNAL
provide the -J filename] flag when starting to p4d
- 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.

Tip

To restore your database, you only need to keep the most recent journal file accessible. Consider also archiving old journals with old checkpoints. This makes it possible to restore to an older checkpoint.

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

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

Important

Make sure your P4JOURNAL environment variable (or command-line specification) matches the setting used when you started the Perforce service. Otherwise the journal is neither saved nor truncated.

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.

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.