Supascale
Sign Up

Supabase June 2026 Breaking Changes: Self-Hoster Prep Guide

Prepare for Supabase's June 2026 breaking changes: Postgres 17 default, Analytics opt-in, and database role updates. Complete migration checklist.

Cover Image for Supabase June 2026 Breaking Changes: Self-Hoster Prep Guide

Supabase is rolling out significant changes to self-hosted deployments in June 2026. If you're running self-hosted Supabase, you need to prepare now—or risk broken deployments when you pull the latest docker-compose.yml.

This guide covers the three major breaking changes, who's affected, and exactly how to prepare your infrastructure.

What's Changing in June 2026

Supabase announced three breaking changes for self-hosted deployments, staggered across the first two weeks of June:

Week of June 1, 2026:

  • Analytics (Logflare) and Vector services move to an opt-in overlay file
  • Default stack becomes leaner—no log aggregation out of the box

Week of June 15, 2026:

  • Default database image switches from Postgres 15 to Postgres 17
  • Studio and postgres-meta switch from supabase_admin role to postgres

Let's break down each change and what you need to do.

Change 1: Analytics Becomes Optional

Starting the week of June 1, Analytics (Logflare) and Vector services are removed from the default docker-compose.yml and moved to a separate overlay file: docker-compose.logs.yml.

What This Means

Running docker compose up -d after this change starts a leaner stack without log aggregation. The Logs menu item in Studio also disappears by default.

Why Supabase Made This Change

Analytics (Logflare) is resource-intensive. In production, it can consume significant CPU and memory—resources many self-hosters would rather allocate to their database. Since Studio, Auth, Storage, PostgREST, and Realtime all function without analytics, making it optional reduces the baseline footprint.

For those running Supabase on low-memory servers, this is actually good news. Your default deployment becomes lighter.

How to Prepare

If you want to keep Analytics:

After pulling the updated compose file, start your stack with the overlay:

docker compose -f docker-compose.yml -f docker-compose.logs.yml up -d

If you don't use Analytics:

No action needed. Your deployment becomes slightly more efficient. Just be aware that if your monitoring or debugging workflows depend on the Logs UI in Studio, you'll need to enable the overlay or switch to an external solution.

If you use external observability:

Many production deployments already use external log management with tools like Grafana Loki or Datadog. This change aligns with that pattern—use the built-in analytics during development, but rely on dedicated observability tools in production.

Change 2: Postgres 17 Becomes Default

The week of June 15, the default database image switches from Postgres 15 to Postgres 17. This is the most impactful change and requires careful preparation.

Critical Warning: Extension Deprecations

If your database uses any of these extensions, you cannot upgrade to Postgres 17:

  • timescaledb
  • plv8
  • plcoffee
  • plls

These extensions are no longer included in the Supabase Postgres 17 images. Check your enabled extensions before planning any upgrade:

SELECT * FROM pg_extension;

What Happens If You Pull Without Preparing

Existing Postgres 15 data directories do not auto-upgrade. If you pull the new compose file and run docker compose up -d against an existing PG 15 volume, Postgres will fail to start—PG 17 cannot read a PG 15 data directory directly.

Migration Options

Option A: Stay on Postgres 15 (Temporary)

Pin your database image to a specific Postgres 15 tag in your docker-compose.yml:

db:
  image: supabase/postgres:15.6.1.145

The PG 15 images remain available on Docker Hub. This buys you time but isn't a permanent solution—eventually you'll want the performance improvements and upstream fixes in Postgres 17.

Option B: Upgrade Using pg_upgrade

Supabase provides upgrade scripts that use pg_upgrade to migrate your data in place. This is the recommended path for production deployments.

Requirements before upgrading:

  • At least 2x your current database size + 5 GB of free disk space
  • A complete backup (the script creates one, but always make your own)
  • Downtime window—the upgrade isn't instant

For the complete upgrade process, see our version migration guide.

Option C: Fresh Start with Data Migration

For new deployments or if you're comfortable with a manual migration:

docker compose -f docker-compose.yml -f docker-compose.pg17.yml up -d

Then restore your data using pg_restore or your existing backup and restore procedures.

Postgres 17 Benefits

If you're on the fence about upgrading, Postgres 17 brings meaningful improvements:

  • Enhanced logical replication with fine-grained publication filters
  • Native JSON output formatting for better performance
  • Improved query planning for complex joins
  • Better vacuum performance for large tables

The Supabase Cloud platform already runs Postgres 17 as the default. Aligning self-hosted deployments means better consistency if you ever need to migrate or reference documentation.

Change 3: Database Role Switch

The week of June 15, Studio and postgres-meta switch from using supabase_admin to the postgres role.

Why This Matters

If you have objects in your database owned by supabase_admin, Studio operations may fail after the update. This affects:

  • Tables you created through Studio before this change
  • Functions, triggers, or views created by migrations run through Studio
  • Any objects explicitly granted to supabase_admin

How to Prepare

Run this query to identify potentially affected objects:

SELECT 
  schemaname,
  tablename,
  tableowner 
FROM pg_tables 
WHERE tableowner = 'supabase_admin';

For each affected object, transfer ownership to postgres:

ALTER TABLE your_schema.your_table OWNER TO postgres;

Supabase will provide a one-time migration script for the public schema. If you have custom schemas, you may need to run similar ownership transfers manually.

Best Practice: Use Migrations

This change reinforces why database migrations matter. When your schema changes are versioned in code and run through the CLI, ownership and role issues become predictable and manageable.

Your June 2026 Preparation Checklist

Here's a condensed checklist to prepare your self-hosted Supabase for June:

Before June 1

  • [ ] Decide whether you need Analytics/Logflare
  • [ ] If yes, update your start command to include the overlay
  • [ ] If using external observability, confirm your setup works without built-in logs

Before June 15

  • [ ] Check for deprecated extensions (timescaledb, plv8, plcoffee, plls)
  • [ ] If using deprecated extensions, pin to Postgres 15 image
  • [ ] Create a full backup using your backup procedures
  • [ ] Test the backup restoration in a staging environment
  • [ ] Ensure you have 2x database size + 5 GB free disk space
  • [ ] Identify objects owned by supabase_admin
  • [ ] Plan ownership migration or wait for Supabase's script
  • [ ] Schedule a maintenance window for the upgrade

After Upgrading

  • [ ] Verify all services start correctly
  • [ ] Test Studio operations (create table, run query)
  • [ ] Confirm RLS policies function correctly
  • [ ] Run your application's integration tests
  • [ ] Monitor for any authentication issues

Using Supascale to Simplify the Transition

If you're managing multiple self-hosted Supabase projects, these breaking changes multiply your preparation work. Each project needs backup verification, extension checks, and upgrade coordination.

Supascale automates much of this complexity:

  • One-click backups ensure every project has a verified restore point before upgrading
  • Multi-project dashboard shows extension usage across all instances
  • Selective service deployment already lets you run without analytics if you don't need it

The one-time pricing model ($39.99 for unlimited projects) means no surprise costs when you're managing multiple staging and production environments through an upgrade cycle.

What If Something Goes Wrong

Even with preparation, upgrades can surface unexpected issues. Here's your recovery playbook:

Postgres Won't Start After Upgrade

Likely cause: Tried to start PG 17 against a PG 15 data directory.

Recovery:

  1. Stop the containers
  2. Restore your data directory backup
  3. Pin to PG 15 image and restart
  4. Follow the proper pg_upgrade process

Studio Operations Fail

Likely cause: Object ownership not migrated from supabase_admin.

Recovery:

  1. Connect directly via psql or another client
  2. Run ownership transfer commands
  3. Restart Studio

Extensions Missing

Likely cause: Using deprecated extension that's not in PG 17 images.

Recovery:

  1. Pin to PG 15 until you can remove the extension dependency
  2. Evaluate alternatives (plv8 → Edge Functions, for example)
  3. Plan a longer-term migration

Looking Ahead

Supabase's shift toward a leaner default stack and modern Postgres reflects the platform's maturation. The optional analytics and Postgres 17 default both signal that self-hosted Supabase is becoming more production-focused—less opinionated defaults, more flexibility for operators to configure what they need.

The database role change, while potentially disruptive, actually improves the security model. Using the postgres superuser role explicitly is more honest than hiding behind a supabase_admin abstraction that behaves like a superuser anyway.

Further Reading