Skip to main content
Version: 0.7.0-incubating

How to upgrade Apache Gravitino

Introduction​

This document describes how to upgrade the schema of backed Gravitino instance from one release version of Gravitino to another release version of Gravitino. For example, by following the steps listed below it is possible to upgrade a Gravitino 0.6.0 schema to a Gravitino 0.7.0 schema. Before attempting this project we strongly recommend that you read through all of the steps in this document and familiarize yourself with the required tools.

Upgrade Steps​

Step 1: Shutdown your Gravitino instance​

Shutdown your Gravitino instance and restrict access to the Apache Gravitino's database. It is very important that no one else accesses or modifies the contents of database while you are performing the schema upgrade.

Step 2: Backup your Gravitino instance​

Create a backup of your database. This will allow you to revert any changes made during the upgrade process if something goes wrong.

MySQL​

For MySQL, you can use the following command to backup your database:

mysqldump --opt <db_name> > backup.sql

Note that you may also need to specify a hostname and username using the --host and --user command line switches.

H2​

The easiest way of accomplishing this task is by creating a copy of the directory containing your database.

PostgreSQL​

For PostgreSQL, you can use the following command to backup your database:

pg_dump -U username -h hostname -d database_name -n schema_name -a -F c -f data_backup.sql

Step 3: Dump your Gravitino database​

Dump your Gravitino database schema to a file

MySQL​

You can use the mysqldump utility to dump the database schema to a file:

mysqldump --skip-add-drop-table --no-data <db_name> > schema-x.y.z-mysql.sql

H2​

For H2, you can use the Script tool to dump the database schema to a file:

wget https://repo1.maven.org/maven2/com/h2database/h2/1.4.200/h2-1.4.200.jar
java -cp h2-1.4.200.jar org.h2.tools.Script -url "jdbc:h2:file:<db_file>;DB_CLOSE_DELAY=-1;MODE=MYSQL" -user <user> -password <password> -script backup.sql

Note that you may need to specify your h2 file path, username and password

PostgreSQL​

For PostgreSQL, you can use the following command to dump the database schema to a file:

pg_dump -U username -h hostname -d database_name -n schema_name -s -F c -f schema-x.y.z-postgresql.sql

Step 4: Determine differences between your schema and the official schema​

The schema upgrade scripts assume that the schema you are upgrading closely matches the official schema for your particular version of Gravitino. The files in this directory with names like schema-x.y.z-<type>.sql contain dumps of the official schemas corresponding to each of the released versions of Gravitino. You can determine differences between your schema and the official schema by comparing the contents of the official dump with the schema dump you created in the previous step. Some differences are acceptable and will not interfere with the upgrade process, but others need to be resolved manually or the upgrade scripts will fail to complete.

Step 5: Apply the upgrade scripts​

You are now ready to run the schema upgrade scripts. If you are upgrading from Gravitino 0.6.0 to Gravitino 0.7.0 you need to run the upgrade-0.6.0-to-0.7.0-<type>.sql script, but if you are upgrading from 0.6.0 to 0.8.0 you will need to run the 0.6.0 to 0.7.0 upgrade script followed by the 0.7.0 to 0.8.0 upgrade script.

MySQL​

Assuming you are upgrading the version of Gravitino server from 0.6.0 to 0.8.0

mysql --verbose
mysql> use <db_name>;
Database changed
mysql> source upgrade-0.6.0-to-0.7.0-mysql.sql
mysql> source upgrade-0.7.0-to-0.8.0-mysql.sql

H2​

For H2, you can use the RunScript tool to apply the upgrade script:

java -cp h2-1.4.200.jar org.h2.tools.RunScript -url "jdbc:h2:file:<db_file>;DB_CLOSE_DELAY=-1;MODE=MYSQL" -user <user> -password <password> -script upgrade-0.6.0-to-0.7.0-h2.sql
java -cp h2-1.4.200.jar org.h2.tools.RunScript -url "jdbc:h2:file:<db_file>;DB_CLOSE_DELAY=-1;MODE=MYSQL" -user <user> -password <password> -script upgrade-0.7.0-to-0.8.0-h2.sql

PostgreSQL​

For PostgreSQL, you can use the following command to apply the upgrade script:

psql -U username -h hostname -d database_name -c "SET search_path TO schema_name;" -f upgrade-0.6.0-to-0.7.0-postgresql.sql
psql -U username -h hostname -d database_name -c "SET search_path TO schema_name;" -f upgrade-0.7.0-to-0.8.0-postgresql.sql

These scripts should run to completion without any errors. If you do encounter errors you need to analyze the cause and attempt to trace it back to one of the preceding steps.

Step 6: Verify the upgrade​

The final step of the upgrade process is validating your freshly upgraded schema against the official schema for your particular version of Gravitino. This is accomplished by repeating steps (3) and (4), but this time comparing against the official version of the upgraded schema, e.g. if you upgraded the schema to Gravitino 0.8.0 then you will want to compare your schema dump against the contents of schema-0.8.0-<type>.sql