H2 Database Migration

What is H2 and how is it used in TestEngine?

TestEngine uses H2, a Java-based relational database management system, as its embedded database. H2 is responsible for storing key information, including:

  • Test job history

As part of SmartBear's continuous maintenance and program to enhance TestEngine, we are upgrading to the latest version of H2, currently at V 2.2.224 (July 2024). This upgrade ensures better security management and takes advantage of the latest features in H2's embedded database technology.

Do I need to go through the upgrade process?

All customers migrating to the latest version of TestEngine, 1.32.0, must complete the migration process.

Steps to Migrate

Warning

You must complete the database migration before running the TestEngine installer for the latest version.

To migrate the database, follow these steps:

  1. Download the migration scripts package

    Download the migration scripts package file from H2 Migrator.

  2. Extract the package

    Extract the package to your Downloads folder.

    After extraction, a new H2 migration folder is created.

  3. Navigate to the migration folder

    Open the migration folder corresponding to your operating system.

    TE_Screenshot_H2Migration_01.png

    • For Windows: The folder will contain .bat files.

    • For Linux/Mac: The folder will contain .sh files.

  4. Review the README file

    The README file in the migration folder contains additional instructions for steps 5–7 below.

  5. Stop TestEngine

    If TestEngine is running, stop it before proceeding.

    Warning

    Database migration can only be performed when TestEngine is stopped.

  6. Run the migration script

    Execute the h2-migrator.bat (Windows) or h2-migrator.sh (Linux/Mac) migration script and wait for the process to complete.

  7. Restart TestEngine

    After the migration is complete, restart TestEngine either as an application or a service.

Need assistance? Contact Support

If you have any questions or encounter issues during the upgrade process, please reach out to Support for assistance. You can also request a technical session with our Solution Engineering team for additional help. To arrange this, please contact your SmartBear Account Manager.

How to revert to an earlier version of TestEngine

From October 2023, file-based licensing is no longer be available and is fully replaced by SmartBear ID-based licensing - SmartBear ID-based licenses are a new license management option that we started using in ReadyAPI 3.8.1. Support for SmartBear ID-based licenses was added to TestEngine 1.28.0 (SLM on-premise support) and 1.29.0 (added support for SLM SaaS).

If you need to revert to a previous version of TestEngine, ensure you choose a version after 1.29.0 to maintain compatibility with SLM licenses. Learn more about licensing changes on the SmartBear ID-based Licenses page.

Reverting the Database Migration

After migration, a backup file of the old database is created in your database file location. The reverting process relies on this backup file.

Backup File Naming Rules

For the reverting script to work correctly:

  • The backup file name must include the word “backup”.

  • The file extension must be ".mv.db”.

While it’s best not to rename the backup file, you can rename it if necessary, as long as the above rules are followed.

Reverting Process for a Database in the Default Location (.readyapi)

TE_Screenshot_H2Migration_03.png

  1. Verify the Migration: Ensure the database was correctly migrated by checking the database folder for the following files:

    TE_Screenshot_H2Migration_02.png

  2. Run the Reverting Script: Execute the revert_h2_migration.sh (Linux/macOS) or revert_h2_migration.bat (Windows) script.

    user.name@servername resources % ./revert_h2_migration.sh

  3. Outcome: Once the script completes, the database migration will be reverted.

    Example Output and Folder Structure After Reversion:

    user.name@servername resources % ./revert_h2_migration.sh
File testengine.mv.db has been renamed to testengine-2024-07-23.mv.db
File testengine-backup-20240723.******.***-******.mv.db has been renamed to testengine.mv.db.
user.name@servername resources %

Reverting Process for a Database in a Custom Location

If your database is stored in a custom location, follow these steps:

  1. Verify the Migration: Ensure the database was correctly migrated by checking the database folder for the following files:

    TE_Screenshot_H2Migration_04.png

  2. Run the Reverting Script with the --db_path Argument: Use the full path to the testengine.mv.db file as the db_path argument.

    Example: revert_h2_migration.sh --db_path=/full/path/to/testengine.mv.db

    user.name@servername resources % ./revert_h2_migration.sh --
db_path=/Users/user.name/Documents/not_default_location/testengine.mv.db

  3. Outcome: After running the script, the database migration is reverted.

    Example Output and Folder Structure After Reversion:

    user.name@servername resources % ./revert_h2_migration.sh --
db_path=/Users/user.name/Documents/not_default_location/testengine.mv.db
File testengine.mv.db has been renamed to testengine-2024-07-23.mv.db
File testengine-backup-20240723.******.***-******.mv.db has been renamed to testengine.mv.db.
user.name@servername resources %
    TE_Screenshot_H2Migration_05.png

See Also

In this section:
© 2025
Publication date: