The P4D "-xv" flag was introduced in revision 2001.1.
The Perforce Server database tables are kept in a B-tree structure, which allows rapid keyed access, and keeps the data organized. The data stored in this structure uses offsets within the file to either point to pages or to specific information within a page. Data on the pages is often relocated to accommodate new data or to reuse space from deleted items.
The structures can become damaged in the event of:
- An unexpected server halt (crash, power outage, hardware failure).
- Insufficient disk space.
- Partial hardware failure (Hard drives, controllers, bad memory).
You might suspect low-level database issues if you encounter any of the following:
- Checkpoint creation fails -- the checkpoint file itself may be present, but incomplete, and the journal file failed to truncate.
- If items appear in a checkpoint, but are not accessible by way of Perforce client commands.
- If P4D crashes during any operation that scans large portions of the database.
- You receive any Perforce Server error messages with "dbscan" or "db write" errors.
After running the -xv command you will see a series of messages as it processes each table in the format:
The length of time the command takes to validate each table varies according to the size of each table's "db.tablename" file. For example, a typical "db.protect" table will validate more quickly than "db.have". In general, validating all your Perforce database tables takes about the same time as taking a checkpoint. Tables are locked one at a time as they are being validated which blocks other commands so you probably want to schedule production downtime and shut down the server before running p4d -xv. Note that the p4d -xv command is read-only so you can stop it at any time with CTRL+C should you need to put the server back into production.
Some validation errors you might see:
- Pages beyond the size of the file.
- Circular free list.
- Pages which are not readable.
- Pages which are not connected to tree or freelist.
- Pages which are not valid or are uninterpretable.
- Pages which are visited multiple times in tree and freelist.
- Data is out of order - table restore required.
- B-tree does not have consistent level count.
- Pages of uninterpretable contents found.
- Items within pages have structural problems.
If any of these errors are evident you should restore from your most recent good checkpoint and journal files. If validation errors persist after the restore you should contact Perforce Support
- Free list pages which are not marked as free.
This validation message can be safely ignored. This message is informational and does not indicate any problem with your data.
- Pages which are not connect [sic] to tree or freelist.
This validation message will sometimes be displayed in the event a command has been interrupted, which can result in new pages being written, but old pages are not assigned to the database "freelist". Since those pages are to be over-written with new data, there is no risk of data loss or corruption. However, over time these "lost" pages will result in slightly larger table sizes, since the space they take up is never reused. This can be corrected by restoring the database using the latest checkpoint. If circumstances make this impractical, the restore can be safely delayed until the next maintenance window.
- **** Checksum mismatch **** possible data corruption.
Usually this is due to a crash on the Server and the stored checksums within the database no longer match ones calculated during the -xv command. A restore from checkpoint and journal should be done as soon as possible.
If this error message is continuing to occur after restores, this can also indicate a hardware problem in memory or disk drive. The checksum error message is designed to catch hardware issues such as bit rot (gradual decay of storage media).
The vendor for the hardware should have diagnostic tools to check the hardware integrity. If, for example, the Windows OS was not rebooted while the Perforce server was running or there have not been any recent server crashes, then the culprit is likely a hardware problem.