Using the Database Upgrade Tool

The command-line Database Upgrade Tool can be used ahead of the Keyfactor Command software installation to bring the database up to the current version. This can be used to test database upgrades and resolve any issues before going forward with a full Keyfactor Command upgrade. If you have previously encountered upgrade issues or want to test the database upgrade step without risking downtime, this may be a good option for you. You can run the database upgrade tool on a temporary restored copy of the database without interrupting operations to confirm that the database upgrade will succeed and then upgrade the production database immediately before upgrading the server software.

System Requirements

The Database Upgrade Tool can be used on any server with access to the SQL server hosting the Keyfactor Command database. It does not need to be run on the Keyfactor Command server.

The Database Upgrade Tool has the following requirements:

• Windows Server 2019 or greater.

• Microsoft .NET Runtime version 8.0 (x64). Version 8.0 is available for download from Microsoft:

  https://dotnet.microsoft.com/download/dotnet/8.0/runtime

  You need only the .NET Runtime (x64), not the ASP.NET Core Runtime or ASP.NET Core Hosting Bundle. At the above link, this would be the Download x64 option under the Run console apps heading.

  

  Figure 658: Select the Download x64 Option Under Run Console Apps

  You can use the following PowerShell command to check the .NET core version(s) installed on a server (if any):

  dotnet --list-runtimes

  Output from this command will look something like this if you have the correct 8.0 x64 version of the .NET Runtime installed (notice the path is in C:\Program Files, not C:\Program Files (x86), indicating this is the x64 version):

  Microsoft.NETCore.App 8.0.4 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

Using the Database Upgrade Tool

The Database Upgrade Tool Does not need to be installed.

To use the Database Upgrade Tool:

1. Copy the zip file to the server on which it will be used and unzip it to a temporary working directory.
2. In the temporary working directory locate the Database Upgrade Tool\Configuration\appsettings.json file and open this file for editing using a text editor.

3. Edit the SqlDirect and EFModel connection strings appropriately for your environment and upgrade plan (production database vs temporarily restored test database).

   Copy

   {
     "ConnectionStrings": {
       "SqlDirect": "Data Source=<SQL_MACHINE_FQDN>;Initial Catalog=<SQL_DB_NAME>;Integrated Security=True;Persist Security Info=True;Command Timeout=360",
       "EFModels": "metadata=res://*/EFModels.csdl|res://*/EFModels.ssdl|res://*/EFModels.msl;provider=Microsoft.Data.SqlClient;provider connection string='Data Source=<SQL_MACHINE_FQDN>;Initial Catalog=<SQL_DB_NAME>;Integrated Security=True;Persist Security Info=True;Command Timeout=360;Multiple Active Result Sets=True;Application Name=EntityFramework'"
     },
     "SqlRetryConfiguration": {
       "NumberOfTries": "5",
       "DeltaTime": "00:00:00.5",
       "MaxTimeInterval": "00:02:00"
     }
   }

4. If you’re upgrading a database in active use by Keyfactor Command, stop the IIS and Keyfactor Command services on the Keyfactor Command server.
5. Open a command prompt and change to the temporary working directory where you copied the Database Upgrade Tool.
6. Execute the DatabaseUpgradeTool.exe. The tool does not have any parameters.

7. It will take a few moment for output to appear and then you will begin to see output as the upgrade tool processes through the upgrade modules that are needed for your database. The modules that will appear will vary depending on the starting version of your database, but output will look something like the following:

   2024-10-08 08:36:36.7603  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Starting Configuration Wizard Console - Upgrade Only.
   2024-10-08 08:36:36.9278  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Warn] - No valid DbCommandTimeout provided, defaulting to 1800 seconds.
   2024-10-08 08:36:37.2713  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Removed 'CSR Enabled' as an option within App Settings.. 0 of 130 complete
   2024-10-08 08:36:37.2713  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Increase Name, Display Name, and Default Value's column size to 4000 in table cms_agents.CertStoreTypeProperties.. 1 of 130 complete
   2024-10-08 08:36:37.3030  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Increase Name, Display Name, and Default Value's column size to 4000 in type CertStoreTypePropertyDetail.. 2 of 130 complete
   2024-10-08 08:36:37.3177  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Remove F5 certificate store types.. 3 of 130 complete
   2024-10-08 08:36:37.3745  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Regenerating audit key (~3 mins/1 million records). 4 of 130 complete
   2024-10-08 08:36:37.4624  CSS.CMS.Install.Upgrade.Modules.RegenerateAuditSigningKey [Info] - Successfully regenerated audit log signing key.
   2024-10-08 08:37:19.3760  CSS.CMS.Install.Upgrade.Modules.RegenerateAuditSigningKey [Info] - Successfully re-signed audit log entries
   2024-10-08 08:37:19.3931  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Add secret ID columns for deterministic Guid removal.. 5 of 130 complete
   2024-10-08 08:37:19.4215  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Migrate to non-deterministic Guids. 6 of 130 complete
   
   Section removed for brevity.
   
   2024-10-08 08:37:49.4083  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Adds InstanceGuid to Command API client secret secret. 127 of 130 complete
   2024-10-08 08:37:49.4083  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Rename EncodeAsPlusSigns to DeltaCRL column for revocation monitoring. 128 of 130 complete
   2024-10-08 08:37:49.4488  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Running module Refresh all SQL modules (procedures, views, etc.). 129 of 130 complete
   2024-10-08 08:37:49.6618  Keyfactor.Command.DatabaseUpgradeTool.Wizard [Info] - Upgrade completed successfully.

8. Confirm that the upgrade completed successfully.
9. If you upgraded the production database, install the upgraded Keyfactor Command software.

Table 1057: Appsetting.json File - SQL Parameters

Setting	Description
Connection Strings	SQL connection strings. Setting Description SqlDirect The SQL connection string using plain text values. EFModels The entity framework connection string using plain text values.
Sql Retry Configuration	SQL retry settings (seeKeyfactor Command Changing SQL Retry Settings for more information). Setting Description Number Of Tries The number of times a connection attempt will be made to SQL before an exception is thrown. The default is 5. Delta Time The preferred gap time to delay before the next attempt to connect to SQL will be made. The default is .5 (1/2) second. Max Time Interval The maximum time interval before the next attempt to connect to SQL will be made. The default is 2 minutes.