What indicates an incomplete qTest upgrade after a failed migration?

Direct answer

An incomplete qTest upgrade is indicated by: (1) a non-zero exit code or error output from qtestctl, (2) a mismatch between the schema version recorded in qTest's migration tracking table and the target release, and (3) DDL errors or migration-failure entries in the upgrade and application logs. If the recorded schema version lags the target release, the migration did not finish and the environment should be rolled back to the pre-upgrade database backup rather than used.

Confirmed facts vs. likely explanation

Confirmed: qTest on-premises upgrades apply database schema migrations as part of the qtestctl-driven upgrade, and the upgrade guide requires a pre-upgrade database backup. The likely explanation for an ambiguous state is that the migration was interrupted mid-DDL, leaving tables, columns, or procedures partially applied. The indicators below are the standard way to distinguish a clean upgrade from a failed one, though exact table names and log paths vary by qTest version and topology, so verify against the release-specific guide.

Indicators to check, in order

1. qtestctl upgrade output and exit code

Capture the full console output and the exit status of the upgrade command. A non-zero exit status, exceptions, or 'migration failed' style errors mean the upgrade did not complete. A clean completion message followed by successful service start is the primary success signal.

2. Schema version metadata

qTest tracks applied migrations in a version/migration table inside the application database. Query this table and confirm the recorded version equals the target release documented in the upgrade guide. A recorded version behind the target means some migrations never ran.

3. Log inspection

Search the upgrade-window logs for failed DDL statements, rolled-back transactions, or checksum/validation warnings. Then, after restarting services, inspect the application logs for schema-related errors. Note that services starting cleanly does not by itself prove completeness, since deferred migrations can fail after startup.

4. Application version and smoke test

Confirm the running application reports the new version (about page or status endpoint), then smoke test core workflows: projects, test runs, defects.

Verification steps

# 1. Rerun/inspect upgrade output
./qtestctl upgrade 2>&1 | tee upgrade.log; echo "exit=$?"
# 2. Query the schema version table (name varies by release — check the upgrade guide)
# 3. grep the application logs for DDL errors
# 4. Confirm version in UI and smoke test

Decision rule

If any indicator is ambiguous, restore the pre-upgrade database backup and rerun the upgrade. Running production against a partially migrated schema risks silent data corruption. Manual spot-testing of a few screens can miss partially applied constraints that only surface under specific workflows.

Uncertainty and review note

The exact schema version table name, log file locations, and qtestctl exit-code behavior are version- and topology-dependent and must be confirmed against the release-specific upgrade guide before acting. This draft is conservative and flagged for human review: do not assume the specific table name or exit-code contract without checking the guide for the installed qTest version.