How to change Citrix Virtual Apps and Desktops SQL database connection string

Case

You have a Citrix Virtual Apps and Desktosp (VAD) installation running on a supported SQL Server instance. You need to change the SQL database connection string inside the Citrix VAD site configuration. The most common reason to do so is because you need to migrate the Citrix VAD databases to a new instance.

Solution

One quick way to work around this issue is to have an SQL design with SQL aliases. If originally using an SQL alias for the Citrix VAD database instance, then there is no need to change any configuration inside the Citrix VAD site but simply change your SQL alias to point to the new SQL database instance.

If you are not using SQL alias though then you need to follow the Citrix recommended procedure for changing the database connection string. Citrix offers several PowerShell scripts that update XenApp and XenDesktop database connection strings when you are using SQL Server high availability database solutions such as AlwaysOn and mirroring. There is always the alternative option to change the SQL connection strings manually.

The scripts, which use the XenApp and XenDesktop PowerShell API, are:

  • DBConnectionStringFuncs.ps1: The core script that does the actual work. This script contains common functions that the other scripts use.
  • Change_XD_Failover_Partner_v1.ps1: Updates (adds, changes, or removes) the failover partner. This script prompts for the failover partner location (FQDN) for each database. (Providing a blank failover partner removes the failover partner. You can also use the ClearPartner option to remove a partner.) Do not set the failover partner to the same location as the principal database server. This is to be used in SQL mirroring configurations.
  • Change_XD_To_ConnectionString.ps1: Uses the provided connection strings to update the connection strings to the databases. This script ensures that certain Citrix services are up and running, and then updates those services in the correct order on all Controllers in the site. Enclose connection string information for each database in quotes. This covers all SQL configuration scenarios.
  • Change_XD_To_MultiSubnetFailover.ps1: Toggles the addition and removal of MultiSubnetFailover=true. If you use Always On Availability Groups, Microsoft recommends that the connection string includes MultiSubnetFailover=true. This option speeds up recovery when a high availability event occurs, and is recommended for both single and multi–subnet environments. Run this script once to add the option. If you must remove the option, use Change_XD_To_ConnectionString.ps1 to run the script again and provide strings without the setting.
  • Change_XD_To_Null.ps1: Resets all the connection strings on the localhost because something has gone wrong. By resetting the connection strings to null, this script places the Controller into an “initial” state. If you run Studio after running this script, you’ll be asked if you want to create a site or join an existing site. This is useful if something has gone wrong and a reset is needed. After the reset, you can try again to set the connection strings using Change_XD_To_ConnectionString.ps1.

You can also update database connection strings manually; see Update strings manually. To download the PowerShell scripts, see the Procedure section.

After changing the SQL connection string it is always a good idea to run the following Powershell Test-ConfigDBConnection cmdlet to test database operations from the Citrix VAD site and also perform at least one hosted desktop/app launch afterwards.

Test-ConfigDBConnection [-DBConnection] <String> [-LoggingId <Guid>] [-BearerToken <String>] [-AdminAddress <String>] [<CommonParameters>]

You can find more detailed guidance and step-by-step procedures for analyzing and troubleshooting Citrix Virtual Apps and Desktops organized by category in my Citrix Virtual Apps and Desktops Troubleshooting e-book.

Sources

Was this article helpful?

Related Articles