Supabase Integration In Emergent

Overview

Supabase is an open-source Firebase alternative that provides PostgreSQL database, authentication, real-time subscriptions, and storage. This guide walks you through integrating Supabase into your Emergent application.

Supabase is perfect when you need a powerful relational database with real-time capabilities and built-in authentication.

What You’ll Build

By the end of this guide, you’ll have:

Supabase PostgreSQL database connected
CRUD operations for your data
Real-time subscriptions (optional)
Supabase Authentication (optional)
File storage (optional)

Prerequisites

Supabase Account

Create a free account at supabase.com

Create Project

Create a new Supabase project

Get Credentials

Copy your project URL and API keys

Step 1: Create Supabase Project & Get Credentials

Create Supabase Project

Go to https://supabase.com
Sign up or log in
Click New Project
Fill in project details:
- Name: Your project name
- Database Password: Strong password (save this!)
- Region: Choose closest to your users
Click Create new project
Wait ~2 minutes for project initialization

Get Your Credentials

Once project is ready, go to Settings → API
Copy these three values:

Project URL

Format: https://xxxxx.supabase.coUse: Both frontend and backend

Anon (Public) Key

Starts with: eyJhbGci...Use: Frontend (safe to expose)Length: Very long JWT token

Service Role Key

Starts with: eyJhbGci...Use: Backend (keep secret!)Note: Has full database access

Never expose the Service Role Key in frontend! It bypasses all security rules.

Step 2: Request Integration from Emergent Agent

Basic Database Integration

I need to integrate Supabase PostgreSQL database:

Purpose: Replace MongoDB with PostgreSQL for [your use case]

Supabase Credentials:
- Project URL: https://xxxxx.supabase.co
- Anon Key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- Service Role Key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Database Tables Needed:
- users: id (uuid), email (text), name (text), created_at (timestamp)
- posts: id (uuid), user_id (uuid), title (text), content (text), created_at (timestamp)
- comments: id (uuid), post_id (uuid), user_id (uuid), content (text), created_at (timestamp)

Features Required:
- CRUD operations for all tables
- Backend API endpoints
- Frontend client for data fetching
- Foreign key relationships

Technical Setup:
- Backend: Supabase Python client for API endpoints
- Frontend: Supabase JS client for direct queries
- Create SQL migration script for tables

Please call integration_playbook_expert for Supabase setup.

With Authentication

I need Supabase with database and authentication:

Purpose: PostgreSQL database + Google social login

Supabase Credentials:
- Project URL: https://xxxxx.supabase.co
- Anon Key: eyJhbGci...
- Service Role Key: eyJhbGci...

Database Tables:
[List your tables]

Authentication:
- Google social login
- Email/password signup
- Protected routes
- User session management

Setup:
- Backend: API with Supabase auth
- Frontend: Login UI + auth context
- Database: User profiles table

Please call integration_playbook_expert.

With Real-Time Features

I need Supabase with real-time subscriptions:

Purpose: Chat app with real-time message updates

Supabase Credentials:
- Project URL: https://xxxxx.supabase.co
- Anon Key: eyJhbGci...
- Service Role Key: eyJhbGci...

Real-Time Features:
- Subscribe to new messages
- Live updates without refresh
- Typing indicators
- Online presence

Database Tables:
- messages: id, room_id, user_id, content, created_at
- rooms: id, name, created_at

Setup:
- Backend: Message API endpoints
- Frontend: Real-time subscription to messages table

Please call integration_playbook_expert.

Step 3: What the Integration Agent Will Create

Backend Implementation

1. Environment Variables (/app/backend/.env)

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_KEY=your_service_role_key_here

2. Supabase Client Setup

from supabase import create_client, Client
import os

supabase_url = os.environ.get("SUPABASE_URL")
supabase_key = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(supabase_url, supabase_key)

3. API Endpoints

Get All Records

@app.get("/api/users")
async def get_users():
    try:
        response = supabase.table('users').select("*").execute()
        return {"users": response.data}
    except Exception as e:
        return {"error": str(e)}

Create Record

@app.post("/api/users")
async def create_user(user_data: dict):
    try:
        response = supabase.table('users').insert(user_data).execute()
        return {"user": response.data[0]}
    except Exception as e:
        return {"error": str(e)}

Update Record

@app.put("/api/users/{user_id}")
async def update_user(user_id: str, user_data: dict):
    try:
        response = supabase.table('users').update(user_data).eq('id', user_id).execute()
        return {"user": response.data[0]}
    except Exception as e:
        return {"error": str(e)}

Delete Record

@app.delete("/api/users/{user_id}")
async def delete_user(user_id: str):
    try:
        response = supabase.table('users').delete().eq('id', user_id).execute()
        return {"message": "User deleted successfully"}
    except Exception as e:
        return {"error": str(e)}

Complex Query with Joins

@app.get("/api/posts-with-users")
async def get_posts_with_users():
    try:
        response = supabase.table('posts').select(
            "*, users(id, name, email)"
        ).execute()
        return {"posts": response.data}
    except Exception as e:
        return {"error": str(e)}

Frontend Implementation

1. Environment Variables (/app/frontend/.env)

REACT_APP_SUPABASE_URL=https://xxxxx.supabase.co
REACT_APP_SUPABASE_ANON_KEY=your_anon_key_here

2. Supabase Client Setup

// src/supabaseClient.js
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.REACT_APP_SUPABASE_URL
const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

3. Using Supabase in Components

Fetch Data

import { supabase } from './supabaseClient'
import { useState, useEffect } from 'react'

function UsersList() {
  const [users, setUsers] = useState([])
  const [loading, setLoading] = useState(true)
  
  useEffect(() => {
    fetchUsers()
  }, [])
  
  const fetchUsers = async () => {
    try {
      const { data, error } = await supabase
        .from('users')
        .select('*')
        .order('created_at', { ascending: false })
      
      if (error) throw error
      setUsers(data)
    } catch (error) {
      console.error('Error fetching users:', error)
    } finally {
      setLoading(false)
    }
  }
  
  if (loading) return <div>Loading...</div>
  
  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          <h3>{user.name}</h3>
          <p>{user.email}</p>
        </div>
      ))}
    </div>
  )
}

Insert Data

const createUser = async (userData) => {
  try {
    const { data, error } = await supabase
      .from('users')
      .insert([userData])
      .select()
    
    if (error) throw error
    
    console.log('User created:', data[0])
    return data[0]
  } catch (error) {
    console.error('Error creating user:', error)
  }
}

// Usage
await createUser({
  name: 'John Doe',
  email: 'john@example.com'
})

Real-Time Subscription

import { useEffect, useState } from 'react'
import { supabase } from './supabaseClient'

function RealTimeMessages() {
  const [messages, setMessages] = useState([])
  
  useEffect(() => {
    // Fetch initial messages
    fetchMessages()
    
    // Subscribe to new messages
    const subscription = supabase
      .channel('messages')
      .on('postgres_changes', 
        { 
          event: 'INSERT', 
          schema: 'public', 
          table: 'messages' 
        },
        (payload) => {
          console.log('New message:', payload.new)
          setMessages(prev => [payload.new, ...prev])
        }
      )
      .subscribe()
    
    // Cleanup
    return () => {
      subscription.unsubscribe()
    }
  }, [])
  
  const fetchMessages = async () => {
    const { data } = await supabase
      .from('messages')
      .select('*')
      .order('created_at', { ascending: false })
    
    setMessages(data || [])
  }
  
  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
    </div>
  )
}

Step 4: Create Database Tables in Supabase

Method 1: Using Supabase Dashboard (Recommended)

Open Table Editor

In Supabase Dashboard, click Table Editor in sidebar

Create New Table

Click Create a new table

Define Table

Name: users
Enable Row Level Security: Check or uncheck
Columns: Define your columns

Add Columns

Click Add column for each field:

id (uuid, primary key, default: gen_random_uuid())
name (text)
email (text)
created_at (timestamptz, default: now())

Save Table

Click Save to create the table

Method 2: Using SQL Editor

Go to SQL Editor in Supabase Dashboard
Create a new query
Run this SQL:

-- Create users table
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create posts table
CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  content TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create comments table
CREATE TABLE comments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes for better performance
CREATE INDEX idx_posts_user_id ON posts(user_id);
CREATE INDEX idx_comments_post_id ON comments(post_id);
CREATE INDEX idx_comments_user_id ON comments(user_id);

Method 3: Ask Agent to Generate SQL

Can you create SQL migration for Supabase with these tables:

**users table:**
- id (uuid, primary key)
- email (text, unique)
- name (text)
- avatar_url (text, nullable)
- created_at (timestamp)

**posts table:**
- id (uuid, primary key)
- user_id (uuid, foreign key to users)
- title (text)
- content (text)
- published (boolean, default false)
- created_at (timestamp)

**tags table:**
- id (uuid, primary key)
- name (text, unique)

**post_tags table (many-to-many):**
- post_id (uuid, foreign key to posts)
- tag_id (uuid, foreign key to tags)
- primary key (post_id, tag_id)

Include indexes for foreign keys and commonly queried fields.

Step 5: Enable Real-Time (Optional)

Enable Real-Time for Tables

In Supabase Dashboard, go to Database → Replication
Find your table (e.g., “messages”)
Toggle Real-time to enabled
Click Save

Frontend Real-Time Subscription

Already shown in Step 3 - Frontend Implementation section.

Step 6: Setup Row Level Security (RLS)

Production Security: Always enable RLS for production apps to protect your data.

What is RLS?

Row Level Security allows you to restrict which rows users can see and modify based on policies.

Enable RLS

Go to Authentication → Policies
Select your table
Click Enable RLS

Create Policies

Example: Users can only see their own data

-- Policy: Users can read their own posts
CREATE POLICY "Users can view own posts"
  ON posts
  FOR SELECT
  USING (auth.uid() = user_id);

-- Policy: Users can insert their own posts
CREATE POLICY "Users can create posts"
  ON posts
  FOR INSERT
  WITH CHECK (auth.uid() = user_id);

-- Policy: Users can update their own posts
CREATE POLICY "Users can update own posts"
  ON posts
  FOR UPDATE
  USING (auth.uid() = user_id);

-- Policy: Users can delete their own posts
CREATE POLICY "Users can delete own posts"
  ON posts
  FOR DELETE
  USING (auth.uid() = user_id);

Example: Public read, authenticated write

-- Anyone can read posts
CREATE POLICY "Public posts are visible"
  ON posts
  FOR SELECT
  USING (published = true);

-- Authenticated users can create posts
CREATE POLICY "Authenticated users can create posts"
  ON posts
  FOR INSERT
  TO authenticated
  WITH CHECK (true);

Step 7: Setup Supabase Authentication (Optional)

Enable Auth Providers

Go to Authentication → Providers
Enable desired providers:
- Email/Password
- Google
- GitHub
- etc.

Google OAuth Setup

Get Google Credentials

Create OAuth app in Google Cloud Console

Configure in Supabase

Add Client ID and Secret in Supabase

Set Redirect URL

Add redirect URL to Google OAuth app

Frontend Auth Implementation

import { supabase } from './supabaseClient'

// Sign up with email
const signUp = async (email, password) => {
  const { data, error } = await supabase.auth.signUp({
    email,
    password,
  })
  if (error) console.error('Error:', error)
  return data
}

// Sign in with email
const signIn = async (email, password) => {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  })
  if (error) console.error('Error:', error)
  return data
}

// Sign in with Google
const signInWithGoogle = async () => {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'google',
  })
}

// Sign out
const signOut = async () => {
  const { error } = await supabase.auth.signOut()
}

// Get current user
const getUser = async () => {
  const { data: { user } } = await supabase.auth.getUser()
  return user
}

Step 8: Test the Integration

Start Preview

Click Preview in Emergent

Test Database Operations

Try creating a record
Fetch and display records
Update a record
Delete a record

Check Supabase Dashboard

Verify data appears in Supabase Table Editor

Test Real-Time (if enabled)

Open app in two browser windows
Create record in one
Should appear in other instantly

Test Auth (if configured)

Try signing up
Try logging in
Check protected routes

Step 9: Deploy

Configure Environment Variables

In Emergent deployment settings, add: Backend:

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_KEY=your_service_role_key

Frontend:

REACT_APP_SUPABASE_URL=https://xxxxx.supabase.co
REACT_APP_SUPABASE_ANON_KEY=your_anon_key

Pre-Deployment Checklist

All tables created in Supabase
RLS policies configured (if using)
Environment variables set
Auth providers configured (if using)
Real-time enabled on required tables (if using)
Tested in Preview mode

Common Use Cases

Use Case 1: Blog Platform

I need Supabase for a blog platform:

**Tables:**
- users: author profiles
- posts: blog posts with rich content
- comments: reader comments
- tags: post categorization

**Features:**
- CRUD for posts
- Real-time comments
- User authentication
- Post search and filtering

Supabase credentials: [will provide]

Please call integration_playbook_expert.

Use Case 2: Real-Time Chat

I need Supabase for a chat application:

**Tables:**
- users: user profiles
- rooms: chat rooms
- messages: chat messages
- room_members: room membership

**Features:**
- Real-time message updates
- Typing indicators
- Online presence
- Message history
- User authentication

Supabase credentials: [will provide]

Please call integration_playbook_expert.

Troubleshooting

Connection Error

Error: “Failed to connect to Supabase”Solutions:

Verify Supabase URL is correct
Check API keys are correct
Ensure project is active (not paused)
Verify environment variables are loaded

Ask agent:

Supabase connection failing with error:
[paste error]

Can you verify the Supabase client configuration?

RLS Blocking Queries

Error: “Row level security policy” or empty resultsSolutions:

Check if RLS is enabled
Verify policies allow the operation
Use service role key in backend (bypasses RLS)
Test with RLS disabled temporarily

Ask agent:

Supabase queries returning empty due to RLS.

Can you:
1. Check RLS policies
2. Update policies to allow [operation]
3. Or guide me to disable RLS for testing

Real-Time Not Working

Error: Subscriptions not receiving updatesSolutions:

Verify Real-time is enabled for table
Check subscription code is correct
Ensure listening for correct events
Check browser console for errors

Ask agent:

Real-time subscriptions not working for [table].

Updates in database but not appearing in UI.

Can you debug the real-time subscription code?

Best Practices

Security

Always use RLS in production
Never expose service role key in frontend
Use anon key for frontend
Validate data server-side
Use UUID for primary keys

Performance

Create indexes on foreign keys
Index frequently queried columns
Use select() to specify needed columns
Limit query results with .limit()
Use pagination for large datasets

Data Modeling

Use foreign keys for relationships
Set appropriate ON DELETE actions
Use TIMESTAMPTZ for timestamps
Add created_at/updated_at fields
Normalize data appropriately

Real-Time

Only enable for needed tables
Clean up subscriptions on unmount
Handle connection errors
Consider rate limiting
Use channels for grouping

Additional Resources

Supabase Docs

Official Supabase documentation

SQL Reference

PostgreSQL and Supabase SQL guide

RLS Guide

Row Level Security documentation

Supabase Dashboard

Manage your Supabase projects

Quick Reference

Integration Prompt

Integrate Supabase:

Credentials: [URL, anon key, service role key]
Tables: [List tables]
Features: [CRUD, real-time, auth]

Please call integration_playbook_expert.

Common Queries

// Select all
supabase.from('table').select('*')

// Select specific columns
supabase.from('table').select('id, name')

// With filter
supabase.from('table').select('*').eq('status', 'active')

// With join
supabase.from('posts').select('*, users(name, email)')

// Insert
supabase.from('table').insert([{...}])

// Update
supabase.from('table').update({...}).eq('id', id)

// Delete
supabase.from('table').delete().eq('id', id)

For Supabase questions, ask: “How do I [operation] with Supabase?” or “Show me an example of [feature] in Supabase.”

​Overview

​What You’ll Build

​Prerequisites

​Step 1: Create Supabase Project & Get Credentials

​Create Supabase Project

​Get Your Credentials

Project URL

Anon (Public) Key

Service Role Key

​Step 2: Request Integration from Emergent Agent

​Basic Database Integration

​With Authentication

​With Real-Time Features

​Step 3: What the Integration Agent Will Create

​Backend Implementation

​Frontend Implementation

​Step 4: Create Database Tables in Supabase

​Method 1: Using Supabase Dashboard (Recommended)

​Method 2: Using SQL Editor

​Method 3: Ask Agent to Generate SQL

​Step 5: Enable Real-Time (Optional)

​Enable Real-Time for Tables

​Frontend Real-Time Subscription

​Step 6: Setup Row Level Security (RLS)

​What is RLS?

​Enable RLS

​Create Policies

​Step 7: Setup Supabase Authentication (Optional)

​Enable Auth Providers

​Google OAuth Setup

​Frontend Auth Implementation

​Step 8: Test the Integration

​Step 9: Deploy

​Configure Environment Variables

​Pre-Deployment Checklist

​Common Use Cases

​Use Case 1: Blog Platform

​Use Case 2: Real-Time Chat

​Troubleshooting

​Best Practices

Security

Performance

Data Modeling

Real-Time

​Additional Resources

Supabase Docs

SQL Reference

RLS Guide

Supabase Dashboard

​Quick Reference

​Integration Prompt

​Common Queries

Overview

What You’ll Build

Prerequisites

Step 1: Create Supabase Project & Get Credentials

Create Supabase Project

Get Your Credentials

Step 2: Request Integration from Emergent Agent

Basic Database Integration

With Authentication

With Real-Time Features

Step 3: What the Integration Agent Will Create

Backend Implementation

Frontend Implementation

Step 4: Create Database Tables in Supabase

Method 1: Using Supabase Dashboard (Recommended)

Method 2: Using SQL Editor

Method 3: Ask Agent to Generate SQL

Step 5: Enable Real-Time (Optional)

Enable Real-Time for Tables

Frontend Real-Time Subscription

Step 6: Setup Row Level Security (RLS)

What is RLS?

Enable RLS

Create Policies

Step 7: Setup Supabase Authentication (Optional)

Enable Auth Providers

Google OAuth Setup

Frontend Auth Implementation

Step 8: Test the Integration

Step 9: Deploy

Configure Environment Variables

Pre-Deployment Checklist

Common Use Cases

Use Case 1: Blog Platform

Use Case 2: Real-Time Chat

Troubleshooting

Best Practices

Additional Resources

Quick Reference

Integration Prompt

Common Queries