Migrate H2 database from 1.3 to 1.4

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

These instructions don’t apply if you’re already on a Bitbucket version 8.0 or above.

If you're upgrading from versions below 8.0 to Bitbucket 8.0-8.7 (for example from 7.19 to 8.2) 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:

  1. Make sure that the Bitbucket application is not running.
  2. Change to your <Bitbucket Server installation directory>/bin and use the command BITBUCKET_HOME=<Home 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...
    	- 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.db file gets stored at the same path as that of the original file with the suffix, _old. For example, db_old.h2.db

Configure the migration script

Set the below 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 this variable is not set.
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.
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:
    • db_old.h2.db, rename it to db.h2.db.
    • db.mv.db, delete it.
Last modified on Apr 26, 2023

Was this helpful?

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