Supabase Integration

Connect Supabase to Brief so your AI agent can query your product database and answer questions with real data.

Last updated: March 1, 2026

Supabase gives Brief direct access to your product data. Instead of manually pulling reports, ask your agent questions like "how many users signed up this week?" or "what's our most active feature?" and get answers backed by real data.

What can Brief do with Supabase?

  • Query your data — Ask natural language questions, get SQL-backed answers
  • Explore schema — List tables, describe columns, understand your data model
  • Run analytics — Aggregations, counts, trends, and ad-hoc analysis
  • Table-level access control — Admins choose exactly which tables the agent can see
Brief only runs read-only queries. No data is ever inserted, updated, or deleted. All queries are validated as SELECT-only before execution.

Which database should I connect?

We strongly recommend connecting a read replica or analytics database rather than your production instance. This is the same best practice used with BI tools like Metabase, Looker, or Mode.

Benefits of using a read replica:

  • Zero risk to production — Even in a worst-case scenario, production data is unaffected
  • No performance impact — Queries don't compete with your application's traffic
  • Standard practice — Same setup you'd use for any analytics or BI tool

If you don't have a read replica, Supabase makes it easy to create one from your project dashboard under Settings → Database → Read Replicas.

How do I set up this integration?

Setup time: 2-3 minutes
Initial sync: Instant (no background sync needed)
Updates: Real-time queries on each use

Steps

Part 1: Connect your Supabase account

  1. Go to Settings → Integrations in Brief
  2. Find Supabase and click Connect
  3. You'll be redirected to Supabase to authorize Brief
  4. Review the permissions and click Authorize

Part 2: Select your project

  1. After authorization, you'll see a list of your Supabase projects
  2. Select the project you want Brief to query (we recommend a read replica)
  3. Click Next: Choose Tables

Part 3: Choose which tables to expose

  1. You'll see all tables in the selected project
  2. Uncheck any tables you don't want the agent to access
  3. Click Connect
  4. Done! Your agent can now query the selected tables.
Start with a small set of tables. You can always add more later from Settings → Integrations. Starting narrow helps you understand what the agent can do before expanding access.

What permissions does Brief request?

Brief uses Supabase's OAuth to authenticate. The authorization includes:

PermissionWhat it doesWhy Brief needs it
Database ReadRead table schemas and column typesLets the agent understand your data model
Database WriteExecute SQL queries via the Management APIRequired by Supabase for any SQL execution, even read-only queries
Why "Database Write"? Supabase's Management API requires this scope for all SQL execution — there's no separate "read-only query" scope. Brief enforces read-only access at the application level: all queries run in read-only Postgres transactions, and only SELECT statements are allowed.

Security model

Brief applies three layers of protection:

  1. Statement validation — Queries are parsed and only SELECT, WITH (CTE), and EXPLAIN statements are allowed. INSERT, UPDATE, DELETE, and DROP are rejected before they reach your database.
  2. Read-only transactions — All queries execute inside a read-only Postgres transaction. Even if a write statement somehow passed validation, the database itself would reject it.
  3. Table allowlist — The agent can only query tables your admin explicitly approved during setup. Queries referencing other tables are blocked.

How does it work in chat?

Once connected, your agent can answer data questions directly:

You: How many users signed up this month? Agent: runs SELECT count(*) FROM public.users WHERE created_at >= '2026-03-01' You had 847 new signups this month, up 12% from February.

The agent discovers your database through Brief's skill system — it won't see database tools until the conversation is relevant, keeping context focused.

Managing connections

Adding more projects

Go to Settings → Integrations, find Supabase, and click Add Project to connect additional databases.

Changing table access

To modify which tables are accessible:

  1. Go to Settings → Integrations
  2. Find the Supabase project you want to modify
  3. Click the settings icon
  4. Update the table selection
  5. Save

Disconnecting

To remove a Supabase project:

  1. Go to Settings → Integrations
  2. Find the project and click Disconnect

Common Issues

"SQL execution requires additional permissions"

Cause: Your Supabase connection was authorized without the database query scope. Fix: Disconnect and reconnect Supabase. The updated authorization flow will request the necessary permissions.

Agent says "I can see tables but can't query data"

Cause: Same as above — the agent can read schema (which needs fewer permissions) but can't execute queries. Fix: Reconnect Supabase from Settings → Integrations.

"Access denied: table not in the allowed list"

Cause: The table you're asking about wasn't selected during setup. Fix: Update the table allowlist in Settings → Integrations → your Supabase project.

Queries are slow

Cause: Complex queries on large tables, or querying a production database under load. Fix:

  • Use a read replica instead of production
  • Ask more specific questions (the agent will use LIMIT and targeted WHERE clauses)
  • Results are automatically truncated to prevent context overflow

What's Next?

Now that Supabase is connected: