Update self-hosted Supabase safely and predictably

Prefer not to manage release notes, merge conflicts and recovery risk yourself? WZ-IT provides managed Supabase hosting and operations with controlled updates, monitoring and backups.

To update self-hosted Supabase is to update more than one container. The stack includes PostgreSQL, Auth, Storage, Realtime, an API gateway, Studio, Functions and other services. Images, environment variables, Compose files, database structures and dependencies can change between releases.

A reliable update process treats each upgrade as a small, repeatable change with inventory, protection, staging, acceptance and rollback.

Why “pull and restart” is risky

Unreviewed upgrades commonly fail because of:

• locally modified Compose files
• new or removed environment variables
• incompatible image combinations
• database changes or major versions
• changed health checks or network paths
• Auth and JWT configuration
• Functions and runtime dependencies
• external SMTP, OAuth or Storage connections

Containers may appear healthy while login, upload, Realtime or an API is already broken. Technical health checks and real user-journey tests serve different purposes and both are required.

1. Capture a reproducible current state

Before updating, record:

Do not let movable tags change images without control. A recorded state is the basis for recreating the same environment.

2. Assess target changes

The official update guide and self-hosting repository are the primary sources. Review:

• changed Compose services
• new, renamed or removed variables
• database migrations
• Auth, gateway and API changes
• required image versions
• breaking changes and manual actions
• known limitations

Also verify application clients and integrations against the target. An update can be technically correct while violating an application assumption.

3. Prepare the right backups

Supabase explicitly notes that its configuration update process does not back up PostgreSQL data or Storage objects.

Before production, require:

• consistent PostgreSQL backup
• separate protection of Storage file bytes
• versioned Compose and override files
• encrypted configuration backup or recovery process
• recorded image versions
• verified recovery runbook

File existence alone is insufficient. Operators need a measured recovery duration and a clear understanding of data loss after rollback.

4. Reconcile official and local changes

Supabase provides an update script for certain self-hosting changes that uses a three-way comparison:

1. previous official template
2. current official template
3. locally modified state

This helps preserve intended adjustments. Merge conflicts still require engineering decisions, particularly around:

• ports and public exposure
• volume paths
• external database or Storage targets
• reverse proxy and TLS
• custom secret variables
• resource limits
• logging and monitoring

Review the result in version control. Secrets do not belong in the repository.

5. Test in a production-like environment

Useful staging reproduces:

• architecture and relevant configuration
• anonymised or representative data
• the same Auth providers in test mode
• Functions and extensions
• realistic Storage and Realtime scenarios

At minimum test:

• Studio and administration
• REST and GraphQL access
• login, logout, refresh and password reset
• positive and negative RLS cases
• upload, download and signed URLs
• Realtime connections
• Functions and secrets
• SMTP, OAuth, webhooks and external APIs
• backups after the update

6. Production runbook

An executable runbook contains:

1. approval and start time
2. verification of the latest successful backup
3. optional write freeze or maintenance mode
4. retrieval of pinned images
5. configuration and database steps in order
6. restart and technical health checks
7. smoke tests for critical journeys
8. go/no-go decision
9. enhanced observation period
10. closure and documentation

Every step has an owner, expected result and abort criterion.

7. Rollback is more than an image rollback

Restarting old images is insufficient when an update changes database state. The rollback plan answers:

• Are schema changes backward-compatible?
• Is a full database recovery required?
• What happens to writes accepted after the update?
• Will Storage metadata and files still match?
• Which DNS, proxy or secret changes need reversal?

For high-risk changes, a prepared parallel target can be safer than an in-place update.

8. Observe and document

After updating, observe:

• error rates and latency
• database connections, locks and resources
• Auth failures
• Storage and Function errors
• Realtime connections
• queue or webhook backlogs
• unexpected restarts

Then update the version inventory, runbook and known deviations. Lessons from incidents or manual work feed the next cycle.

Sources

• Supabase: update a self-hosted deployment
• Supabase: self-hosting with Docker
• Supabase: database backups
• Supabase self-hosting repository