Updates - Supabase

Regular updates are critical for security, performance, and accessing new features. This guide covers the update process and version management for self-hosted Supabase.

Update Strategy

Always backup your database before updating! Updates can include breaking changes or migration scripts that modify your data.

Update Frequency

Recommended schedule:

Security patches: Within 48 hours of release
Minor updates: Monthly
Major updates: Quarterly (after testing)

Monitor for updates:

Before Updating

Review Changelog

Check docker/CHANGELOG.md for:

Breaking changes
Required configuration updates
Database migrations
Known issues

# View recent changes
cd supabase/docker
git pull
cat CHANGELOG.md | head -100

Backup Database

Create a full backup:

# Full database dump
docker exec supabase-db pg_dump -U postgres postgres > backup_$(date +%Y%m%d).sql

# Backup configuration
cp .env .env.backup
cp -r volumes volumes.backup

Test in Staging

If possible, test updates in a staging environment first:

# Clone production environment
cp -r supabase supabase-staging
cd supabase-staging/docker

# Update staging
git pull
docker compose pull
docker compose up -d

# Verify functionality

Schedule Maintenance Window

Notify users of planned downtime
Choose low-traffic period
Prepare rollback plan
Have team available for issues

Update Process

Standard Update

For most updates without breaking changes:

# Navigate to docker directory
cd supabase/docker

# Pull latest configuration
git pull

# Pull latest images
docker compose pull

# Stop services
docker compose down

# Start with new images
docker compose up -d

# Monitor logs
docker compose logs -f

Breaking Changes Update

When changelog indicates breaking changes:

Review Configuration Changes

Check for new environment variables or changed formats:

# Compare environment files
diff .env.example .env

# Add new required variables
vim .env

Update docker-compose.yml

If the changelog mentions docker-compose changes:

# Backup current file
cp docker-compose.yml docker-compose.yml.backup

# Review changes
git diff HEAD~1 docker-compose.yml

# Apply changes (manual merge if you have custom config)

Update Volume Configurations

Some updates require changes to mounted config files:

# Example: Vector logging config update
diff volumes/logs/vector.yml.backup volumes/logs/vector.yml

# Example: Kong routes update
diff volumes/api/kong.yml.backup volumes/api/kong.yml

Run Database Migrations

If changelog mentions database migrations:

# Check for migration files
ls -la volumes/db/migrations/

# Migrations run automatically on startup
docker compose up -d db
docker compose logs -f db

Version History

Track which versions you’re running:

# Check current image versions
docker compose images

# Check specific service version
docker inspect supabase-db | grep -i version

# Save version snapshot
docker compose images > versions_$(date +%Y%m%d).txt

Version File

The repository includes docker/versions.md with complete version history:

## 2026-02-16
- supabase/studio:2026.02.16-sha-26c615c
- supabase/gotrue:v2.186.0
- postgrest/postgrest:v14.5
- supabase/realtime:v2.76.5
- supabase/storage-api:v1.37.8
- supabase/postgres:15.8.1.085

Service-Specific Updates

PostgreSQL Updates

Major version upgrades require pg_upgrade:

PostgreSQL major version upgrades (e.g., 15 → 16) require special handling. Plan carefully.

# Before upgrading
docker exec supabase-db psql -U postgres -c "SELECT version();"

# After upgrading
docker compose up -d db
docker compose logs db | grep -i "database system is ready"

Studio Updates

Studio updates usually require no manual intervention:

# Pull latest Studio image
docker compose pull studio

# Restart Studio
docker compose up -d studio

# Verify Studio is healthy
curl http://localhost:3000/api/platform/profile

Auth (GoTrue) Updates

Auth updates may include new features or security fixes:

# Review GoTrue changelog
# https://github.com/supabase/auth/blob/master/CHANGELOG.md

# Update
docker compose pull auth
docker compose up -d auth

# Test authentication
curl http://localhost:8000/auth/v1/health

Storage Updates

Storage updates may require configuration changes for S3:

# Check for storage-specific config in changelog
cat CHANGELOG.md | grep -A 10 "Storage"

# Update storage
docker compose pull storage imgproxy
docker compose up -d storage imgproxy

Rollback Procedure

If an update causes issues:

Stop Services

docker compose down

Restore Configuration

# Restore .env
cp .env.backup .env

# Restore volumes (if needed)
rm -rf volumes
cp -r volumes.backup volumes

Restore Database

# Stop database
docker compose stop db

# Restore from backup
docker exec -i supabase-db psql -U postgres postgres < backup_20260304.sql

# Start database
docker compose start db

Pin Previous Versions

Edit docker-compose.yml to use previous image tags:

db:
  image: supabase/postgres:15.8.1.060  # Previous version

auth:
  image: supabase/gotrue:v2.185.0  # Previous version

Then start services:

docker compose up -d

Verify Functionality

# Check all services
docker compose ps

# Test API
curl http://localhost:8000/rest/v1/

# Check logs for errors
docker compose logs --tail=50

Update Automation

Automated Image Pulls

Create a weekly update check:

update-check.sh

#!/bin/bash
set -e

cd /path/to/supabase/docker

# Pull latest repository
git fetch origin

# Check for new commits
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git rev-parse origin/master)

if [ $LOCAL != $REMOTE ]; then
    echo "Updates available!"
    echo "New commits:"
    git log HEAD..origin/master --oneline
    
    # Send notification
    echo "Supabase updates available" | mail -s "Supabase Update" [email protected]
else
    echo "No updates available"
fi

Schedule with cron:

# Check weekly on Sundays at 6 AM
0 6 * * 0 /path/to/update-check.sh

Watchtower Integration

Automate image updates with Watchtower (use with caution):

docker-compose.override.yml

version: '3.8'

services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_SCHEDULE=0 0 3 * * 0  # 3 AM every Sunday
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_STOPPED=false
      - WATCHTOWER_MONITOR_ONLY=true  # Set false to auto-update
    command: --interval 86400

Automatic updates can cause unexpected downtime. Only enable in non-production environments.

Monitoring for Updates

GitHub Watch

Watch the Supabase repository:

Visit https://github.com/supabase/supabase
Click “Watch” → “Custom”
Select “Releases”
Get email notifications for new releases

RSS Feed

Subscribe to GitHub releases RSS:

https://github.com/supabase/supabase/releases.atom

Discord Notifications

Join #self-hosting channel on Discord:

Update announcements
Community discussions
Known issues

Recent Updates

Latest significant updates (as of February 2026):

2026-02-16 Release

Breaking Changes

Analytics (Logflare): Changed default to disable public access
Vector: Major version jump from 0.28.1 to 0.53.0
Storage: New environment variables required

Action Required: Update docker-compose.yml and volumes/logs/vector.yml

New Features

Studio: Edge Functions management UI
Storage: S3 protocol endpoint access at /storage/v1/s3
Edge Runtime: Deno cache volume for faster cold starts

Security Fixes

Auth (GoTrue): Security-related patches in v2.185.0
Analytics: Disabled public dashboard access by default
Updated PostgREST to v14.5 with security improvements

2026-01-27 Release

Studio: SQL snippets management
Realtime: Reduced healthcheck logging
PostgREST: Upgraded to v14.3

2025-12-18 Release

Studio: React2Shell security fixes
Auth: Updated to v2.184.0
New utility scripts: generate-keys.sh and db-passwd.sh

See complete changelog.

Update Best Practices

Always Read Changelog First

Never update blindly. Review all changes, especially breaking changes and security notices.

Test Before Production

Use staging environment to test updates. Verify all functionality before applying to production.

Backup Everything

Database, configuration files, and volumes. Test restore procedure regularly.

Update During Low Traffic

Schedule updates during maintenance windows. Communicate downtime to users.

One Service at a Time

For major updates, update and test individual services before updating all.

Monitor After Update

Watch logs and metrics closely for 24 hours after update. Be ready to rollback.

Document Changes

Keep notes on what was updated, when, and any issues encountered.

Getting Help

If you encounter issues:

GitHub Issues

Search existing issues or report new ones

Discord Community

Ask in #self-hosting channel

GitHub Discussions

Community support and questions

Documentation

Official guides and references

Next Steps

Security

Secure your installation

Configuration

Optimize your setup

Monitoring

Set up monitoring and alerts

Backup Strategy

Implement backup automation

Platform

Self-Hosting

CLI

Security

​Update Strategy

​Update Frequency

​Before Updating

​Update Process

​Standard Update

​Breaking Changes Update

​Version History

​Version File

​Service-Specific Updates

​PostgreSQL Updates

​Studio Updates

​Auth (GoTrue) Updates

​Storage Updates

​Rollback Procedure

​Update Automation

​Automated Image Pulls

​Watchtower Integration

​Monitoring for Updates

​GitHub Watch

​RSS Feed

​Discord Notifications

​Recent Updates

​2026-02-16 Release

​2026-01-27 Release

​2025-12-18 Release

​Update Best Practices

​Getting Help

GitHub Issues

Discord Community

GitHub Discussions

Documentation

​Next Steps

Security

Configuration

Monitoring

Backup Strategy

Build docs developers (and LLMs) love

Update Strategy

Update Frequency

Before Updating

Update Process

Standard Update

Breaking Changes Update

Version History

Version File

Service-Specific Updates

PostgreSQL Updates

Studio Updates

Auth (GoTrue) Updates

Storage Updates

Rollback Procedure

Update Automation

Automated Image Pulls

Watchtower Integration

Monitoring for Updates

GitHub Watch

RSS Feed

Discord Notifications

Recent Updates

2026-02-16 Release

2026-01-27 Release

2025-12-18 Release

Update Best Practices

Getting Help

Next Steps