Migrate H2 database from 1.x to 2.x and later

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

If you're upgrading from a version older than 8.8 to Bitbucket 8.8 and later (for example, from 8.0 to 8.8 or 7.21 to 8.9) and use the H2 database (for a Bitbucket Mirror or Data Center), you'll need to migrate the on-disk database file so it's compatible with the new H2 driver version. 

The distribution package under the /bin directory contains a script, h2-migrate-db-file.sh, that you can use to migrate the H2 database file.

If you start Bitbucket without migrating to the new disk format, a fatal error will occur and you can’t start Bitbucket.

Migrate the H2 database for a Bitbucket Mirror or Data Center

To migrate your H2 database:

  1. Make sure that the Bitbucket application isn’t running.

  2. Change to your <Bitbucket installation directory>/bin and use the command BITBUCKET_HOME=<Home directory> SOURCE_INST_DIR=<Old installation directory> ./h2-migrate-db-file.sh. You can customize the behavior of the script. Learn how to configure the migration script

  3. When the script is successfully executed, it will generate output that looks similar to the following: 

Creating script file...
Script file created successfully
Running script...
Run script finished, DB file generated successfully at /var/opt/atlassian-bitbucket/home/shared/data/db.mv.db

A backup of the db.h2.db file gets stored at the same path as that of the original file with the prefix, backup_. For example, backup_db.h2.db or backup_db.mv.db.

Configure the migration script

Set the following environment variables to customize the behavior of the script.

VariableDescription
BITBUCKET_HOMEBitbucket home directory
JAVA_HOME or JRE_HOMESet one of these variables so the script can run successfully.
BITBUCKET_SHARED_HOMESet this variable only if the shared home is different from <BITBUCKET_HOME>/shared. Note that you don’t need to set BITBUCKET_HOME if you set this variable.
DB_FILESet this variable only if you want to provide a custom location for the H2 database file. <BITBUCKET_SHARED_HOME>/data/db.h2.db is used by default if present on the disk, otherwise <BITBUCKET_SHARED_HOME>/data/db.mv.db.
H2_JAR_PATHThis variable is optional and can be used to set the path of the H2 jar file. The H2 jar bundled in the installation directory is used by default.
SOURCE_INST_DIRThis is the path of the existing installation directory. For example, if you're upgrading from Bitbucket 7.21, then this is the path of the installation directory for 7.21.
JDBC_USERThis variable is optional and can be used to set the username to connect to the H2 database file. The default username is sa.
JDBC_PASSWORDThis variable is optional and can be used to set the password to connect to the H2 database file. The default password is blank (““).

Revert your migration

If the migration is unsuccessful or you want to reconsider your upgrade decision, you can revert the migration:

  1. Navigate to the directory from where you executed the script h2-migrate-db-file.sh and remove the h2_script.sql file, if present.

  2. Change the directory to <BITBUCKET_HOME>/shared/data.

  3. If you see the file:

    • backup_db.h2.db, rename it to db.h2.db.

    • backup_db.mv.db, rename it to db.mv.db.

    • db.mv.db, delete it.

Migrate the H2 database for Bitbucket Mesh

To check which Bitbucket Mesh version is compatible with your Bitbucket application, check Bitbucket Mesh compatibility matrix.

If you're upgrading to Mesh 1.5 and later, you'll need to migrate your database file so it's compatible with the new H2 driver version.

How do I check the H2 database version used by Mesh?

In the following table, find the H2 driver version compatible with your Bitbucket Mesh version.

Mesh versionH2 version
1.4.2 and older1.4.200
1.5.0-1.5.42.1.214
1.5.5-1.5.62.2.220
2.0.0-2.0.62.1.214
2.0.7-2.0.82.2.220
2.1.02.1.214
2.1.1-2.1.22.2.220

If you start Mesh with the database file using old disk format, a fatal error will occur and the Mesh application will not start.

To migrate your H2 database perform the following steps as the same user that runs the Mesh application:

  1. Create a new file named h2-migrate-db-file.sh inside <Mesh installation directory/bin> with the following content:

    Substitute the <source H2> placeholder with the relevant version number of the H2 database you're currently using.

    #!/usr/bin/env bash
    
    if [ -z "$SOURCE_H2_JAR_PATH" ]; then
      echo "Please provide the location of the <source H2> JAR in the 'SOURCE_H2_JAR_PATH' environment variable"
      exit 1
    fi
    
    # BIN_DIR & INST_DIR will be absolute paths, not relative
    pushd $(dirname $0) > /dev/null
    BIN_DIR=$(pwd)
    popd > /dev/null
    INST_DIR=$(dirname "$BIN_DIR")
    
    source "$BIN_DIR"/set-jre-home.sh &&
        source "$BIN_DIR"/set-mesh-home.sh &&
        source "$BIN_DIR"/set-mesh-user.sh
    
    DB_FILE_WITHOUT_EXT="$MESH_HOME/mesh"
    DB_FILE="$DB_FILE_WITHOUT_EXT.mv.db"
    DB_LOCK_FILE="$DB_FILE_WITHOUT_EXT.lock.db"
    
    if [ -f "$DB_LOCK_FILE" ]; then
      echo "The file $DB_LOCK_FILE is present which means the database may be in use. Please stop Mesh or any other clients using the $DB_FILE file and try again. If the database is not in use, manually delete the file $DB_LOCK_FILE and try again."
      exit 1
    fi
    
    if [ ! -f "$DB_FILE" ]; then
      echo "Cannot run migration; $DB_FILE doesn't exist"
      exit 1
    fi
    
    if [ -z "$H2_JAR_PATH" ]; then
      H2_JAR_PATH="$BIN_DIR/h2.jar"
    fi
    
    JDBC_URL="jdbc:h2:$DB_FILE_WITHOUT_EXT"
    SCRIPT_FILE="h2_script.sql"
    SCRIPT_JAVA_OPTS="-cp $SOURCE_H2_JAR_PATH org.h2.tools.Script -user sa -url $JDBC_URL -script $SCRIPT_FILE"
    RUN_SCRIPT_JAVA_OPTS="-cp $H2_JAR_PATH org.h2.tools.RunScript -user sa -url $JDBC_URL -script $SCRIPT_FILE -showResults -options FROM_1X"
    
    BACKUP_FILE="$MESH_HOME/backup_mesh.mv.db"
    
    echo "Creating script file..."
    $JAVA_BINARY $SCRIPT_JAVA_OPTS
    if [ $? -eq 0 ]; then
      echo "Script file created successfully"
      mv "$DB_FILE" "${BACKUP_FILE}"
    else
      echo "Script generation failed"
      exit 1
    fi
    
    echo "Running script..."
    $JAVA_BINARY $RUN_SCRIPT_JAVA_OPTS
    if [[ $? -eq 0 && -f "$DB_FILE" ]]; then
      echo "Run script finished, DB file generated successfully at $DB_FILE"
      rm -rf "$SCRIPT_FILE"
      chmod u=rw,go=r $DB_FILE
    else
      echo "Run script failed"
      rm -rf ${DB_FILE_WITHOUT_EXT}.*.db
      mv "${BACKUP_FILE}" "$DB_FILE"
      exit 1
    fi

    Here and in the commands and variables below, <source H2 version> is your current H2 database version. <target H2 version> is the H2 database version you’re migrating to.

  2. Download the following H2 driver jar files in any location on the disk:

    1. https://repo1.maven.org/maven2/com/h2database/h2/ H2 version>/h2-<source H2 version>.jar

    2. https://repo1.maven.org/maven2/com/h2database/h2/ H2 version>/h2-<target H2 version>.jar

  3. Make sure that the Mesh application isn’t running.

  4. Change to your <Mesh installation directory>/bin and use the command MESH_HOME=<Home directory> SOURCE_H2_JAR_PATH=<Path of h2-<source H2 versio>.jar> H2_JAR_PATH=<Path of h2-<target H2 version>.jar>./h2-migrate-db-file.sh. You can customize the behavior of the script. Learn how to configure the migration script

  5. When the script is successfully executed, it will generate output that looks similar to the following:
Creating script file... 
Script file created successfully
Running script...
Run script finished, DB file generated successfully at /var/opt/atlassian-bitbucket/home/mesh.mv.db

A backup of the mesh.mv.db file gets stored at the same path as that of the original file with the prefix, backup_. For example, backup_mesh.mv.db.

Configure the migration script

Set the following environment variables to customize the behavior of the script.

VariableDescription
MESH_HOMEMesh home directory
JAVA_HOME or JRE_HOMESet one of these variables so the script can run successfully.
DB_FILESet this variable only if you want to provide a custom location for the H2 database file. <MESH_HOME>/mesh.mv.db is used by default.
H2_JAR_PATHThis variable is used to set the path of the H2 jar file for the version you’re migrating to. For example, 2.2.200.
SOURCE_H2_JAR_PATHThis variable is used to set the path of the H2 jar file for your current version. For example, 1.4.200.

Revert your migration

If the migration is unsuccessful or you want to reconsider your upgrade decision, you can revert the migration:

  1. Navigate to the directory from where you executed the script h2-migrate-db-file.sh and remove the h2_script.sql file, if present.

  2. Change the directory to <MESH_HOME>.

  3. If you see the file:

    • backup_mesh.mv.db, rename it to mesh.mv.db.

    • mesh.mv.db, delete it.

Last modified on Sep 24, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.