yuqi1129 commented on code in PR #4054: URL: https://github.com/apache/gravitino/pull/4054#discussion_r1679069474
########## docs/how-to-upgrade.md: ########## @@ -0,0 +1,111 @@ +--- +title: How to upgrade Apache Gravitino +slug: /how-to-upgrade +license: "This software is licensed under the Apache License version 2." +--- + +## 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: + +```shell +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. + +### 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: + +```shell +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: + +```shell +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 + + +### 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 +You can use the following command to apply the upgrade script: Review Comment: Please include information like "Assuming you are upgrading the version of Gravitino server from 0.6.0 to 0.8.0". ########## docs/index.md: ########## @@ -149,3 +149,5 @@ Gravitino provides several ways to configure and manage the Gravitino server. Se a Gravitino release. * [Publish Docker images](./publish-docker-images.md): a guide to publishing Gravitino Docker images; also lists the change logs of Gravitino CI Docker images and release images. +* [How to upgrade Gravitino](./how-to-upgrade.md): a guide to upgrading the schema of backed + Gravitino instance from one release version to another. Review Comment: of Gravitino storage backend -- 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]
