This is an automated email from the ASF dual-hosted git repository.
yuqi1129 pushed a commit to branch branch-1.3
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-1.3 by this push:
new c884c8bcd5 [Cherry-pick to branch-1.3] [#11122 ][#11112]
docs(upgrade): Improve PostgreSQL backup format and add rollback instructions
(#11461) (#11535)
c884c8bcd5 is described below
commit c884c8bcd5743187d75c0d8ccbbca8ebef7e369a
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Tue Jun 9 22:08:04 2026 +0800
[Cherry-pick to branch-1.3] [#11122 ][#11112] docs(upgrade): Improve
PostgreSQL backup format and add rollback instructions (#11461) (#11535)
**Cherry-pick Information:**
- Original commit: fcb3bb4c5b12691ddf751a95c71ece32860b17d0
- Target branch: `branch-1.3`
- Status: ✅ Clean cherry-pick (no conflicts)
Co-authored-by: Danhua Wang <[email protected]>
---
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="" />
