From 2013.3 - 2018.2 to latest (single server)

Note

The new db.storage table replaces db.archmap to provide a link count for archive files on the server. This allows +Sn type files to be lazy copied, which saves disk space. The upgrade also improves the performance of p4 obliterate, especially on servers with significant integration history.

These instructions assume you have a single server. If not, see From 2013.3 - 2018.2 to latest (multi-server environment).

Note
  • A proxy or broker only needs to get the latest binary.
  • You do NOT need to run p4d -xu against offline db.* files (a set of db.* files periodically brought current by replaying the journal files from the production server).

Prerequisites

Important
  • To upgrade Helix Server to a newer version, your Helix Server license file must be current.
  1. Time:
    • Phase 1 of the upgrade requires that the servers be down for several minutes.
    • Phase 2 of the upgrade runs in the background so users can work. This phase might take several hours. Performance might be slower while the db.storage table is being built.
      • Environments with a db.rev table larger than 200 GB might take a couple hours to complete.
      • Smaller environments might only take several minutes.
  2. Available disk space should be at least equal to the size of the db.rev table. (The journal file can grow to the size of the new db.storage table. Typically, the journal is on a separate partition.)
  3. Make sure that journaling is enabled.
Important
  • We strongly recommend that you take a checkpoint so that you know you can recover if something goes wrong during the upgrade. (See Checkpoint files.) It is best to take the checkpoint at a time when the end-users are not active.

  • Let the users know that the server will be down several minutes for maintenance, followed by several hours in which performance might be slower and the following commands are blocked:

Upgrade Steps

In the following steps, replace

  • [P4ROOT] with the path to the P4ROOT directory
  • [P4JOURNAL] with the directory path and name of the journal file

Phase 1

  1. Shut down the server by running p4 admin stop

  2. Install the new version of the p4d binary on the system.
  3. Set the lbr.storage.skipkeyed configurable, using the new p4d binary:

    p4d -r [P4ROOT] "-cset lbr.storage.skipkeyed=1"
  4. As the OS account owner of the Helix Server, run p4d -r [P4ROOT] -J [P4JOURNAL] -xu
  5. Wait until you see this sequence of messages complete and expect a pause after the first message:
    2019.1: building db.storage from db.rev, db.revsh and db.revtx
    [pause]
    2019.1: Adding default namespace to Extension configurations
    Additional upgrades will be applied at server startup.

    (The upgrades steps for the new version will be executed by the server as it is started)

  6. As the OS account owner of the Helix Server, start the server. This starts a background process to build the db.storage table, a new table in the Helix Server schema.

  7. Inform your users that they can resume work.

Phase 2

  1. To know when the background upgrade process is complete, run p4 storage -w on the the innermost server.
  2. Wait for p4 storage -w to return the following message: "The storage upgrade process is complete".
  3. To monitor progress, on a separate command-line terminal, run the following command from time to time to verify that the timestamp or filesize is increasing:
    • ls -l db.storage for Linux
    • dir /ta /od for Windows

  4. After you determine that the timestamp or filesize is no longer increasing, run the p4 storage -U -q //... command to update the digests of your ktext file revisions. We recommend you do this overnight or on the weekend because it might reduce performance for a considerable time. (See File types in Helix Core Command-Line (P4) Reference.)

    Note

    The -U option for p4 storage exists only with 2020.2 and later servers.

  5. (Optional) Perform a verification in the background by using the p4 storage -v command.