From 2019.1 or later to latest (multi-server environment)

These instructions assume you have a multi-server environment from 2019.1 or later. If not, see From 2019.1 or later to latest (single server) .

You can upgrade a server whenever it is convenient to do so.

Upgrade outer servers first

The sequence of upgrades in a multi-server environment is from the outermost server toward the innermost server.

In the case of a standard server and replicas of that standard server, the "innermost server" is a standard server.

In the case of commit edge, the innermost server is the Commit Server and the outer servers are Edge Servers.

For example, in this edge-to-edge chaining scenario,

Edge E2 is the outermost server and Commit C is the innermost server. Therefore, you first upgrade E2, then E1, and finally C.

Limitations while upgrading

Although users can continue to use upgraded outer servers before the innermost server is upgraded, new functionality on upgraded outer servers does not become available until the inner servers have been upgraded.

During the time the Commit Server is undergoing the upgrade process, users of Edge Servers cannot perform operations that require the Edge Servers to be connected to the Commit Server. There are many such operations.

Prerequisites

  • To upgrade Helix Core Server to a newer version, your Helix Server license file must be current.
  • We strongly recommend that you take a checkpoint so that you know you can recover if something goes wrong during the upgrade. It is best to take the checkpoint at a time when the end-users are not active. To learn more, see Checkpoint files.

  • Make sure that journaling is enabled. To learn more, see Journal files.

  • Read the information at Upgrade overview.

Upgrade steps

Begin the sequence of upgrades with the outermost server, working towards the innermost server.

On the outermost server

Upgrade the p4d binary

  1. (Recommended) Verify files before and after a server upgrade.

  2. Shut down the server by running
    p4 admin stop

  3. Install the new version of the p4d binary, which you can obtain from Download Helix Core (P4D) Server.
    1. For Linux and macOS, make a copy of the existing p4d binary, and overwrite the existing p4d binary with the new one. Then proceed to "Upgrade the p4d database".

    2. For Windows, the installer:

      • Detects that an installation exists and proceeds as "Upgrading the Helix Core Server Installation".

      • Concludes with a message that "Helix Core Server failed to start. ..." This is to be expected. Proceed to "Upgrade the p4d database".
Upgrade the p4d database
  1. As the OS account owner of the Helix Core Server, run
    p4d -r P4ROOT -J P4JOURNAL -xu
    replacing
    P4ROOT with the path to the P4ROOT directory, and
    P4JOURNAL with the directory path and name of the journal file as specified at P4JOURNAL.
  2. Wait until you see this message:

    Upgrades will be applied at server startup.

  3. Start the server. This upgrades the database level to be compatible with the server version. For the list of database levels by server version, see the database schema Upgrades.
  4. (Recommended) Verify files before and after a server upgrade.

  5. Inform users of this server that they can resume working.

  6. When it is convenient, proceed to upgrade the servers between the outermost server and the innermost server.

On the servers between the outermost server and the innermost server

Upgrade the p4d binary

  1. (Recommended) Verify files before and after a server upgrade.

  2. Shut down the server by running
    p4 admin stop

  3. Install the new version of the p4d binary, which you can obtain from Download Helix Core (P4D) Server.
    1. For Linux and macOS, make a copy of the existing p4d binary, and overwrite the existing p4d binary with the new one. Then proceed to "Upgrade the p4d database".

    2. For Windows, the installer:

      • Detects that an installation exists and proceeds as "Upgrading the Helix Core Server Installation".

      • Concludes with a message that "Helix Core Server failed to start. ..." This is to be expected. Proceed to "Upgrade the p4d database".
Upgrade the p4d database
  1. As the OS account owner of the Helix Core Server, run
    p4d -r P4ROOT -J P4JOURNAL -xu
    replacing
    P4ROOT with the path to the P4ROOT directory, and
    P4JOURNAL with the directory path and name of the journal file as specified at P4JOURNAL.
  2. Wait until you see this message:

    Upgrades will be applied at server startup.

  3. Start the server. This upgrades the database level to be compatible with the server version. For the list of database levels by server version, see the database schema Upgrades.
  4. (Recommended) Verify files before and after a server upgrade.

  5. Inform users of this server that they can resume working.

  6. When it is convenient, proceed to upgrade the innermost server.

On the innermost server

Upgrade the p4d binary

  1. (Recommended) Verify files before and after a server upgrade.

  2. Shut down the server by running
    p4 admin stop

  3. Install the new version of the p4d binary, which you can obtain from Download Helix Core (P4D) Server.
    1. For Linux and macOS, make a copy of the existing p4d binary, and overwrite the existing p4d binary with the new one. Then proceed to "Upgrade the p4d database".

    2. For Windows, the installer:

      • Detects that an installation exists and proceeds as "Upgrading the Helix Core Server Installation".

      • Concludes with a message that "Helix Core Server failed to start. ..." This is to be expected. Proceed to "Upgrade the p4d database".
Upgrade the p4d database
  1. As the OS account owner of the Helix Core Server, run
    p4d -r P4ROOT -J P4JOURNAL -xu
    replacing
    P4ROOT with the path to the P4ROOT directory, and
    P4JOURNAL with the directory path and name of the journal file as specified at P4JOURNAL.
  2. Wait until you see this message:

    Upgrades will be applied at server startup.

  3. Start the server. This upgrades the database level to be compatible with the server version. For the list of database levels by server version, see the database schema Upgrades.
  4. (Recommended) Verify files before and after a server upgrade.

  5. Inform users of this server that they can resume working.

  6. Inform the users of all the servers throughout the multi-server environment that the new functionality associated with the upgrade is now available.