Journal files
The current journal is the running transaction log that keeps track of
all the Helix Core Server database modifications since the previous checkpoint
or journal. Journal file rotation is an incremental metadata backup, and the checkpoint is a full metadata backup.
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
. If the current journal is extremely large, 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
directory and named P4ROOT
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.
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
Journaling is automatically enabled on all Windows and Linux platforms. By default, the current journal filename is journal
, and
the file resides in the
directory. However, if a
failure corrupts that root directory, your journal file will be
inaccessible.P4ROOT
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
-
include the
-J filename
option when startingp4d
and make sure that subsequent checkpoints use the same file, or the journal will not be properly renamed
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.
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 Specify 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
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.
Verify journal integrity
You can verify the integrity of a checkpoint using the p4d
-jv
command.
Automate maintenance work after journal rotation
See Triggering on journal rotation.
Disable 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
option.