Product Documentation


Sep 29, 2015

Gets a script that updates the Host Service database schema.


Get-HypDBVersionChangeScript -DatabaseName <String> -TargetVersion <Version> [-AdminAddress <String>] [<CommonParameters>]

Detailed Description

Returns a database script that can be used to upgrade or downgrade the site or secondary schema for the Host Service from the current schema version to a different version.



Specifies the name of the database instance to which the update applies.

Required? true
Default Value  
Accept Pipeline Input? false


Specifies the version of the database you want to update to.

Required? true
Default Value  
Accept Pipeline Input? false


Specifies the address of a XenDesktop controller to which the PowerShell snap-in connects. You can provide this as a host name or an IP address.

Required? false
Default Value Localhost. Once a value is provided by any cmdlet, this value becomes the default.
Accept Pipeline Input? false

Return Values


A PSObject containing the required SQL script for application to a database.


The PSObject returned by this cmdlet contains the following properties:

-- Script The raw text of the SQL script to apply the update, or null in the case when no upgrade path to the specified target version exists.

-- NeedExclusiveAccess Indicates whether all services in the service group must be shut down during the update or not.

-- CanUndo Indicates whether the generated script allows the updated schema to be reverted to the state prior to the update.

Scripts to update the schema version are stored in the database so any service in the service group can obtain these scripts. Extreme caution should be exercised when using update scripts. Citrix recommends backing up the database before attempting to upgrade the schema. Database update scripts may require exclusive use of the schema and so may not be able to execute while any Host services are running. However, this depends on the specific update being carried out.

After a schema update has been carried out, services that require the previous version of the schema may cease to operate. The ServiceState parameter reported by the Get-HypServiceStatus command provides information about service compatibility. For example, if the schema has been upgraded to a more recent version that a service cannot use, the service reports "DBNewerVersionThanService".

If the command fails, the following errors can be returned.

Error Codes



The operation was successful but had no effect.


The database connection string for the Host Service has not been specified.


An error occurred in the service while attempting a database operation.


The operation could not be completed because the database for the service is not configured.


An error occurred in the service while attempting a database operation - communication with the database failed for various reasons.


You do not have permission to execute this command.


There was a problem communicating with the Citrix Delegated Administration Service.


There was a problem communicating with the remote service.


An unexpected error occurred. For more details, see the Windows event logs on the controller or the XenDesktop logs.


-------------------------- EXAMPLE 1 --------------------------

C:\PS> $update = Get-HypDBVersionChangeScript -DatabaseName MyDb -TargetVersion 
C:\PS> $update.Script > update_75.sql

Gets an SQL update script to update the current schema to version The resulting update_75.sql script is suitable for direct use with the SQL Server SQLCMD utility.