Supabase
Connect a Supabase project you already own so the agent works against your real schema
The Supabase integration links Swarmz to a Supabase project you manage outside of Swarmz. Once connected, the agent reads your Postgres schema, your auth configuration, and your storage buckets, then generates code that targets your real data instead of guessing field names.
This integration is separate from Swarmz Cloud. Cloud is a managed Supabase project we provision for you per project — zero setup, no separate dashboard, billed through your Swarmz plan. The integration here is for the case where you already have a Supabase project (production data, custom extensions, a paid plan you don't want to abandon) and you want the agent to work against it directly.
When to use BYO Supabase
Use the integration if any of these apply:
- You already run a Supabase project in production and your data lives there
- You want to keep your Supabase plan and billing under your own account
- You need access to a region, extension, or Postgres version that Swarmz Cloud doesn't expose
- You're moving an existing app into Swarmz and don't want to migrate the database
- You need to connect staging and production as separate projects so generated code targets the right environment per branch
Use Swarmz Cloud (the default) if you want a backend wired up in seconds with no separate signup, billed through your existing Swarmz plan. You can always start with Cloud and connect a BYO Supabase project later — they're per-project settings.
Setup
Go to Settings → Integrations and click Supabase.
A popup opens with Supabase's OAuth screen. Sign in with the Supabase account that owns the project you want to link.
Approve the requested scopes. Swarmz asks for read access to your projects, schema, and edge functions, plus write access to migrations and edge function deploys so the agent can apply changes directly.
Pick the organization and project to link. You can connect multiple projects to the same workspace — staging and production each as their own connection.
The OAuth flow goes through the integration-oauth edge function, which exchanges the auth code for an access and refresh token, encrypts both with TOKEN_ENCRYPTION_KEY, and stores them as a row in workspace_connections with integration_id = "supabase".
What the agent gets access to
Once linked, the agent can call into your project's Management API and the Supabase JS client on its behalf.
| Capability | What it means |
|---|---|
| Read schema | Lists tables, columns, types, foreign keys, and RLS policies. Generated queries match your real columns — no users.user_name when the column is actually username. |
| Read auth config | Knows which providers you've enabled (email, Google, GitHub, Apple, Discord, etc.) and scaffolds login UI that matches. |
| Run migrations | Generates SQL migrations and applies them directly. You see the migration file in the editor before it runs. |
| Deploy edge functions | Writes the function code, runs supabase functions deploy, and shows you the deployment URL. |
| List storage buckets | Reads bucket names, public/private settings, and existing policies so generated upload UI uses the right bucket. |
| Realtime subscriptions | Wires up channel subscriptions with proper cleanup to listen for row changes on tables you've enabled. |
The agent does not get blanket service-role access. All writes go through the Supabase Management API or the project's Postgres connection using the OAuth-issued token, which is scoped to the operations you authorized during setup. To give the agent service-role access for runtime queries, paste your service role key separately under Project Settings → Environment Variables — it's stored encrypted and only injected into the project's container.
Linking a project
Once the workspace connection exists, you link a Supabase project to a Swarmz project from the editor:
Open the project and click the Cloud tab in the sidebar.
Click Connect existing Supabase.
Pick which of your linked Supabase projects this Swarmz project should use.
The agent then introspects the schema (tables, types, RLS) and stores a snapshot it can reference without re-querying every turn. To refresh the snapshot after you change the schema outside of Swarmz, click Resync schema on the Cloud tab.
Multi-project setups
A common pattern is connecting your Supabase staging project to feature branches and your Supabase production project to the main branch. To do this:
- Connect both Supabase projects under Settings → Integrations → Supabase — they show up as two connections with different names (
my-app-staging,my-app-prod). - In the project's Cloud tab, set Branch overrides so
mainuses prod and other branches use staging. - Generated environment variables (
SUPABASE_URL,SUPABASE_ANON_KEY) get swapped automatically when you deploy or preview.
Disconnecting
From Settings → Integrations → Supabase, click the connection and choose Disconnect. Swarmz revokes the OAuth tokens with Supabase, deletes the workspace_connections row, and breaks the link from any project that pointed at it. Your Supabase project itself is untouched — only the link from Swarmz is removed.
If a project has the disconnected Supabase as its backend, the editor surfaces a banner letting you reconnect or fall back to Swarmz Cloud.
Limits
| Limit | Detail |
|---|---|
| Connections per workspace | No hard cap; we recommend keeping it under 10 for sanity |
| Schema introspection | Cached for 5 minutes; click Resync schema to refresh |
| Migration size | Single migrations capped at 1MB of SQL; split larger ones |
| Token refresh | Automatic, runs the day before expiry |
For Cloud (managed) usage instead, see Cloud Overview.