Upgrade & Backup

Before you upgrade

Read the release notes for the target version.
Back up PostgreSQL (snapshot or pg_dump). You need this backup if you must roll back.

Always back up the database before a major upgrade. Schema migrations run automatically on pod startup and are not reversed by helm rollback.

Upgrade

helm upgrade nocodb oci://ghcr.io/nocodb/charts/nocodb --version <new-version> \
  -n nocodb -f values.yaml --wait

The app uses an ordered rollout (maxSurge: 1, maxUnavailable: 0). The first new pod runs all schema migrations. A migration lock makes them run one at a time. The other pods start when the migrations are complete. The startup probe has a long limit, so Kubernetes does not stop pods during a migration.

For a major upgrade, you can be more careful. Scale the app to one replica for the upgrade first:

helm upgrade nocodb oci://ghcr.io/nocodb/charts/nocodb --version <new-version> \
  -n nocodb -f values.yaml --set replicaCount=1 --wait
# once healthy, restore your normal replica count

Roll back

helm history nocodb -n nocodb
helm rollback nocodb <revision> -n nocodb --wait

The auto-generated JWT secret and datasource encryption key are never rotated by upgrades (they carry helm.sh/resource-policy: keep), so rollbacks do not invalidate sessions or stored credentials. If a migration changed the schema, restore your database backup to fully revert.

Backup & restore

PostgreSQL: use the snapshots of your provider or pg_dump/pg_restore. PostgreSQL holds all NocoDB metadata.
S3: enable bucket versioning. S3 holds the attachments.
For the general procedure, refer to Backups.

Troubleshooting

Symptom	Likely cause
Pod stuck `0/1` for minutes on first install	First-boot migrations are running. The startup probe allows this.
`NocoDB requires Redis...` at install	`replicaCount>1` or `worker.enabled` is set, and `externalRedis` is not configured
Attachments missing on some requests	Object storage is not configured. Set up an S3-compatible Storage plugin in the App Store.
New pods not picking up env changes	The config checksum does not track values from `extraEnvVars` or an external Secret. Restart the rollout with `kubectl rollout restart`, or run `helm upgrade` again.