One Supabase project can serve a whole book of client sites: one Postgres, one Storage layer, one Auth instance. Row Level Security policies scope every read and write to a `site_id`, and the service-role key never leaves a server context. You pay for one project instead of ten, migrations happen in one place instead of ten, and the tenant boundary sits in the database, where a leaky API can’t bypass it.
We ran this setup across the FH client book before moving our sites onto a shared CMS, and most of it still holds. Here’s how it works.
Why one project, not one per client
Cost: Supabase pricing is per-project. Ten clients means ten subscriptions for projects that mostly sit idle. One shared Pro project covers a small client book comfortably.
Operational simplicity: one place to manage migrations, one place to monitor logs, one place to set up backups. A schema change lands once and applies to every tenant at the same time.
Trade-off: a Supabase outage takes every client down. Mitigate it with Cloudflare caching in front of every read endpoint so static content keeps serving even if Supabase is unavailable, and verify your backups weekly.
The schema: site_id on every row
Every tenant-scoped table has a `site_id text not null` column. The value is a slug like `"client-a"` or `"client-b"`. There’s a `sites` table with the canonical list. Foreign keys enforce that every row points at a real site.
create table sites (
id text primary key,
name text not null,
created_at timestamptz default now()
);
create table submissions (
id uuid primary key default gen_random_uuid(),
site_id text references sites(id) not null,
name text not null,
email text not null,
phone text,
message text,
created_at timestamptz default now()
);
create index on submissions(site_id, created_at desc);The RLS policies: scope by site_id, reject everything else
Every tenant-scoped table has RLS enabled. The policies allow reads and writes only when the caller’s JWT contains a `site_id` claim matching the row. The default is deny. There is no anon-read policy on tenant tables — anon access to client data is impossible from the client SDK.
alter table submissions enable row level security;
create policy "insert own site" on submissions
for insert with check (site_id = (auth.jwt() ->> 'site_id'));
create policy "select own site" on submissions
for select using (site_id = (auth.jwt() ->> 'site_id'));Where the site_id comes from
Two paths. For authenticated users, the `site_id` is injected into the JWT at sign-in by a Supabase auth hook. For anonymous users (a public lead form), use the service-role key on the server side. The role bypasses RLS, so the server code has to set `site_id` itself, from the per-tenant environment variable. The client never sees the service-role key.
Storage buckets: one per tenant
Tenant data goes through RLS-scoped tables. Tenant media goes through bucket-per-tenant Storage. Give each client a public bucket (`client-a-images`, `client-b-images`) for marketing imagery, and a private bucket for anything sensitive. Public buckets are read-only-to-anon, write-only-to-service-role. Private buckets have RLS policies that scope to the user’s `site_id` claim.
An `imageUrl()` helper resolves bucket paths into public URLs. Swapping buckets later is a single-file change.
Migration workflow
Use the Supabase CLI for migrations, version-controlled in one repo. Each migration is a numbered SQL file under `supabase/migrations/`. Local development runs against a local Supabase stack via `supabase start`; migrations apply locally first, get tested in staging, then ship to prod with `supabase db push`.
# Create a new migration
supabase migration new add_lead_score_column
# Edit supabase/migrations/202605061200_add_lead_score_column.sql
# Apply locally
supabase db reset
# Apply to prod
supabase db push --linkedFour migration rules for a shared project
- Migrations are forward-only. Don’t write down-migrations: if a migration is wrong, ship a new one that fixes it.
- Never run a migration that takes more than 30s on a populated table without a maintenance window. ALTER TABLE … ADD COLUMN with a default value on a 5M-row table will lock the table.
- Always test on a clone of production data. `supabase db dump` then restore locally before migrating in prod. This is how you catch a long table lock before it hits production.
- Migrations and code changes ship together. A migration that adds a column gets the code that uses it in the same PR.
Auth: per-tenant claims
Supabase Auth uses GoTrue with custom JWT claims. Inject `site_id` into the JWT with an auth hook that runs server-side on sign-in. The hook reads the user’s row in a `user_sites` join table and adds the relevant `site_id` to the claims. Every downstream RLS check uses `auth.jwt() ->> 'site_id'`.
For anon users (public site visitors filling out a form), there’s no JWT and the public RLS policies are deliberately empty. Public form submissions go through a server action using the service-role key, which sets `site_id` from the per-tenant env var. Never trust the client to provide its own site_id.
Backups and disaster recovery
Supabase Pro includes daily point-in-time recovery. Supplement it with weekly `pg_dump` snapshots stored outside Supabase, following the “three places, two formats, one offsite” rule. If Supabase ever fully fails, you can rehydrate the database into a fresh project from those snapshots.
Monitoring and alerting
Supabase exposes query performance and connection metrics in the dashboard. Pipe slow-query logs into your alerting tool and alert on anything over 1s. The Postgres-level monitoring catches things the application monitoring doesn’t — a missing index, a runaway sequential scan, a connection pool exhaustion.
When NOT to use shared multi-tenancy
- Regulated data: HIPAA, PCI, anything with strict data isolation requirements. Even with RLS, the regulator may insist on physical isolation. Spin up a separate project.
- Tenants with wildly different load. One client doing 10k RPS will affect the database for everyone else. Pull the high-volume tenant onto their own project.
- Customer-controlled schemas. If the tenant gets to define columns, the shared-schema approach breaks down. Use a different per-tenant strategy (schema-per-tenant or separate projects).
Where FH runs this now
Our client sites ran on this shared Supabase project until we moved them onto a multi-tenant CMS. The idea carried over: one database for the whole client book, one place to migrate and monitor, and every record tagged with the client it belongs to. What changed is where the boundary lives. The CMS enforces it in its own access rules rather than in RLS policies, and leads, media and logins all live there now. If you’re running multi-tenant SaaS on per-tenant databases or trying to reinvent this pattern on raw Postgres, book a consultation. There’s usually a simpler version of what you’re building.
