qTest Manager Recovery Decision After a Failed On‑Premises Upgrade

Immediate Decision Framework

The recovery choice depends on whether the database schema migration completed. If the migration did not finish, a full restore from backup is the only supported path. If the migration succeeded and the failure is in post‑migration tasks (service startup, index rebuild, plugin registration), a fix‑forward to the target version may be viable — but only for minor/patch upgrades and when a tested restore is unavailable.

Indicators of Migration Completion

Confirmed facts

• The installer writes a migration marker file (typically under <install_dir>/logs/upgrade/) only after the schema migration step commits.
• The qTest database maintains a Flyway history table (flyway_schema_history or schema_version). A record for the target version with success=1 means migration completed; absence or success=0 means it did not.
• Installer logs may show "upgrade completed" before the DB transaction commits — do not rely on UI success messages alone.

Likely explanation

If the marker file is missing and the Flyway table shows no successful entry for the target version, the failure occurred pre‑migration. In that case the database is still at the source schema and a full restore is straightforward. If the marker exists and the Flyway record shows success, the failure is post‑migration; the database already reflects the target schema.

When Fix‑Forward Is Supported

Confirmed facts (per Tricentis 9.x/10.x upgrade documentation)

• Fix‑forward is considered only for the immediate next minor or patch release (e.g., 9.6 → 9.7).
• The failure must be in post‑migration configuration: service startup, Elasticsearch index rebuild, or plugin registration.
• A full backup exists but has not been validated by a test restore within the last 30 days.
• Major version jumps (e.g., 9.0 → 10.0) involve irreversible data transformations; Tricentis KB articles explicitly require restore for these paths.

Likely explanation

If you are on a minor upgrade and the database migration succeeded, re‑running the installer or manually completing the failed post‑migration step (such as dropping and rebuilding the Elasticsearch index) is often lower risk than an untested restore. However, license key compatibility for the target version must be verified first; an invalid key will block service startup and mimic a migration failure.

Weighing Rollback vs. Fix‑Forward with External Integrations

Confirmed facts

• Integrations (Jira, Azure DevOps, Jenkins, Selenium Grid) bind to specific qTest REST API versions.
• A partial rollback that leaves the database at the new schema while the application runs the old version will break integration authentication and webhook signatures.
• If the Elasticsearch index rebuild fails post‑migration, the application may start but search will be broken; this is a fix‑forward candidate only if the index can be dropped and rebuilt from the upgraded schema.

Likely explanation

When integrations are present, a full restore (application + database) is the only way to guarantee compatibility. A fix‑forward that leaves the database upgraded but the application partially functional will cause integration failures. Therefore, if a validated restore exists, rollback is strongly preferred. Without a validated restore, a fix‑forward on a minor upgrade may be the lesser risk, provided you can complete the post‑migration steps and verify integration connectivity afterward.

Verification Steps

1. Check <qTest_home>/logs/upgrade/upgrade_<timestamp>.log for "Flyway migration completed" or "Schema migration finished" entries.
2. Run against the qTest database:

   SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;

3. Review the Tricentis qTest Upgrade Guide for the specific version pair (e.g., "qTest 9.6 to 9.7 Upgrade Guide") for version‑specific fix‑forward statements.
4. Validate the most recent full backup by restoring to a staging environment and confirming application startup and integration connectivity.

One Missing Diagnostic Detail

What are the exact source and target versions? The version pair determines whether the upgrade is a minor/patch release (fix‑forward possible) or a major release (restore required). This detail changes the recommendation.