H2 Database Migration

What is H2 and how is it used in VirtServer?

VirtServer uses H2 as its embedded database. This is a Java-based relational database management system. It stores the following:

  • Virtual Service details

  • Transactional and HAR logs

  • User information

  • Data for managing virts, tests, transactions, and users

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

Do I need to go through this upgrade process?

All customers migrating to the latest version of VirtServer 3.28.0, will be required to go through the migration process.

Without H2 migration, if you try to run VirtServer 3.28.0 you get the following error:

ERROR [YYYY-MM-DD hh:mm:ss,SSS]
com.smartbear.virtserver.VirtServer: H2 database migration is required.
For more information, please go to H2 Database Migration.

Note

Customers using VirtServer versions earlier than 3.6.0 must first upgrade to version 3.14 before upgrading to 3.28.0. This step is necessary due to changes in user management in the H2 database introduced in version 3.6. For more information, click the VirtServer 3.6.0 release notes.

Download the VirtServer 3.14 Installers from the ReadyAPI Downloads page:

Steps to migrate the database

Note

Before running the VirtServer installer for the latest version, you must perform the database migration.

Note

Migrating large virtual services (150-200 MB+) to the new database may take some time. To reduce migration time, consider undeploying large virtual services from VirtServer before the migration and then redeploying them using ReadyAPI or the VirtServer CLI after upgrading to version 3.23.0. Otherwise, be patient during the migration process, as very large virtual services (400 MB+) can take up to 2 hours to migrate.

To migrate the database, follow these steps:

  1. Download the Migration Scripts: Download the H2 migration package from H2 Migrator.

  2. Extract the Package: Unzip the package into your Downloads folder. This will create a new H2 migration folder.

  3. Navigate to the Migration Folder: Open the folder relevant to your operating system.

    The README file contains further instructions for steps 4-6 below.

  4. Stop VirtServer: Ensure VirtServer is not running.

    Note

    Database migration can only be performed when VirtServer is stopped.

  5. Run the Migration Script: Execute the h2-migrator.bat (for Windows) or h2-migrator.sh (for Linux/Mac) migration script. Wait for the process to complete and follow any on-screen prompts.

  6. Start VirtServer: Once the migration is complete, start VirtServer as an application or as a service.

Need assistance? Contact Support

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

How to revert to an earlier version of VirtServer

If you’ve upgraded to version 3.26.0 and need to revert to an earlier version, note that file-based licensing will no longer be available as of October 2023. This will be fully replaced by SmartBear ID-based licensing, which was introduced in ReadyAPI 3.8.1 and supported in VirtServer versions 3.16.0 and 3.17.0.

To ensure your SmartBear License Management (SLM) works, you must revert to a version later than 3.17.0. For more information, see the SmartBear ID-Based Licensing documentation.

To downgrade your version and restore your previous H2 database, follow these steps:

  1. For VirtServer 3.16.0 or Earlier: If you want to revert after migrating to H2, manually delete the virt-server.h2.mv.db file and restart VirtServer 3.16.0.

    • Windows: C:\Users\<user>\.readyapi\virt-server\virt-server.h2.mv.db

    • Linux: /home/user/.readyapi/virt-server/virt-server.h2.mv.db

  2. If H2 Database Files Are in .readyapi/virt-server: Run the virtserver-h2-migration-revert script.

    • Windows: revert-h2-migrator.bat

    • Linux/Mac: revert-h2-migrator.sh

  3. If Database Files Are in Another Directory other than .readyapi/virt-server: Use the following command:

    • Windows: revert-h2-migrator.bat --db_path=C:\path\to\virt-server\virt-server.h2.mv.db

    • Linux/Mac: ./revert-h2-migrator.sh --db_path=path/to/virt-server/virt-server.h2.mv.db

Running VirtServer in Docker

If you are running the VirtServer Docker image without mounting it to a local folder, the H2 migration is not required.

However, if you are running the VirtServer Docker image with a mounted local folder, such as: docker run -v C:\Users\user\DockerVS1:/virtserver smartbear/ready-api-virtserver-dev, then you need to follow these steps for migration:

  1. A virt-server-docker.yml file should be created in the C:\Users\user\DockerVS1 folder.

  2. The .readyApi folder will also be created in the same directory.

For further instructions, refer to the README file.

In this section:
© 2025
Publication date: