Contents

Overview

New versions of QEST Platform products are often accompanied by structural or data changes to the QEST Platform database. The QEST Script Runner product is used to:

1. Connect to the QEST Platform database

2. Run the script package files provided by Spectra QEST to

   1. Carry out any necessary pre-upgrade database tasks

   2. Perform the core structure and database updates for the new QEST Platform version

   3. Carry out any necessary post-upgrade database tasks

Prerequisites

The following must be present in the target environment in order to update a QEST Platform database:

1. QEST Script Runner must be installed on a machine that can access the QEST Platform database

2. db_owner access to the QEST Platform database for the user QEST Script Runner will use to access the QEST Platform database

3. QEST Script package file(s) to run against the QEST Platform database. 

   1. For a product update there will be up to three package files

      1. (Optional) Pre-upgrade, usually named preinstall-project_V.M.B.R.qestscriptpackage (where V is the major version, M the minor release version and B and R are the build and revision numbers)

      2. Upgrade, named QEST Platform Database Upgrade V.M.B.R.qestscriptpackage

      3. (Optional) Post-upgrade, usually named postinstall-project_V.M.B.R.qestscriptpackage (where V is the major version, M the minor release version and B and R are the build and revision numbers)

   2. The QEST Script Runner can also be used to run a single SQL file or a standalone script package, in which case the file to be run will be needed

This guide assumes that an update is being carried out.

Process

Connection

In order to update a database, QEST Script Runner must first connect to the target database. 

First Time Use

When first launching the QEST Script Runner, the user will be prompted to define a new connection. 

Open

The following details will be required:

1. Server Name: The SQL server or instance name. This can be typed in directly or, if the drop down is used, QEST Script Runner will provide an option to browse for servers

2. Authentication: The type of authentication to use when connecting to the selected SQL server or instance.

   1. If Windows Authentication (default) is used then the Windows user running the QEST Script Runner application will be connecting to the SQL server and QEST Platform database. 

   2. If SQL Authentication is used then a SQL User Name and password will need to be provided in order to log into the server and access the database

3. Database: The name of the QEST Platform database to connect to. This can be typed in directly or, if the drop down is used, QEST Script Runner will search for accessible databases on the designated SQL server or instance.

Subsequent Usage

On subsequent uses of the QEST Script Runner, any recently used connections for the current Windows user running the application will be listed in the Recent drop down. Selecting one of the available options will pre-fill the connection details used previously. 

Open

Changing Connections

Once a connection to a database has been established it can be changed by using the change connection option next to the connection name. This option is useful if a connection has been established to the wrong environment. 

Open

Upgrading

In order to upgrade a QEST Platform database, the provided pre-upgrade, upgrade and post-upgrade files must successfully be run to completion using the QEST Script Runner in that order.

Running a Package

Running a QEST Script Package file consists of the following steps:

Opening the File

A script package file can be opened in the QEST Script Runner by one of three methods:

1. By using the Menu -> Open Script Package option and navigating to the relevant qestscriptpackage file

2. By dragging the relevant qestscriptpackage file into the QEST Script Runner window

3. By double clicking the qestscriptpackage file (installing QEST Script Runner 

Passing Requirements Checks

Package files will come with some verification steps in order to determine whether or not it is safe to run the included scripts. These verification steps are run once a file has been opened in QEST Script Runner and success or failure is reported in the application.

Open

If the requirements checks have passed, the script package can be started. If the checks have failed refer to the Troubleshooting section below. If there is any uncertainty about continuing please contact Spectra QEST.

Starting the Package

Clicking the Start button will apply the current package to the database to which the connection has been established. Progress will be reported in the console along with any problems encountered. If an error is encountered the script package will stop and the last error message retained in the output. Some errors will provide guidance on how they encountered problem should be rectified.  If there is any uncertainty about continuing please contact Spectra QEST.

Troubleshooting

Connect error

When attempting to connect to a database, an error message similar to the below appears:

Resolution

1. Confirm that the current user has access to the database.

Requirements check failed

The requirements check failed when selecting a script package.

Open

Resolution

1. Show details if they are hidden.

2. Read failure details to determine the check which has failed.

Database Version fail

Package version is older than the current database version.

Resolution

The package should not be run, as the database has already been upgraded to a newer version than this package.

Package Version fail

The package should not be run as this package has already been run on the database.

QN Version 4.4 Update fail

The package should not be run as the database will need to be upgraded with an earlier version first. In order to run this package the database must first be upgraded to version 3.7 or later using QESTNET.Upgrade.

If unsure of the exact failure issue, please contact Spectra QEST Help Desk with failure details.