upgradetest
Use the upgradetest program to check for potential problems with updating the database. It runs all the necessary patchdb scripts, allowing any errors in their execution to be identified and addressed before an upgrade.. Errors identified by upgradetest should be reported to Bravura Security Support.
This program is shipped along with the installation package.
Warning
The patchdb scripts are not a dry run. upgradetest irreparably modifies the database it runs against. Always run it against a restored copy of the production database, never a live instance. To run the utility again, you must restore a fresh copy.
Requirements
The patchdb script executions are not a dry-run and will upgrade the database. Before running this tool, you must copy the production database to another server.
The server to which the database is copied must be the same edition as the production database. The result of the patchdb script executions by upgradetest will differ depending on the edition of SQL Server it is running against. If that edition differs from production, it may result in false positive errors or otherwise inaccurate results.
The upgradetest utility must be run from the installation folder where it is provided. It relies on idm.msi (or idm_debug.msi) to be in the same folder. It will then know which upgrade scripts to run from that .msi file.
The database must be at schema version 9.0.0 or later, and the installation package must be the same version as, or newer than, the version already installed. The utility will not downgrade a database.
The utility protects against accidental misuse: it refuses to run if it detects a live instance connected to the database, and it refuses to run a second time against a database it has already modified. If this happens, restore a fresh copy of the database and try again.
Best practice
Use the utility from the installation package for the version to which the instance will be upgraded.
Preparation
Before running upgradetest:
Copy the instance database to another SQL server.
Set up an account that has access to the database copy.
The account should be similar to the production account that Bravura Security Fabric uses to access the database (name can differ, but permissions and access should be the same). See Database, user, schema for steps to set up the user.
Copy the installation package to the new server.
Usage
Open the Bravura Security Fabric command prompt as an administrator, change to the installation folder, and run the utility. You must specify exactly one authentication method: either -u or -windowsauth.
upgradetest.exe -db <database> -s <server> ( -u <user> | -windowsauth ) [ -createuser ] [ -runbook <file> ] [ -strict ]
Argument | Description |
|---|---|
-db, --db <database> | Name of the database to upgrade (required) |
-s, --server <server> | Address of SQL Server backend (required) |
-u, --username <username> | User name to connect to the SQL Server backend with. Cannot be combined with |
-windowsauth | Use Windows authentication using the current user (do not prompt for password). Cannot be combined with |
-createuser | Create a new database user to perform the upgrade. You are prompted for the new user's username and password, and the utility reconnects as that user to run the scripts. The connecting account ( |
-runbook <file> | Record a runbook of failures and resolutions in the named file. Each failed statement is logged, along with skips and aborts. When a retried statement succeeds, you are prompted for a one-line description of what you did to resolve it, which is saved to the file. |
-strict | Perform strict database schema verification, which also checks for unexpected tables. By default, verification is not strict. |
Example
upgradetest.exe -s sqlserver -db enterprisedb -u sqladmin
Handling failures
The utility installs each upgrade script in turn. If a statement fails, it displays the failed statement and prompts for an action:
Failed statement: <statement> [R]etry, [A]bort, [S]kip?
Retry reruns the statement. Use this after correcting the target database or editing the upgrade script. While the utility is running, the extracted upgrade scripts are located in
%LOCALAPPDATA%\Temp\<guid>\db\upgrade\.Abort stops the test. The database is left partially modified and is no longer reusable; discard it and start from a fresh copy.
Skip skips the statement and continues. Skip is only offered for statements that can be safely skipped, so it does not appear for every failure.
After the scripts complete, the utility performs a schema verification pass and reports whether it succeeded or failed.
Output and logs
Progress and results are written to the console and to upgradetest.log in your temporary folder (%LOCALAPPDATA%\Temp\upgradetest.log). Review the log for any failures and report them to Bravura Security Support.