jerryshao commented on code in PR #4054: URL: https://github.com/apache/gravitino/pull/4054#discussion_r1671672943
########## scripts/h2/README: ########## @@ -0,0 +1,64 @@ +Gravitino Upgrade HowTo +============================ + +This document describes how to upgrade the schema of a H2 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. + +Gravitino Upgrade Steps +======================= + +1) Shutdown your Gravitino instance and restrict access to the + Gravitino's H2 database. It is very important that no one else + accesses or modifies the contents of database while you are + performing the schema upgrade. + +2) Create a backup of your H2 database. This will allow + you to revert any changes made during the upgrade process if + something goes wrong. The easiest way of accomplishing this task is + by creating a copy of the directory containing your H2 database. + +3) Dump your Gravitino database schema to a file using the `Script` tool. + You need to replace your h2 file path, username and password. The default + username and password are both gravitino + + % 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 + +4) 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-h2.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. + +5) 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.h2.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. + + % 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 + + 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. + +6) 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-h2.sql Review Comment: I think it is better to have a doc about upgrading, not a README here. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
