Bitbucket Support

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:

Make sure that the Bitbucket application isn’t running.
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
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.

Variable	Description
`BITBUCKET_HOME`	Bitbucket home directory
`JAVA_HOME` or `JRE_HOME`	Set one of these variables so the script can run successfully.
`BITBUCKET_SHARED_HOME`	Set 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_FILE`	Set 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_PATH`	This 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_DIR`	This 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_USER`	This variable is optional and can be used to set the username to connect to the H2 database file. The default username is `sa`.
`JDBC_PASSWORD`	This 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:

Navigate to the directory from where you executed the script h2-migrate-db-file.sh and remove the h2_script.sql file, if present.
Change the directory to <BITBUCKET_HOME>/shared/data.
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 version	H2 version
1.4.2 and older	1.4.200
1.5.0-1.5.4	2.1.214
1.5.5-1.5.6	2.2.220
2.0.0-2.0.6	2.1.214
2.0.7-2.0.8	2.2.220
2.1.0	2.1.214
2.1.1-2.1.2	2.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:

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.

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
Make sure that the Mesh application isn’t running.
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
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.

Variable	Description
`MESH_HOME`	Mesh home directory
`JAVA_HOME` or `JRE_HOME`	Set one of these variables so the script can run successfully.
`DB_FILE`	Set 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_PATH`	This 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_PATH`	This 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:

Navigate to the directory from where you executed the script h2-migrate-db-file.sh and remove the h2_script.sql file, if present.
Change the directory to <MESH_HOME>.
If you see the file:
- backup_mesh.mv.db, rename it to mesh.mv.db.
- mesh.mv.db, delete it.

Bitbucket Support

Knowledge base

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

Suggestions and bugs

Marketplace

Billing and licensing

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

Migrate H2 database

On this page

Still need help?

Migrate the H2 database for a Bitbucket Mirror or Data Center

Configure the migration script

Revert your migration

Migrate the H2 database for Bitbucket Mesh

Configure the migration script

Revert your migration

Page

Viewport

Confluence

Versions

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

Migrate H2 database

On this page

Related content

Still need help?

Migrate the H2 database for a Bitbucket Mirror or Data Center

Configure the migration script

Revert your migration

Migrate the H2 database for Bitbucket Mesh

Configure the migration script

Revert your migration

Related content