yuqi1129 commented on code in PR #11461:
URL: https://github.com/apache/gravitino/pull/11461#discussion_r3362651934
##########
docs/how-to-upgrade.md:
##########
@@ -49,8 +49,10 @@ by creating a copy of the directory containing your database.
For PostgreSQL, you can use the following command to backup your database:
```shell
-pg_dump -U username -h hostname -d database_name -n schema_name -a -F c -f
data_backup.sql
+pg_dump -U username -h hostname -d database_name -n schema_name -Fc -f
data_backup.dump
Review Comment:
The `-a` (data-only) flag was silently dropped here. The original command
backed up data only; this new command backs up both schema and data. That's
actually the right behaviour for rollback purposes, but it should be explicitly
documented — the added note only mentions the format change. Please add a
sentence explaining this semantic difference, e.g.: "Unlike the previous
command, this backup includes both schema and data, which is necessary for a
full rollback."
##########
docs/how-to-upgrade.md:
##########
@@ -206,4 +212,43 @@ Confirm the running image tag matches the target version:
kubectl get pods -n <namespace> -o
jsonpath='{.items[*].spec.containers[*].image}'
```
+## Rollback if Upgrade Fails
Review Comment:
The rollback section is missing a critical prerequisite: the Gravitino
server must be stopped before any restore is performed, otherwise concurrent
writes can corrupt the database. Please add a note at the top of this section,
e.g.:\n\n> **Important:** Stop the Gravitino server before restoring the
database to avoid data corruption from concurrent writes.
##########
docs/how-to-upgrade.md:
##########
@@ -206,4 +212,43 @@ Confirm the running image tag matches the target version:
kubectl get pods -n <namespace> -o
jsonpath='{.items[*].spec.containers[*].image}'
```
+## Rollback if Upgrade Fails
+
+If you encounter errors during the upgrade process, you can
+restore your database from the backup created in Step 2.
+
+### MySQL
+
+Use the backup file to restore your database. The `mysqldump`
+backup contains `DROP TABLE` statements by default (via `--opt`),
+so it will replace the upgraded tables automatically:
+
+```shell
+mysql -u username -h hostname <db_name> < backup.sql
+```
+
+### H2
+
+Replace the current database directory with the copy you made
+during the backup step:
+
+```shell
+rm -rf <db_directory>
+cp -r <db_directory_backup> <db_directory>
+```
+
+### PostgreSQL
+
+Use `pg_restore` with `--clean` to drop existing objects before
+restoring them in one transaction. This is safer than manually
+dropping the schema first:
+
+```shell
+pg_restore -U username -h hostname -d database_name --clean --if-exists
--single-transaction data_backup.dump
Review Comment:
Two issues with this restore command:\n\n1. **Missing schema filter**: the
backup was taken with `-n schema_name`, so the restore should include
`--schema=schema_name` (or `-n schema_name`) for symmetry. Without it, the
behaviour depends on what is in the dump and may confuse users.\n\n2.
**`--clean` limitation**: `pg_restore --clean` only drops objects that are
present in the dump file. If the upgrade scripts added new tables or sequences
not present in the backup, those objects will remain after the restore and may
leave the database in an inconsistent state. Worth adding a note such as:
"Note: objects added by the upgrade scripts that are not in the backup will not
be removed automatically; verify the schema matches the expected state after
restoring."\n\nSuggested command:\n```shell\npg_restore -U username -h hostname
-d database_name -n schema_name --clean --if-exists --single-transaction
data_backup.dump\n```
--
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]
