What is H2 and how is it used in ReadyAPI?

H2 is a Java-based relational database management system embedded in ReadyAPI. It is used to store the following:

Results from test runs
Dashboard layout and results
Logs and statistics for Performance Tests

As part of SmartBear's continuous maintenance and program to enhance ReadyAPI, we are upgrading it to the latest version of H2, currently at V 2.2.224. This upgrade enhances security management and leverages the latest embedded database versions for improved performance.

Do I need to go through this upgrade process?

The migration of data is not obligatory if you are running ReadyAPI for the first time, and it also remains optional for others. It is also not a prerequisite for using the application. If you choose not to migrate existing data and proceed with a new H2 installation, the following data will be unavailable:

Results from test runs
Dashboard layout and results
Logs and statistics for Performance Tests

What will happen when I start or update ReadyAPI 3.51?

If you are using ReadyAPI 3.51 as a new user, there will be no impact, and you'll start the product with a new H2 database, requiring no migration.

If you are an existing user with data in older ReadyAPI versions, a new screen will appear, guiding you through the process. When you start ReadyAPI, you will go through the following steps:

Starting ReadyAPI
- When you start ReadyAPI without databases, the application launches with new, empty databases using the H2 2.2.224 driver.
- When you start ReadyAPI with databases of version 1.4.200, the application will display a pop-up with description of the migration process.
  
  Click the image to enlarge it.
  - When you select I want a quick upgrade, no need to migrate data option, it expands the dialog to the following state:
    
    Click the image to enlarge it.
    - You may select to Exit. The application will close without any migration.
    - Or, click Upgrade, no migration button. The application will retain existing databases in their current locations and start with empty databases.
  - When you select I want to migrate my data with the upgrade option, it expands the dialog to the following state:
    
    Click the image to enlarge it.
    - You may select to Exit.
    - Or, select Path to H2 driver, It can provide path to old ReadyAPI installation directory, path to the old driver, and also allow the application to download the driver.
      
      The drivers will be stored in the <ReadyAPIInstallation>/bin directory and will be deleted after the script finishes execution.
      
      Once you determine the method to provide the driver to the application, click the Upgrade, migrate data button. After confirmation, the script execution dialog will appear, displaying logs from the migration script execution.
  - If the script succeeds, the following options will be shown:
    
    Click the image to enlarge it.
    
    After clicking Continue, the application will start with the migrated data.
  - If the script fails, the following options will be shown:
    
    Click the image to enlarge it.
    - You may select Log support ticket and a new Support Request will be opened on the Customer Support Portal.
    - Or, choose Upgrade, no migration, and the old databases will stay in their current location. The application will start with empty databases.
    - Or, click on Exit to close the application. The application will then shut down.
Using ReadyAPI headlessly with command line runners (Functional, Security, Performance Test Runners)
- When you run command line test runners (i.e. Testrunner, Securitytestrunner, PerformancetestRunner) for the first time on version 3.51, a message explaining migration options appears if ReadyAPI detects no prior data migration.
  
  Example
  
  2023-11-29 14:43:34,819 INFO [ReadyApiH2MigrationDriver] Compliance status for dashboard database: not compliant
  2023-11-29 14:43:34,823 INFO [ReadyApiH2MigrationDriver] Compliance status for test history database: not compliant
  2023-11-29 14:43:34,823 INFO [H2MigrationStatusView] Due to an upgrade of the H2 database, data migration is required.
  2023-11-29 14:43:34,823 INFO [H2MigrationStatusView] To migrate your data, follow the instructions: https://support.smartbear.com/readyapi/docs/general-info/install/h2-migration.html
  2023-11-29 14:43:34,823 INFO [H2MigrationStatusView] To skip the migration, run testrunner.sh with the following option:
  2023-11-29 14:43:34,823 INFO [H2MigrationStatusView] -Dreadyapi.migration.ignore=true
- At this point, choose to either perform migration following the provided steps or, if you are opting to skip or ignore migration, include additional parameters in the command line arguments.
  1. To continue the test run, incorporate this argument into the command line. Note that the product will complete the test run and upgrade without data migration, only creating a backup. If you prefer data migration upon upgrading, follow the outlined steps for upgrading with data migration.
    -Dreadyapi.migration.ignore=true
Using Docker-based runners
- The H2 migration process becomes necessary when there is a volume attached containing the ReadyAPI home folder (.readyapi)
- The process for the command line runners is same as outlined above. Ensure to pass the parameter into the COMMAND_LINE variable while running the Docker image.

Manual migration

In the installation folder of your ReadyAPI instance, there is a file with script (.bat/.sh).

You can run the script for automatic migration, providing these four arguments:
- --allow_download/-y: Enables ReadyAPI to download the old driver for migration if internet access is available.
- --old_jar/-j: Specify the path to an old driver jar file, useful in air-gapped or offline environments.
- --old_installation/-i: Provide the path to the old ReadyAPI installation (version <= 3.50.0).
- --loadui_database_location: Provide the path to LoadUI performance results, necessary if the path was changed using the Path to statistics results preference.
You can run the default script by double-clicking, running the script file, or using the command line.

Examples of commands to perform migration:

Windows
- C:\Program Files\SmartBear\ReadyAPI-3.51.0\bin\h2_migration.bat --allow_download
- C:\Program Files\SmartBear\ReadyAPI-3.51.0\bin\h2_migration.bat --old_jar "C:\h2-1.4.200.jar"
- C:\Program Files\SmartBear\ReadyAPI-3.51.0\bin\h2_migration.bat --old_installation "C:\Program Files\SmartBear\ReadyAPI-3.50.0"
Linux
- /home/user/SmartBear/ReadyAPI-3.51.0/bin/h2_migration.sh --allow_download
- /home/user/SmartBear/ReadyAPI-3.51.0/bin/h2_migration.sh --old_jar "/home/user/Downloads/h2-1.4.200.jar"
- /home/user/SmartBear/ReadyAPI-3.51.0/bin/h2_migration.sh --old_installation "/home/user/SmartBear/ReadyAPI-3.50.0"
macOS
- /Applications/ReadyAPI-3.51.0.app/Contents/java/app/bin/h2_migration.sh --allow_download
- /Applications/ReadyAPI-3.51.0.app/Contents/java/app/bin/h2_migration.sh --old_jar "/Users/user/Downloads/h2-1.4.200.jar"
- /Applications/ReadyAPI-3.51.0.app/Contents/java/app/bin/h2_migration.sh --old_installation "/Applications/ReadyAPI-3.50.0.app"

Please note that this manual method is an alternative to UI migration. We recommend migrating through the UI for a smoother process.

New databases locations

As part of the migration process, the ReadyAPI and dashboard databases are relocated to the $HOME/.readyapi/data directory.
LoadUI databases are now labeled as data, and the execution history is now named test_executions.properties.
Your data from previous ReadyAPI versions is retained in its original location. You can use it when running versions older than 3.51.0.

Migration logs

You can find logs from the migration process in the following directory:

Windows: ./readyapi/logs
Linux: /home/user/SmartBear/ReadyAPI-3.51.0/bin/
MacOS: /Applications/ReadyAPI-3.51.0.app/Contents/java/app/bin/

We've conducted extensive testing for this migration step, covering all potential scenarios. If any issues arrise, please log a support ticket, and our team will reach out to address and assist with the matter. You can log a support ticket through this link.

H2 Migration