Supabase 2026: The Open-Source Firebase Alternative Powering 1M+ AI Apps with Postgres Vector Search — Setup Guide

# Your project comes with:
# - PostgreSQL 16 database
# - Auto-generated REST API
# - Built-in Auth
# - 500 MB database storage (free tier)
# - 1 GB file storage (free tier)
# - 2 GB bandwidth (free tier)

# Install the Supabase CLI
# macOS
brew install supabase/tap/supabase

# Linux
npm install -g supabase

# Verify installation
supabase --version
# Expected: 1.220.0

# Login to your account
supabase login

# Initialize a new project
mkdir my-ai-app && cd my-ai-app
supabase init

# Start the local stack (Docker required)
supabase start

# Output includes local API URL, anon key, and service role key
# API URL: http://localhost:54321
# GraphQL URL: http://localhost:54321/graphql/v1
# anon key: eyJhbGciOiJIUzI1NiIs...

# Clone the official self-hosting repository
git clone https://github.com/supabase/supabase.git
cd supabase/docker

# Copy and edit environment variables
cp .env.example .env

# Generate secure secrets
openssl rand -base64 32  # For JWT secret
openssl rand -hex 32     # For anon/service keys

# Edit .env with your domain, SMTP settings, and S3 credentials
nano .env

# Start the stack
docker compose up -d

# Verify all services are healthy
docker compose ps

# Expected output:
# NAME                STATUS
# supabase-db         healthy
# supabase-kong       healthy
# supabase-auth       healthy
# supabase-rest       healthy
# supabase-realtime   healthy
# supabase-storage    healthy
# supabase-meta       healthy
# supabase-studio     healthy

# Install the client library
npm install @supabase/supabase-js

# Or for Python
pip install supabase

// TypeScript / Next.js
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// Test connection
const { data, error } = await supabase.from('test').select('*')
console.log(data)

# Python
from supabase import create_client

supabase = create_client(
    "https://your-project.supabase.co",
    "your-anon-key"
)

# Test connection
response = supabase.table('test').select('*').execute()
print(response.data)

-- In the Supabase SQL Editor or psql
CREATE EXTENSION IF NOT EXISTS vector;

-- Verify the extension is installed
SELECT * FROM pg_extension WHERE extname = 'vector';

-- Create a documents table with embeddings
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    content     TEXT NOT NULL,
    source_url  TEXT,
    embedding   VECTOR(1536),  -- Matches OpenAI text-embedding-3-large
    metadata    JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Create an HNSW index for fast similarity search
CREATE INDEX idx_documents_embedding
ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- Add full-text search index for hybrid search
CREATE INDEX idx_documents_fts ON documents
USING GIN (to_tsvector('english', content));

# Python: Generate embeddings and insert into Supabase
from supabase import create_client
import openai

supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
client = openai.OpenAI(api_key=OPENAI_API_KEY)

def insert_document(title: str, content: str, source_url: str = None):
    # Generate embedding
    response = client.embeddings.create(
        input=content,
        model="text-embedding-3-large"
    )
    embedding = response.data[0].embedding

    # Insert into Supabase
    result = supabase.table('documents').insert({
        'title': title,
        'content': content,
        'source_url': source_url,
        'embedding': embedding,
        'metadata': {'word_count': len(content.split())}
    }).execute()
    return result

# Insert sample documents
insert_document(
    title="Docker Best Practices 2026",
    content="Use multi-stage builds to reduce image size...",
    source_url="https://docs.docker.com"
)

-- Pure SQL: Find top 5 most similar documents
SELECT
    id,
    title,
    content,
    1 - (embedding <=> :query_embedding::vector) AS similarity
FROM documents
ORDER BY embedding <=> :query_embedding::vector
LIMIT 5;

# Python: RAG retrieval function
async def search_similar_documents(query: str, top_k: int = 5):
    # Generate query embedding
    response = client.embeddings.create(
        input=query,
        model="text-embedding-3-large"
    )
    query_embedding = response.data[0].embedding

    # Query Supabase
    result = await supabase.rpc(
        'match_documents',
        {
            'query_embedding': query_embedding,
            'match_threshold': 0.7,
            'match_count': top_k
        }
    ).execute()
    return result.data

-- Create a stored procedure for document retrieval
CREATE OR REPLACE FUNCTION match_documents(
    query_embedding VECTOR(1536),
    match_threshold FLOAT,
    match_count INT
)
RETURNS TABLE (
    id BIGINT,
    title TEXT,
    content TEXT,
    similarity FLOAT
)
LANGUAGE plpgsql
AS $$
BEGIN
    RETURN QUERY
    SELECT
        d.id,
        d.title,
        d.content,
        1 - (d.embedding <=> query_embedding) AS similarity
    FROM documents d
    WHERE 1 - (d.embedding <=> query_embedding) > match_threshold
    ORDER BY d.embedding <=> query_embedding
    LIMIT match_count;
END;
$$;

# rag_pipeline.py
from supabase import create_client
from openai import OpenAI
import json

class SupabaseRAG:
    def __init__(self, supabase_url: str, supabase_key: str, openai_key: str):
        self.supabase = create_client(supabase_url, supabase_key)
        self.openai = OpenAI(api_key=openai_key)

    def embed_and_store(self, chunks: list[dict]):
        """Store document chunks with embeddings."""
        for chunk in chunks:
            embedding = self.openai.embeddings.create(
                input=chunk['text'],
                model="text-embedding-3-large"
            ).data[0].embedding

            self.supabase.table('documents').insert({
                'title': chunk['title'],
                'content': chunk['text'],
                'embedding': embedding,
                'metadata': chunk.get('metadata', {})
            }).execute()

    def retrieve(self, query: str, top_k: int = 5) -> list[dict]:
        """Retrieve relevant documents using vector search."""
        query_embedding = self.openai.embeddings.create(
            input=query,
            model="text-embedding-3-large"
        ).data[0].embedding

        results = self.supabase.rpc(
            'match_documents',
            {
                'query_embedding': query_embedding,
                'match_threshold': 0.75,
                'match_count': top_k
            }
        ).execute()
        return results.data

    def generate(self, query: str, context: list[dict]) -> str:
        """Generate response using retrieved context."""
        context_text = "\n\n".join([
            f"[Source: {doc['title']}]\n{doc['content']}"
            for doc in context
        ])

        response = self.openai.chat.completions.create(
            model="gpt-4.1-mini",
            messages=[
                {
                    "role": "system",
                    "content": "You are a helpful assistant. Answer based only on the provided context. Cite your sources."
                },
                {
                    "role": "user",
                    "content": f"Context:\n{context_text}\n\nQuestion: {query}"
                }
            ],
            temperature=0.3,
            max_tokens=1000
        )
        return response.choices[0].message.content

    def chat(self, query: str) -> dict:
        """End-to-end RAG pipeline."""
        context = self.retrieve(query)
        answer = self.generate(query, context)
        return {
            'query': query,
            'answer': answer,
            'sources': [doc['title'] for doc in context],
            'similarity_scores': [doc['similarity'] for doc in context]
        }

# Usage
rag = SupabaseRAG(SUPABASE_URL, SUPABASE_KEY, OPENAI_KEY)
result = rag.chat("What are Docker best practices?")
print(result['answer'])

-- Enable Row Level Security
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- Create a policy: users can only read their own documents
CREATE POLICY "Users can read own documents"
ON documents FOR SELECT
USING (auth.uid() = user_id);

-- Create a policy: users can insert their own documents
CREATE POLICY "Users can insert own documents"
ON documents FOR INSERT
WITH CHECK (auth.uid() = user_id);

// Sign up a new user
const { data: authData, error: authError } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// Sign in
const { data: session } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// Access token for API calls
const accessToken = session.session?.access_token

// Query with auth context (RLS automatically enforced)
const { data } = await supabase
  .from('documents')
  .select('*')

# Python: Server-side auth with service role key
supabase_admin = create_client(SUPABASE_URL, SERVICE_ROLE_KEY)

# Bypass RLS for admin operations
all_docs = supabase_admin.table('documents').select('*').execute()

// Subscribe to database changes in real-time
const channel = supabase
  .channel('documents-changes')
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'documents' },
    (payload) => {
      console.log('New document inserted:', payload.new)
      // Trigger re-indexing, notification, or UI update
    }
  )
  .subscribe()

// Unsubscribe when done
supabase.removeChannel(channel)

# Python asyncio version
import asyncio

async def subscribe_to_changes():
    channel = supabase.channel('documents-changes')
    
    def handle_insert(payload):
        print(f"New document: {payload['new']['title']}")
    
    channel.on(
        'postgres_changes',
        {'event': 'INSERT', 'schema': 'public', 'table': 'documents'},
        handle_insert
    ).subscribe()

asyncio.run(subscribe_to_changes())

# Initialize edge function
supabase functions new ai-completion

# Edit the generated file
# supabase/functions/ai-completion/index.ts

// supabase/functions/ai-completion/index.ts
import { serve } from 'https://deno.land/std@0.224.0/http/server.ts'

serve(async (req) => {
  const { prompt } = await req.json()

  // Call OpenAI API from the edge
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${Deno.env.get('OPENAI_API_KEY')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4.1-mini',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 500
    })
  })

  const data = await response.json()

  return new Response(
    JSON.stringify({ completion: data.choices[0].message.content }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

# Set secrets
supabase secrets set OPENAI_API_KEY=sk-...

# Deploy the function
supabase functions deploy ai-completion

# Invoke via HTTP
supabase functions invoke ai-completion --data '{"prompt": "Explain RAG"}'

# docker-compose.prod.yml (excerpt)
services:
  db:
    image: supabase/postgres:15.8.1.040
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGVECTOR_HNSW_EF_SEARCH: 64
    volumes:
      - pgdata:/var/lib/postgresql/data
    command: >
      postgres
        -c shared_preload_libraries='pg_stat_statements,pgvector'
        -c max_connections=200
        -c shared_buffers=2GB
        -c effective_cache_size=6GB
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  kong:
    image: kong:3.7
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /var/lib/kong/kong.yml
    ports:
      - "8000:8000"
    depends_on:
      - auth
      - rest
      - realtime

volumes:
  pgdata:

# .env file for production
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# SMTP for auth emails
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.xxx

# S3-compatible storage
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_ENDPOINT=s3.amazonaws.com
STORAGE_S3_ACCESS_KEY=AKIA...
STORAGE_S3_SECRET_KEY=...

# Automated daily backups with pg_dump
0 2 * * * docker exec supabase-db pg_dump -U postgres -Fc postgres > /backups/supabase-$(date +\%Y\%m\%d).dump

# Or use Supabase's built-in Point-in-Time Recovery (PITR)
# Available on Pro tier and above

# Create a new migration
supabase migration new add_documents_table

# Edit the generated SQL file
# supabase/migrations/20260519000000_add_documents_table.sql

# Apply to local instance
supabase db reset

# Deploy to production
supabase db push

# Generate TypeScript types from schema
supabase gen types typescript --local > src/types/supabase.ts