Supabase
Backend in a box — Postgres database, authentication, file storage, and realtime subscriptions from one service.
Read this for an overview of Supabase in Catalyst.
See Platform docs for detailed auth, database, and storage patterns.
Why Supabase
Supabase gives you a full backend without managing infrastructure. You get a Postgres database, user authentication, file storage, and realtime subscriptions — all with a simple JavaScript client.
It's open source, has excellent documentation, and AI agents understand it well. The free tier is generous for development, and scaling is straightforward.
What Supabase Provides
The services Catalyst uses:
Database
Full Postgres. SQL queries, migrations, Row Level Security, and generated types.
Authentication
Built-in auth. Email/password, magic links, OAuth providers, and session management.
Storage
File storage. Upload files, generate signed URLs, organize in buckets.
Realtime
Live updates. Subscribe to database changes and broadcast events.
Catalyst Integration
Catalyst wraps Supabase in the Platform layer for consistent patterns:
Quick Start
Basic Supabase usage in Catalyst:
Server-side data fetching
import { createClient } from "@/lib/supabase/server"
export default async function Page() {
const supabase = await createClient()
const { data, error } = await supabase
.from("posts")
.select("id, title")
.order("created_at", { ascending: false })
return <PostList posts={data} />
}Client-side with real-time
"use client"
import { createSupabaseBrowserClient } from "@/lib/supabase"
import { useEffect, useState } from "react"
export function LivePosts() {
const [posts, setPosts] = useState([])
const supabase = createSupabaseBrowserClient()
useEffect(() => {
const channel = supabase
.channel("posts")
.on("postgres_changes", { event: "*", schema: "public", table: "posts" },
(payload) => { /* handle change */ }
)
.subscribe()
return () => { supabase.removeChannel(channel) }
}, [])
}Row Level Security
RLS is enabled by default
Without policies, queries return empty results. Every table needs policies defining who can access what data.
Common RLS Pattern
-- Users can only see their own records CREATE POLICY "Users can view own records" ON posts FOR SELECT TO authenticated USING (user_id = auth.uid());
Setup
Create a Supabase project
Go to supabase.com and create a new project.
Get your credentials
In Dashboard → Project Settings → API, copy the URL and anon key.
Configure environment
Add to .env.local:
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-anon-key
Learn More
For AI Agents
Key rules:
- Use Catalyst's Platform layer, not raw Supabase client
- Server:
createClient()from@/lib/supabase/server - Browser:
createSupabaseBrowserClient()from@/lib/supabase - Always add RLS policies for new tables
- Read Platform docs for auth, database, and storage patterns
Next Steps
Explore platform capabilities: