This is an automated email from the ASF dual-hosted git repository.
yuqi1129 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new fcb3bb4c5b [#11122 ][#11112] docs(upgrade): Improve PostgreSQL backup
format and add rollback instructions (#11461)
fcb3bb4c5b is described below
commit fcb3bb4c5b12691ddf751a95c71ece32860b17d0
Author: Danhua Wang <[email protected]>
AuthorDate: Tue Jun 9 19:38:24 2026 +0800
[#11122 ][#11112] docs(upgrade): Improve PostgreSQL backup format and add
rollback instructions (#11461)
### What changes were proposed in this pull request?
This PR improves the `docs/how-to-upgrade.md` documentation with the
following changes:
1. Changed the PostgreSQL data backup command to use `-Fc` (custom
compressed binary format) instead of `-F c`, producing a `.dump` file
instead of `.sql`, and added a note explaining the custom format.
2. Changed the PostgreSQL schema dump command to use plain-text format
(`-f`) instead of custom format (`-F c`), making it easier to diff
against official schema files.
3. Improved the wording in Step 4 (schema comparison) to clarify which
differences are acceptable (e.g., object ordering, comments) and which
need manual resolution (e.g., table structures, column types, missing
tables/indexes).
4. Added a new "Rollback if Upgrade Fails" section with restore
instructions for MySQL, H2, and PostgreSQL backends.
### Why are the changes needed?
1. The previous PostgreSQL backup command used `-F c` (custom format)
but saved to a `.sql` extension, which is misleading. The custom format
should use a `.dump` extension and be restored with `pg_restore`.
2. The schema dump should be in plain-text format so users can directly
diff it against the official schema SQL files.
3. The original documentation lacked rollback guidance, leaving users
without a clear recovery path if an upgrade fails.
Fix: #11112
Fix: #11122
### Does this PR introduce _any_ user-facing change?
No. This is a documentation-only change.
### How was this patch tested?
Documentation-only change. Verified the commands are correct by
reviewing PostgreSQL and MySQL official documentation.
---
docs/how-to-upgrade.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 64 insertions(+), 5 deletions(-)
diff --git a/docs/how-to-upgrade.md b/docs/how-to-upgrade.md
index ba1563bce2..26b63ba3c9 100644
--- a/docs/how-to-upgrade.md
+++ b/docs/how-to-upgrade.md
@@ -49,14 +49,18 @@ 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
```
+The `-Fc` option produces a compressed binary dump in PostgreSQL's
+custom format, which can be restored with `pg_restore`. Unlike a
+schema-only dump, this backup includes both schema and data, which
+is necessary for a full rollback.
If you are running an Iceberg REST Catalog (IRC) service backed by a separate
PostgreSQL database,
back it up as well:
```shell
-pg_dump -U username -h hostname -d irc_database_name -n schema_name -a -F c -f
data_backup_irc.sql
+pg_dump -U username -h hostname -d irc_database_name -n schema_name -Fc -f
data_backup_irc.dump
```
### Step 3: Dump the Gravitino Database
@@ -86,9 +90,13 @@ Note that you may need to specify your h2 file path,
username and password
For PostgreSQL, you can use the following command to dump the database schema
to a file:
```shell
-pg_dump -U username -h hostname -d database_name -n schema_name -s -F c -f
schema-x.y.z-postgresql.sql
+pg_dump -U username -h hostname -d database_name -n schema_name -s -f
schema-x.y.z-postgresql.sql
```
+Note: The `-s` flag dumps schema-only in plain SQL format. This is
+different from the `-Fc` custom format used in Step 2 for backup,
+which produces a binary dump that must be restored with `pg_restore`.
+
### Step 4: Determine Differences Between the Existing Schema and the Official
Schema
The schema upgrade scripts assume that the schema you are upgrading
@@ -98,8 +106,12 @@ Gravitino. The files in this directory with names like
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
+you created in the previous step.
+
+Some differences are acceptable and will not interfere
+with the upgrade process, such as differences in object ordering or
+comments. However, differences in table structures, column types, or
+missing tables/indexes need to be resolved manually
or the upgrade scripts will fail to complete.
### Step 5: Apply the Upgrade Scripts
@@ -206,4 +218,51 @@ Confirm the running image tag matches the target version:
kubectl get pods -n <namespace> -o
jsonpath='{.items[*].spec.containers[*].image}'
```
+## Rollback if Upgrade Fails
+
+> **Important:** Stop the Gravitino server before restoring the database
+> to avoid data corruption from concurrent writes.
+
+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 --database=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 -n schema_name --clean
--if-exists --single-transaction data_backup.dump
+```
+
+Note: `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 not be removed automatically.
+Verify the schema matches the expected state after restoring.
+
+After restoring, verify that your Gravitino instance starts
+successfully with the restored database before attempting the
+upgrade again.
+
<img
src="https://analytics.apache.org/matomo.php?idsite=62&rec=1&bots=1&action_name=HowToUpgrade";
alt="" />
