Upgrades

An upgrade moves two things: the Helm release, which changes the running image, and the entity store schema, which changes the database Gravitino keeps its own metadata in. They are separate steps and the schema comes first.

Your connected sources are not touched. Gravitino stores catalog definitions, tags, policies, and grants, not your data, so an upgrade affects metadata about connections rather than anything in the systems those connections point at.

Before You Start

Read the release notes for every version between the one you are on and the one you are moving to. Upgrades are cumulative, so moving from 1.1.0 to 1.3.0 means applying the 1.1.0 to 1.2.0 migration and then the 1.2.0 to 1.3.0 migration, in order.

Schedule downtime. The server must be stopped while the schema is migrated, and nothing else may write to the entity store during that window.

1. Stop the Server

Scale the deployment to zero so that no instance is holding a connection to the entity store.

kubectl -n {namespace} scale deployment/gravitino --replicas=0

2. Back Up the Entity Store

This is what you restore from if the migration fails, so do it even when the upgrade looks routine.

For MySQL:

mysqldump --opt --host {host} --user {user} -p {database} > backup.sql

For PostgreSQL, use the custom format, which includes both schema and data and is what a full rollback needs:

pg_dump -U {user} -h {host} -d {database} -n {schema} -Fc -f backup.dump

If you run an Iceberg REST catalog service against its own database, back that up as well.

3. Apply the Schema Migration

The chart does not migrate the schema for you. Apply the migration scripts for your backend manually, one per version step, in order.

For MySQL:

mysql -h {host} -u {user} -p {database} < upgrade-1.2.0-to-1.3.0-mysql.sql

For PostgreSQL:

psql -U {user} -h {host} -d {database} \
  -c "SET search_path TO {schema};" \
  -f upgrade-1.2.0-to-1.3.0-postgresql.sql

These should complete without errors. If one fails partway, stop rather than continuing to the next step, restore from your backup, and contact support with the error. A migration that errors usually means the schema has drifted from what the script expects, and reconciling that by hand risks leaving the store in a state no later migration will accept.

4. Upgrade the Helm Release

Create a values file for the target version based on your current one, applying any field changes listed under Version Notes below, then upgrade.

helm upgrade gravitino \
  oci://{registry_host}/charts/datastrato-enterprise \
  --version {target_version} \
  -n {namespace} \
  -f values-{target_version}.yaml

Scaling back up happens as part of the upgrade, so there is no separate step.

5. Verify

Confirm the rollout completed and the pods are running the image you expect.

kubectl -n {namespace} rollout status deployment/gravitino
kubectl -n {namespace} get pods -o jsonpath='{.items[*].spec.containers[*].image}'

Then confirm the server is actually serving rather than merely running. Readiness reports whether it reached the entity store, which is the thing the migration just changed.

kubectl -n {namespace} exec deployment/gravitino -- curl -s -o /dev/null -w '%{http_code}' \
  http://localhost:8090/api/health/ready

A 200 means the migration and the upgrade are both good. See Health and readiness if it returns 503.

Finally, list a metalake and a catalog to confirm your existing definitions survived.

Rolling Back

Stop the server before restoring, or concurrent writes will corrupt the restored state.

kubectl -n {namespace} scale deployment/gravitino --replicas=0

For MySQL, the dump contains DROP TABLE statements, so it replaces the upgraded tables:

mysql -h {host} -u {user} -p {database} < backup.sql

For PostgreSQL:

pg_restore -U {user} -h {host} -d {database} -n {schema} \
  --clean --if-exists --single-transaction backup.dump

pg_restore --clean drops only objects present in the dump, so tables or sequences the migration added are not removed. Verify the schema before restarting.

Then roll the Helm release back to the previous revision and scale up.

helm rollback gravitino -n {namespace}

Version Notes

1.2.0 to 1.3.0

Field	1.2.0	1.3.0
image.tag	1.2.0	1.3.0
env.GRAVITINO_HOME	/root/gravitino	/opt/gravitino
extraVolumeMounts[gravitino-log].mountPath	/root/gravitino/logs	/opt/gravitino/logs

GRAVITINO_HOME moved from /root/gravitino to /opt/gravitino. Update every path reference in your values file, not only the two above, or volume mounts will land in the wrong place and logs will disappear rather than fail loudly.

Engine Connectors

Connectors run inside your Trino, Spark, and Flink pods and are upgraded separately from the server. Check the release notes for whether the connector version you are running is supported against the server version you are moving to, and plan connector updates alongside the server upgrade rather than after it. See Connectors on Kubernetes.