Resolving Schema-Related Errors

Author: Amanda Jennewein

Updated: June 2024

Audience: Everyone

Environmental details: Self-Hosted Replicated - Traditional/Native Channels upgrading from v8.6x to 8.7x+

Summary

Users upgrading from Jama Connect versions 8.62.4 to 8.66, and potentially other 8.6x versions to 8.79.x, may encounter database-related errors preventing Jama from starting. These errors are typically logged in the contour.log file, indicating missing columns or incorrect data types, suggesting a schema mismatch.

Symptoms

• Errors contour.log related to the database schema.
• Missing columns or incorrect data types in the database.

Prerequisites for Upgrade

• Jama Connect 8.66 requires MySQL 8.
• Jama Connect 8.62.4 and above may require MySQL 8+ or MSSQL 2017+.

Diagnostic Steps

1. Check the database software and version being used. In case of an error, verify whether MySQL 8 is in use (Jama Connect 8.66 requirement).
2. Inspect contour.log for errors related to database schema mismatch.

Resolution Steps

1. Roll Back to a Previous Backup:
   • Restore the previous virtual machine backups of both the application and the database.
2. Set Up a New MySQL 8 Instance:
   • Follow the Jama Connect Pre-Installation Instructions (LINK HERE).
   • Ensure that the Jama database is empty on the target database server.
   • Set up users, databases, and grants according to the instructions.
3. Configuration and Restoration:
   • Upload the backup file to the restored app server in the /data/restore folder.
   • Save the configuration in the Replicated admin panel.
   • Address any configuration errors reported to the console or support bundle.
4. Post-Restoration Steps:
   • Reindex the database.
   • Update the FQDN or server URL if changed using the 'Fix Url' and 'Fix URL References' Jama Connect® v8.79.x User Guide
   • If the IP address has changed but the hostname remains the same, update the IP address in your network's DNS settings.

Estimated Restoration Time

• Large databases: Up to four hours.
• Smaller databases: Several minutes.

Additional Notes

• Ensure compatibility of database versions before attempting an upgrade.
• Work closely with your IT or Jama Support teams to monitor and resolve any issues during the upgrade process.
• Jama Connect® User Guides and Self-hosted resources: Learn how to access and share specific and unique URLs easily

Please feel free to leave feedback in the comments below.