Database Setup

Configure your Supabase database with vector search capabilities. This section is crucial for a working installation.

Choose Your SQL File Based on Deployment Mode

You must use the correct SQL file for your deployment mode. Using the wrong schema will cause issues. Not sure which mode? Learn more →

Cloud vs Self-Hosted

ChatRAG is optimized for Supabase Cloud (managed service), which is the easiest path and recommended. Supabase is open-source and can run self-hosted (VPS/private/on-prem). Ensure your Postgres has the pgvector extension with HNSW support available.

Create Supabase Project

Visit supabase.com and create a new project
Choose a region close to your users for optimal performance
Wait for the project to initialize (~2 minutes)

Configure Database Schema

ChatRAG includes deployment-mode specific database setup files that create all required tables, indexes, and security policies.

Single-Tenant Mode

Shared knowledge base, user-isolated chats

supabase/single-tenant-setup.sql

~1,383 lines

Multi-Tenant Mode

Isolated workspaces, team collaboration, RBAC

supabase/multi-tenant-setup.sql

~1,143 lines + organizations

Follow these steps:

Open SQL Editor in your Supabase dashboard
Copy the entire contents of the SQL file matching your deployment mode
Paste and execute the SQL in the editor

Run Once Per Project

The script only needs to be run once per Supabase project. It enables pgvector, creates HNSW indexes, tables, storage buckets, functions, and RLS policies.

What Both Modes Create:

Core tables with Row Level Security (RLS) for data isolation
HNSW vector indexes (15-28x faster than traditional RAG)
Storage buckets for images, videos, and 3D models
Database functions for semantic search operations

Multi-Tenant Mode Adds:

organizations table with subscription tiers & quotas
organization_members with role-based access (owner/admin/member/viewer)
team_invitations for email-based invitations
organization_id columns on documents, chats, and chunks for isolation
Auto-personal org trigger (creates workspace on user signup)

Get Supabase Credentials

From your Supabase project settings, retrieve the following credentials:

Project Settings → API

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<YOUR_SUPABASE_ANON_KEY>

Project Settings → API → Service Role

# Keep this secret - server-side only!
SUPABASE_SERVICE_ROLE_KEY=<YOUR_SUPABASE_SERVICE_ROLE_KEY>

Security Warning

The Service Role Key bypasses Row Level Security and should never be exposed in the browser. It's only used on the server side for admin operations.

Verify Database Setup

Test your database connection to ensure everything is configured correctly:

# 1. Add Supabase credentials to your config
npm run config
# Paste your credentials and save

# 2. Start the development server
npm run dev

# 3. Check browser console for any database errors
# 4. Verify at http://localhost:3000 - you should see the chat interface

Verification Checklist:

Chat interface loads without errors
No database connection errors in browser console
User authentication is working (sign up/login)
Tables visible in Supabase Table Editor

Database Tables Reference

The setup script creates the following core tables:

documents

Stores uploaded document metadata

document_chunks

Vector embeddings for RAG (1536 dimensions)

chats

Chat conversations and history

folders

Chat organization and categorization

subscriptions

Payment and subscription management

admin_settings

Global configuration and settings

whatsapp_sessions

WhatsApp connection data

whatsapp_conversations

WhatsApp chat history

HNSW Vector Search Performance

The HNSW (Hierarchical Navigable Small World) indexes provide 15-28x faster search compared to traditional IVFFlat indexes.

Query time: <50ms for semantic search
Index parameters: m=64, ef_construction=200
Supports 1536-dimensional vectors (OpenAI embeddings)

← Previous: Quick Start Next: API Keys →