Quickstart Guide for Upgrades to Coverity Connect 2020.12


About this document
1. Overview
1.1. Choosing the type of upgrade
2. Performing the upgrade: standalone deployments
2.1. Upgrade prerequisites
2.2. Performing an In-place upgrade (standalone instances)
2.3. Performing a Backup-and-restore upgrade (standalone instances)
2.4. Performing an Intermachine upgrade (standalone instances)
A. Coverity Legal Notice

About this document

This document describes the recommended procedures for upgrading Coverity Connect with an embedded PostgreSQL database to version 2020.12. This document does not cover the following:

  • Upgrading Coverity Connect with an external database

  • Upgrading a Coverity Connect clustered environment (Coordinator/Subscribers)

Details for the items listed above are documented in the Coverity 2020.12 Upgrade Guide.

Chapter 1. Overview

An embedded database is a part of the installation package that resides within your installation directory and is available for use by default with Coverity Connect (and Coverity Policy Manager), while an external database is one that your company creates and maintains in a separate location to use with Coverity Connect (and Coverity Policy Manager).

Depending on the size of your database and the number of versions in the upgrade, the upgrade process might take several hours to complete.

[Note]Important!

Before performing an upgrade, you should familiarize yourself with upgrade impacts by reading the section called "Important upgrade considerations" in the Coverity 2020.12 Upgrade Guide.

[Note]Important!

All upgrades must be performed using one of the upgrade options in the Coverity Connect installer. Do not perform an upgrade manually. For example, do not use command line techniques to backup an existing instance and then restore it to a new, upgraded instance.

1.1. Choosing the type of upgrade

This section helps you choose the type of upgrade. Note that each type of upgrade corresponds to the Coverity Connect installer options as shown in the following table. This chapter uses the terminology specified in the table to describe upgrade types:

Table 1.1. Installer options

Type of upgradeInstaller option(s)
In-place upgrade"In-place Upgrade" option
Backup-and-restore upgrade"Backup-and-restore" option
Intermachine upgrade“Upgrade Preparation” option followed by “Intermachine Upgrade” option

Upgrade types are described in the following subsections.

Intermachine upgrade

Use the Intermachine upgrade if you want the upgraded Coverity Connect instance to exist on a new host machine. Otherwise, use the In-place upgrade or the Backup-and-restore upgrade.

In-place upgrade versus Backup-and-restore upgrade

An In-place upgrade is faster and uses less disk space than a Backup-and-restore upgrade. However, a Backup-and-restore upgrade keeps the old instance intact, which is useful if you want to create a staging environment.

An In-place upgrade transforms an existing Coverity Connect instance, including all of its data, into a new Coverity Connect instance in the same directory location on the same machine. Essentially, an In-place upgrade does the following:

  • Optionally, backs-up the existing database

  • For PostgreSQL major version changes, modifies the data storage format in-place

  • If required by Coverity Connect, upgrades the database schema

  • Updates non-database state (the configuration not stored in the database)

A Backup-and-restore upgrade backs-up the entire, existing Coverity Connect instance. Then the Backup-and-restore upgrade restores the Coverity Connect instance, including the database, to a new location (a different directory than where the existing instance is installed) on the same machine without affecting the existing instance. Essentially, a Backup-and-restore upgrade does the following:

  • Backs-up the existing database

  • Installs a new Coverity Connect instance in the new location

  • Restores the database to the new location

  • If required by Coverity Connect, upgrades the database schema in the new installation

  • Copies non-database state (the configuration not stored in the database) to the new installation

Chapter 2. Performing the upgrade: standalone deployments

2.1. Upgrade prerequisites

Make sure the instance you want to upgrade meets the following prerequisites:

  • Important: Make sure you are not running anti-virus software on a system with a Coverity Connect database because it impacts performance and can even interfere with correct functioning of the database, possibly including data corruption. If you must run anti-virus software, disable it for the duration of the upgrade or exempt the <cc_install_dir>/<database> directory from anti-virus inspection.

  • Make sure there is sufficient free space in these locations:

    • The location for the backup if one is needed

    • The volume where the new instance will be installed (if you are not doing an In-place upgrade)

    The free space should be roughly 3x the size of the database, as determined by the size of the <cc_install_dir>/<database> directory’s contents.

  • Make sure you have enough disk space for the upgrade.

  • Make sure that you have the following information prior to launching the installer:

    • Existing Coverity Connect installation directory

    • Destination installation directory (if you plan to perform a Backup-and-restore or Intermachine upgrade)

    • Desired backup directory location (if you plan to create a database backup)

    • Location of your Coverity Connect license file

    • Desired ports for Coverity Connect communications (for Backup-and-restore and Intermachine upgrades)

2.2. Performing an In-place upgrade (standalone instances)

This section describes how to perform an In-place upgrade on a Coverity Connect standalone instance that uses an embedded database.

[Note]

Make sure you have read all of the preceding sections in this chapter before proceeding.

To perform an In-place upgrade on a standalone instance that uses an embedded database:

[Note]

If you are performing an In-place upgrade, the upgrade may fail if the path of the chosen cov-platform installation directory is overly long. As reference, an upgrade on Windows may succeed with paths up to 107 characters, including slash characters. On Linux, 85 characters may be too long. This restriction is due to PostgreSQL.

[Note]

On Linux systems, you must not be logged in as root to upgrade Coverity Connect.

  1. Make sure you have full permissions (rwx) on the existing installation directory.

  2. On the machine where you want to install Coverity Connect and other Coverity Platform components, download the Coverity Platform (this is the correct installer for Coverity Connect) installer file for your operating system.

  3. Run the installer program for your operating system.

    For Windows, we recommend that you install Coverity Connect with Windows Administrator privileges (installing Coverity Connect as a service requires it). To do so, right click the installer and choose Run as Administrator.

    To install, double-click the .exe program.

    For Linux, run the installer script in a Bourne shell, for example:

    > ./cov-platform-linux64-[version].sh

    [Note]

    Depending on the size of your database, the upgrade process can take a long time. If you are performing this operation by way of an SSH terminal, we recommend you use a persistent terminal (such as Screen) in case your session is interrupted.

    The installer uses a text-based console mode or a graphical mode. The installation choices for graphical and console modes are equivalent. To install using graphical mode on Linux, append the –g option to the command above.

    Note that you can change from graphical to silent installer (command line) as described in Chapter 1.2. Coverity Platform installation modes in the Coverity Installation and Deployment Guide. For details about the silent installer options and parameters, see 1.2.3. Coverity Connect silent installer, and in particular see the sub-section In-place upgrade parameters.

  4. Complete the installation process:

    1. Select and accept the license agreement for your region of the world.

    2. Select the In-place Upgrade option.

    3. Follow the installation prompts.

      [Note]Important!

      When you are prompted to choose a performance configuration, you can choose Production or Restore. If you choose Production, the installer runs cov-admin-db tune. This can improve Coverity Connect performance by re-tuning database performance. If you choose Restore, the installer does not run cov-admin-db tune. For details about cov-admin-db tune, see the Coverity 2020.12 Command Reference.

2.3. Performing a Backup-and-restore upgrade (standalone instances)

This section describes how to perform a Backup-and-restore upgrade on a Coverity Connect standalone instance that uses an embedded database.

[Note]

Make sure you have read all of the preceding sections (excluding Performing an In-place Upgrade) in this chapter before proceeding.

Make sure you know the location for the new Coverity Connect installation directory prior to launching the installer.

To perform a Backup-and-restore upgrade on a standalone instance that uses an embedded database:

[Note]

If you are performing a Backup-and-restore upgrade, the upgrade may fail if the path of the chosen cov-platform installation directory is overly long. As reference, an upgrade on Windows may succeed with paths up to 107 characters, including slash characters. On Linux, 85 characters may be too long. This restriction is due to PostgreSQL.

[Note]

On Linux systems, you must not be logged in as root to upgrade Coverity Connect.

  1. Make sure you have full permissions (rwx) on the existing installation directory and the new installation directory.

  2. On the machine where you want to install Coverity Connect and other Coverity Platform components, download the Coverity Platform (this is the correct installer for Coverity Connect) installer file for your operating system.

  3. Run the installer program for your operating system.

    For Windows, we recommend that you install Coverity Connect with Windows Administrator privileges (installing Coverity Connect as a service requires it). To do so, right click the installer and choose Run as Administrator.

    To install, double-click the .exe program

    For Linux, run the installer script in a Bourne shell, for example:

    > ./cov-platform-linux64-[version].sh

    [Note]

    Depending on the size of your database, the upgrade process can take a long time. If you are performing this operation by way of an SSH terminal, we recommend you use a persistent terminal (such as Screen) in case your session is interrupted.

    The installer uses a text-based console mode or a graphical mode. The installation choices for graphical and console modes are equivalent. To install using graphical mode on Linux, append the –g option to the command above.

    Note that you can change from graphical to silent installer (command line) as described in Chapter 1.2. Coverity Platform installation modes in the Coverity Installation and Deployment Guide. For details about the silent installer options and parameters, see 1.2.3. Coverity Connect silent installer, and in particular see the sub-section In-place upgrade parameters.

  4. Complete the installation process:

    1. Select and accept the license agreement for your region of the world.

    2. Select the Backup-and-restore option.

    3. Follow the prompts, selecting the Automated backup and non-database gathering option when it becomes available to you.

      [Note]Important!

      When you are prompted to choose a performance configuration, you can choose Production or Restore. If you choose Production, the installer runs cov-admin-db tune. This can improve Coverity Connect performance by re-tuning database performance. If you choose Restore, the installer does not run cov-admin-db tune. For details about cov-admin-db tune, see the Coverity 2020.12 Command Reference.

  5. Copy modifications from your old to your new server.xml file.

    If you made any modifications to the <install_dir_cp>/server/base/conf/server.xml file of your existing installation (for example, if you modified the keystoreFile or keystorePass properties), copy those modifications to your new installation.

    [Note]

    Copy only the modifications; do not overwrite the entire file.

2.4. Performing an Intermachine upgrade (standalone instances)

This section describes how to perform an Intermachine upgrade on a Coverity Connect standalone instance that uses an embedded database.

An Intermachine upgrade is required if you want to relocate an existing Coverity Connect instance to a new host machine when you upgrade. Otherwise, perform a Backup-and-restore upgrade or an In-place upgrade. For more information, see Section 1.1, “Choosing the type of upgrade”.

To perform an Intermachine upgrade, you will need to run the installer two times. The first time you run the installer, use the Upgrade Preparation option to get a backup of the database and a backup of the non-database state. The second time you run the installer, use the Intermachine Upgrade option to install the new instance using the backups from the Upgrade Preparation step. The procedure in this section describes all of the steps in this process.

To perform an Intermachine upgrade on a standalone instance that uses an embedded database:

[Note]

On Linux systems, you must not be logged in as root to upgrade Coverity Connect.

  1. Make sure you have full permissions (rwx) on the existing installation directory and the new installation directory.

  2. Download the correct Coverity Platform installer file for your operating system. (The Coverity Platform installer also installs Coverity Connect.)

  3. Once the Coverity Platform installer download is complete, run the installer program for your operating system.

    For Windows, we recommend that you install Coverity Connect with Windows Administrator privileges (installing Coverity Connect as a service requires it). To do so, right click the installer and choose Run as Administrator.

    To install, double-click the .exe program.

    For Linux, run the installer script in a Bourne shell, for example:

    > ./cov-platform-linux64-[version].sh

    [Note]

    Depending on the size of your database, the upgrade process can take a long time. If you are performing this operation by way of an SSH terminal, we recommend you use a persistent terminal (such as Screen) in case your session is interrupted.

    The installer uses a text-based console mode or a graphical mode. The installation choices for graphical and console modes are equivalent. To install using graphical mode on Linux, append the –g option to the command above.

    Note that you can change from graphical to silent installer (command line) as described in Chapter 1.2. Coverity Platform installation modes in the Coverity Installation and Deployment Guide. For details about the silent installer options and parameters, see 1.2.3. Coverity Connect silent installer, and in particular see the sub-sections "Upgrade preparation parameters" and "Intermachine upgrade parameters".

  4. To update your existing Coverity Connect instance, complete the Upgrade Preparation process:

    [Note]

    This part of the process shuts down your Coverity Connect server. Plan a maintenance window that covers the remainder of the upgrade process.

    1. Select the Upgrade Preparation option.

    2. Specify the current Coverity Connect installation directory, and select one destination directory for both the database backup and the non-database state backup. The backups in this directory will be used to complete the upgrade on the destination machine.

  5. Complete the Intermachine Upgrade process:

    1. Make sure that the destination machine has access to the backups from the previous step. You could do that by sharing the directory containing your backups or by copying it over to the destination machine.

    2. On the destination machine, launch the installer and follow the on-screen prompts, selecting the Intermachine Upgrade option.

    3. Enter your desired installation directory, then specify the location of the directory where you saved the database backup file and non-database state backup (as part of the Upgrade Perparation step)

    4. Follow the on-screen prompts to complete the upgrade.

Appendix A. Coverity Legal Notice