From 2013.3 - 2018.2 to latest (multi-server environment)

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

Prerequisites

1. To upgrade Helix Server to a newer version, your Helix Server license file must be current.
2. 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 and its contents are being replicated to the outer servers.

     • Environments with a db.rev table larger than 200 GB might take a couple hours to complete.

     • Smaller environments might only take several minutes.
3. 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.)
4. Make sure that journaling is enabled because journal replication is how the new upgrades will be copied to other servers.
   
5. Be prepared to upgrade all the servers in a single upgrade session.

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 all the servers will be down several minutes for maintenance, followed by several hours in which performance might be slower and the following commands are blocked:

  • fetch
  • obliterate
  • push (for DVCS)
  • reload
  • storage
  • unload (for administration)
  • unsubmit

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

In the case of commit edge, the "innermost server" is the commit server, and the outer servers are edge servers. In the case of a standard server and replicas of that standard server, the "innermost server" is a standard server.

• The upgrade proceeds from the outermost server toward the innermost server
• Restarting will proceed from innermost server towards the outermost server.

On the outermost server

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 from '-xu' at upstream server.

   (The upgrades steps for the new version will be replicated outward from the innermost server)

6. Leave this server down.
   

On the servers between the outermost server and the innermost server

1. Shut down 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 from '-xu' at upstream server.

   (The upgrades steps for the new version will be replicated outward from the innermost server)

6. Leave this server down.
   

On the innermost server

Phase 1

1. Shut down 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.

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

7. As the OS account owner of the Helix Server, start the servers between the innermost server and the outermost server.
8. As the OS account owner of the Helix Server, start the outermost server.
9. 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.