SQL Sentry EPI Upgrade

Upgrade SQL Sentry via EPI

See the EPI article for details on using the Enhanced Platform Installer.

SQL Sentry Client Impacts

How does using EPI impact the SQL Sentry client during an upgrade?

If a SQL Sentry user has the SQL Sentry client open, they receive an alert informing them that the SQL Sentry client must be shut down due to an upgrade. It will ask them to exit the application and display a "shutdown countdown" starting at 120 seconds.

How does using EPI impact the SQL Sentry client after an upgrade?

When the SQL Sentry client is launched after an upgrade, a message appears, indicating to the user that the client is checking for updates and asks them to wait while the client is updated.

SQL Sentry Client Checking for UpdatesUpdate message displayed to user in client

Things to Know Before Upgrading

Important: 

  • Back up the SQL Sentry database before performing an upgrade.
  • A major version upgrade requires a license upgrade. See the Product Version Mismatch section of the License Management article for more information.
  • Review the System Requirements before upgrading. The latest version may require a newer version of Microsoft .NET, which could require restarts during the upgrade process.
  • All SQL Sentry components, including the SQL Sentry database, monitoring service(s), and client(s) must be on the same build to work.
  • See the Password section of this article for information on using non-alphanumeric characters such as spaces or quotes with the -p flag. The command will stop, and monitoring and controller service installations will fail if these characters are not properly formatted with quotes and the backslash escape character.

Note: 

  • Review the Parameters & Examples section for more information about the <parameters> used in the following commands.
  • If you experience any Result = Timeout messages while a command is running, refer to the Advanced section for more information. This does not mean the operation timed out.
  • If you are unsure about which version of SQL Sentry you have installed (EPI or non-EPI), you can determine this from the presence of: 
    • The SQL Sentry controller service, which only exists in the EPI version. 
      • See the list command in the Available Commands section to get a list of monitoring services that are running without the controller. 
    • The Setup.Bootstrapper table in the SQL Sentry database, which only exists in the EPI version. 
    • If you need additional help determining which version you have installed, please contact our support team at support.sentryone.com.

Files referenced in upgrade instructions

There are two SQL Sentry Enhanced Platform Installer files available from the SolarWinds Customer Portal: The full installation (Enhanced Platform Installer / SolarWinds-SQLSentry-EPI-{Version}.exe such as SolarWinds-SQLSentry-EPI-2021.8) and the upgrade package (Enhanced Platform Upgrade Package / SolarWinds-SQLSentry-EPIUpgradePackage-{Version}.s1package such as SolarWinds-SQLSentry-EPIUpgradePackage-2021.8.s1package).

Full installation file:  SolarWinds-SQLSentry-EPI-{Version}.exe

Upgrade package file:  SolarWinds-SQLSentry-EPIUpgradePackage-{Version}.s1package

DEPRECATED (SentryOne Branded SQL Sentry)

The files referenced here are only for versions prior to 2021.8.

There are two files available from my.sentryone.com: The full installation (Enhanced Platform Installer / SentryOneSetup.exe) and the upgrade package (Enhanced Platform Upgrade Package / current.s1package).

Note:  Depending on your environment, the current.s1package may download as current.zip. You will need to change the file type to .s1package.

Download SentryOneSetup.exe from my.sentryone.com before startingExample: Download the Enhanced Platform Installer product from my.sentryone.com to get SentryOneSetup.exe

Download the current.s1package from my.sentryone.comExample: Download the Enhanced Platform Upgrade Package from my.sentryone.com to get current.s1package

Upgrade Paths

Warning:  

  • There are three different upgrade paths.
    • If you used EPI for the installation or previous upgrade, follow the first set of instructions under Option 1. Existing EPI Upgrade. Note that going from a pre v20 release to a v20.0+ release has some additional prerequisite steps (i.e. v19.2 to v20.0, v20.0.1, or v2020.x) that must be completed for Option 1.
    • If your installation or previous upgrade did not use EPI, follow the second set of instructions under Option 2. First EPI Upgrade.
    • If you used EPI for the installation or previous upgrade, and are now upgrading to Version 20.0 (or 2020.x), there is an alternate path available under Option 3. Version 20.0 Existing EPI Alternative which allows you to upgrade from a pre v20 release to a v20+ release without having to uninstall/install the controller service on all machines with a monitoring service at the time of the upgrade. This is not the typical or recommended path.

Option 1. Existing EPI to EPI upgrade

Warning:  For Version 20.0, customers currently on an EPI build of SQL Sentry must follow these steps before continuing to the steps listed in Option 1. Existing EPI Upgrade.

These steps are needed to go from any pre v20 release to a v20+ release (i.e. 19.2 to 20.0, 20.0.1, or 2020.x). If you are upgrading from a v20+ EPI release to another v20+ EPI release, skip the perquisite steps and continue to Option 1. Existing EPI Upgrade below.

Before starting, log in to the SolarWinds Customer Portal and download the latest EPI version of SQL Sentry.

Option 1. Prerequisite Steps for an Existing EPI Upgrade (pre v20 to v20+)

On each server with an existing SQL Sentry monitoring service, complete the following steps:

1. Run Command Prompt as Administrator and change the directory to SentryOne Framework:

cd c:\Program Files\SentryOne Framework

2. Uninstall the SQL Sentry Monitoring service.

so uninstall -n <connectionName>

3. Open the Control Panel > Programs > Programs and Features. Select SQL Sentry (or SentryOne), then select Uninstall.

4. Double-click SolarWinds-SQLSentry-EPI-{Version}.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

5. Install the SQL Sentry monitoring service (you will be prompted for the <serviceAccount> password):

Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.

so install --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount> 

Versions prior to 2020.8 use the following:

so install -n <connectionName> -u <serviceAccount> 

Success: You can now proceed to Option 1. Existing EPI Upgrade to complete your SQL Sentry EPI Version 20.0 installation.

Option 1. Existing EPI Upgrade

Use this option if EPI was used for the initial installation or previous upgrade. 

Note:  For version 20.0 follow the prerequisite steps listed above before continuing. These steps are needed to go from any pre v20 release to a v20+ release (i.e. 19.2 to 20.0 or 20.0.1).

1. Run Command Prompt as Administrator and change the directory to SentryOne Framework:

cd c:\Program Files\SentryOne Framework 

2. Verify that you have the correct connection to the SQL Sentry database:

so listreg

3. Push the .s1package to the SQL Sentry database:

so push -n <connectionName> -f <packagePath>

Note:  You can omit the -f option if you installed the SentryOne Frameworks installer with the version you want to upgrade to.

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\SolarWinds-SQLSentry-EPIUpgradePackage-{Version}.s1package

4. Validate available packages:  

so listpackage -n <connectionName>

5. Start the upgrade. Note:  See more about using the upgrade command in the EPI Commands article.

If your currently installed version is below 2020.8 use the following:

so upgrade -n <connectionName> -t <packageVersion>

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

so upgrade --IAcceptLicenseTerms -n <connectionName> -t <packageVersion>

6. Wait for the upgrade to complete.

Note:  The upgrade command so upgrade is a global command that informs all controller services that a new desired state has been marked with a version increase to version <packageVersion>. Once this new state is detected, any monitoring service connected to the affected SQL Sentry database will be stopped, upgraded, and restarted after the upgrade completes. If any client processes are detected, the user will be notified that they have two minutes to exit the client before it is stopped to proceed with the upgrade. There is no status indicator. 

Important:  The EPI installation adds a SQL Sentry Client shortcut to the desktop, but does not install the client. Running the executable file that the shortcut points to opens the Client installer and then installs the Client on the machine. You can remove the SQL Sentry Client shortcut if you don't want to install the client. 

7. Launch the SQL Sentry client. You will see a loading dialog as files are downloaded from the SQL Sentry database for the latest version of the client. It may take a few minutes for the files to download.

Note:  To verify the status of the upgrade without launching the client, validate the package:

so listpackage -n <connectionName>

Success: The SQL Sentry installation has been upgraded and is now ready for use.

Note:  If you are using SQL Sentry Portal, see the upgrading section of this article to complete the upgrade steps for that service.

Option 2. First EPI upgrade

Use this option if EPI was not used for the initial installation or previous upgrade. The .NET Framework 4.7.2 is installed during this process, which may force a reboot.

1. Uninstall all current SQL Sentry monitoring services using Add/Remove Programs in Windows.

Important:  For Version 20.0, you must perform the monitoring service uninstall before proceeding.

2. Ensure all SQL Sentry clients are closed (disconnected from the SQL Sentry database). For Version 20.0, it is required that you uninstall the SQL Sentry clients from the machines in your SQL Sentry environment before proceeding.

3. Double-click SolarWinds-SQLSentry-EPI-{Version}.exe

Note:  The files are unpacked to C:\Program Files\SentryOne Framework.  

4. Run Command Prompt as Administrator and change directory to SentryOne Framework: 

cd c:\Program Files\SentryOne Framework 

5. Add a new connection:

Using Integrated Windows Authentication

so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>

Using SQL Server Authentication

so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName> --connectionUseIntegrated false --connectionUsername <SQLServerUserName> --connectionPassword <SQLServerUserPassword> --connectionPort <SQLServerConnectionPort>

6. Verify available connections are registered:

so listreg

7.Push the upgrade package:

so push -n <connectionName>

Important:  If you are on a version older than 18.3, skip this step, and proceed straight to step 8 to continue.

8. Upgrade the SQL Sentry database to the latest version and push upgrade package:

so upgradedb -n <connectionName>

9. Install the SQL Sentry monitoring service (you will be prompted for the serviceAccount password):

Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA:

so install --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount>

Versions prior to 2020.8 use the following:

so install -n <connectionName> -u <serviceAccount>

Note:  The SQL Sentry monitoring service is now installed and running. 

Important:  The EPI installation adds a SQL Sentry Client shortcut to the desktop, but does not install the client. Running the executable file that the shortcut points to opens the Client installer and then installs the Client on the machine. You can remove the SQL Sentry Client shortcut if you don't want to install the client. 

9. Launch the SQL Sentry client. You will see a loading dialog as files are downloaded from the SQL Sentry database for the latest version of the client. It may take a few minutes for the files to download. 

Note:  To verify the status of the upgrade without launching the client, validate the package:

so listpackage -n <connectionName>

Note:  See the Install Additional Clients and Install Additional Monitoring Services sections of this article for instructions on installing the EPI compatible versions of the SQL Sentry client and monitoring service onto additional machines as needed.

Success: The SQL Sentry installation has been upgraded and is now ready for use. The next time you need to upgrade, use Option 1 for an Existing EPI Upgrade.

Option 3. An alternative option (non-typical path)

Option 3 allows you to upgrade from a pre v20 release to a v20+ release without having to uninstall/install the controller service on all machines with a monitoring service at the time of the upgrade. This is not the typical or recommended path. This options allows you to upgrade SQL Sentry controller services on your own schedule, if needed. It is not required to upgrade the controllers at the same time.

Warning:  Option 1 is the recommended upgrade path. The upgrade option below does not upgrade the controller services and future compatibility is not guaranteed with this alternative option.

Important:  The upgraded controller services are needed to install and use SQL Sentry Portal. This option does not meet those requirements.

For this option, you'll need to upgrade the SQL Sentry framework on one machine. The instructions vary depending on which (if any) SQL Sentry components are installed on the machine where you are running the EPI upgrade. Read below to determine if you should use Option A or Option B.

Option A: Machine without services

On a machine that does not have the SQL Sentry monitoring or controller services, follow these steps:

1. If there's an existing installation of the SQL Sentry framework, open the Control Panel > Programs > Programs and Features. Select SQL Sentry, then select Uninstall to remove it before continuing.

2. Install the v20.0 SentryOne Framework. Double-click SolarWinds-SQLSentry-EPI-{Version}.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

3. Run Command Prompt as Administrator and change the directory to SentryOne Framework:

cd c:\Program Files\SentryOne Framework 

4. Verify that you have the correct connection to the SQL Sentry database:

so listreg

5. Push the .s1package to the SQL Sentry database:

so push -n <connectionName> -f <packagePath>

Note:  You can omit the -f option if you installed the SentryOne Frameworks installer with the version you want to upgrade to.

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\SolarWinds-SQLSentry-EPIUpgradePackage-{Version}.s1package

6. Validate available packages:  

so listpackage -n <connectionName>

7. Start the upgrade. Note:  See more about using the upgrade command in the EPI Commands article.

If your currently installed version is below 2020.8 use the following:

so upgrade -n <connectionName> -t <packageVersion>

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

so upgrade --IAcceptLicenseTerms -n <connectionName> -t <packageVersion>

8. Wait for the upgrade to complete before starting the SQL Sentry client.

Note:  If you are using SQL Sentry Portal, see the upgrading section of the SQL Sentry Portal Configuration article to complete the upgrade steps for that service.

Option B: Machine with services

On a machine that has the SQL Sentry monitoring or controller services, follow these steps:

1. Run Command Prompt as Administrator and change the directory to SentryOne Framework:

cd c:\Program Files\SentryOne Framework 

2. Verify that you have the correct connection to the SQL Sentry database:

so listreg

3. Uninstall the service:

so uninstall -n <connectionName>

4. Uninstall the existing installation of the SentryOne framework by opening the Control Panel > Programs > Programs and Features. Select SQL Sentry, then select Uninstall to remove it before continuing.

5. Install the v20.0 SentryOne Framework. Double-click SolarWinds-SQLSentry-EPI-{Version}.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

6. Install the SQL Sentry monitoring service (you'll be prompted for the password):

Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA:

so install --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount>

Versions prior to 2020.8 use the following:

so install -n <connectionName> -u <serviceAccount>

7. Push the .s1package to the SQL Sentry database:

so push -n <connectionName> -f <packagePath>

Note:  You can omit the -f option if you installed the SentryOne Frameworks installer with the version you want to upgrade to.

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\SolarWinds-SQLSentry-EPIUpgradePackage-{Version}.s1package

8. Validate available packages:  

so listpackage -n <connectionName>

9. Start the upgrade. Note:  See more about using the upgrade command in the EPI Commands article.

If your currently installed version is below 2020.8 use the following:

so upgrade -n <connectionName> -t <packageVersion>

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

so upgrade --IAcceptLicenseTerms -n <connectionName> -t <packageVersion>

10. Wait for the upgrade to complete before starting the SQL Sentry client.

Note:  If you are using SQL Sentry Portal, see the upgrading section of the SQL Sentry Portal Configuration article to complete the upgrade steps for that service.

Upgrade SQL Sentry Portal

If you installed SQL Sentry Portal using EPI, you can upgrade via EPI by following the steps below. The upgrade process involves uninstalling, then reinstalling SQL Sentry Portal. You must upgrade the SQL Sentry version first via EPI, before you can upgrade the SentryOne Portal version.

Note:  The default SentryOne Framework directory is used in the instructions. If you used a non-default location, use that path instead.

  1. Open Command Prompt (use the Run as administrator option)
  2. Change to the SentryOne Framework directory
    cd C:\Program Files\SentryOne Framework
  3. Stop the SQL Sentry Portal service
    so stopmp -n <connectionName> -s <portalServerFQDN>
  4. Uninstall the SQL Sentry Portal
    so uninstallmp -n <connectionName> -s <portalServerFQDN>

5. Install the SQL Sentry Portal

Using Integrated Windows Authentication

so installmp --IAcceptLicenseTerms -n <connectionName> -s <portalServerFQDN> -u <serviceAccount>

Using SQL Server Authentication

so installmp --IAcceptLicenseTerms --connectionUseIntegrated false --server <portalServerFQDN> --connectionServer <serverName> --connectionDatabase <databaseName> --connectionUsername <SQLServerUserName> --connectionPassword <SQLServerUserPassword>

Versions prior to 2020.8 use the following:

so installmp -n <connectionName> -s <portalServerFQDN> -u <serviceAccount> -b <ipAddress:port>

6. Start the SQL Sentry Portal service

so startmp -n <connectionName> -s <portalServerFQDN>

Note: 

  • The --server (-s) switch is for the server that will host SQL Sentry Portal (<portalServerFQDN>) and must be the Fully Qualified Domain Name (FQDN). If needed, this name can be found by using the list command to view the Controller Service value. See the EPI Commands article for additional information on using list.
so list -t services -n <connectionName> 
  • The switch -b <ipAddress:port> is not valid in versions 2020.8.31 or later. This version uses the Portal Configuration Utility to make updates after installing.
    • Prior to that release, it can be omitted if you're using the default value of 0.0.0.0:9991. Prior versions cannot use the Portal Configuration Utility with EPI and must set the binding duirng installation, or uninstall then reinstall to make changes.
  • See the Parameters & Examples section of the EPI article for more information on the <parameters> used such as <serverName> and <databaseName>. These are referring to the SentryOne database and the SQL Server that hosts it.

Downgrade (non-typical process)

In the event that a downgrade or rollback is required, the process will differ depending on whether the database schema changed between versions.

Verify the schema

Use the listpackage command to view the details of the old and new package:

so listpackage -n <connectionName>

Same Schema Version

If the schema version is the same between the old and new packages, then you can downgrade to the older version using the upgrade command and the older package:

so upgrade --IAcceptLicenseTerms -n <connectionName> -t <packageVersion>

There is no need to run any uninstall commands in this scenario.

Note:  See more about using the upgrade command in the EPI Commands article.

Different Schema Version

If the schema version is different between the old and new packages, then you should:

  1. Restore the SQL Sentry database from backup
  2. Uninstall the current version using so uninstall (see the Uninstall section in this article for details) or through the control panel
  3. Reinstall the previous monitoring service and controller version using the so install command

Available Commands

See the EPI Commands article for a table of available commands and flag examples.

Troubleshooting

Problem: The upgrade process is being blocked

If this is for the first option, where EPI already exists, it's possible that SQL Sentry components were installed before using the EPI. For example, there may be clients connected to the SQL Sentry database that were installed pre-EPI. In this scenario, there are no bootstrappers running to manage those client processes, which means that the so upgrade command cannot control those pre-EPI clients. The pre-EPI clients will continue sending a heartbeat to the SentryOne, and the upgrade will be blocked until the clients are shut down.