Migrate H2 database from 1.x to 2.x and later
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>/binand use the commandBITBUCKET_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 scriptWhen 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.dbA 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.shand remove theh2_script.sqlfile, if present.Change the directory to
<BITBUCKET_HOME>/shared/data.If you see the file:
backup_db.h2.db, rename it todb.h2.db.backup_db.mv.db, rename it todb.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.
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.shinside<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 fiHere 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:
https://repo1.maven.org/maven2/com/h2database/h2/ H2 version>/h2-<source H2 version>.jar
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>/binand use the commandMESH_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.dbA 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.shand remove theh2_script.sqlfile, if present.Change the directory to
<MESH_HOME>.If you see the file:
backup_mesh.mv.db, rename it tomesh.mv.db.mesh.mv.db, delete it.