Migrate H2 database to the MvStore format
If you’re upgrading to Bitbucket 8.0 or higher from a version lower than 8.0 and use a H2 database (for a Bitbucket Mirror or Server), you’ll need to migrate the on-disk database file from PageStore format to MVStore format. The distribution package under the
/bin directory contains a new script,
h2-migrate-db-file.sh, that you can use to migrate the H2 database file.
If you start Bitbucket without migrating to the MVStore format, a fatal error will occur and you can’t start Bitbucket.
On this page
To migrate your H2 database:
- Make sure that the Bitbucket application is not running.
- Change to your
<Bitbucket Server installation directory>/binand use the command
BITBUCKET_HOME=<Home directory> ./h2-migrate-db-file.sh. You can customize the behavior of the script. For details, refer 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... - Table PUBLIC.DATABASECHANGELOGLOCK created with 1 row - Table PUBLIC.DATABASECHANGELOG created with 704 rows - Table PUBLIC.APP_PROPERTY created with 8 rows .... - Table PUBLIC.AO_4789DD_PROPERTIES created with 0 rows Run script finished, DB file generated successfully at /var/opt/atlassian-bitbucket/home/shared/data/db.mv.db
A backup of the
db.h2.dbfile gets stored at the same path as that of the original file with the suffix, _old. For example,
Configure the migration script
Set the below environment variables to customize the behavior of the script.
|Bitbucket home directory|
|Set one of these variables so the script can run successfully.|
|Set this variable only if the shared home is different from |
|Set this variable only if you want to provide a custom location for the H2 database file. |
|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.|
|This variable is optional and can be used to set the username to connect to the H2 database file. The default username is |
|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 the
h2_script.sqlfile, if present.
- Change the directory to
- If you see the file
db_old.h2.db, rename it to
- If you see the file
db.mv.db, delete it.