Journal files

The current 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 the Server database modifications since the previous 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. or journal. Journal file rotation is an incremental metadata backup, and the checkpoint is a full metadata backup.

Tip

Journals can grow to be quite large. Frequent journal rotation reduces the size of each journal file. You might consider daily journal rotation and weekly checkpoints.

To restore the Server database to the most recent point in time, you need:

The most recent checkpoint.
Any journal files created since that checkpoint.
The journal file that was active at the time the server was stopped.

For example, suppose it is Wednesday and you have:

The weekly checkpoint file that you create before your users start work on Monday.
The daily journal files for Monday and Tuesday.
The currently running journal file of Wednesday.

If a disk crash occurs on Wednesday that corrupts the Server database, you can restore the Server database by using Monday's checkpoint file, the rotated journal files for Monday and Tuesday, and Wednesday's journal file.

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.

Note

On Windows Server 2016 and newer, journal rotation can be performed using an atomic rename instead of a copy and truncate operation. To enable this feature, see the filesys.atomic.rename configurable in Helix Core Command-Line (P4) Reference.

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

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.