SUPABASE_REST_API.md

Supabase REST API Integration

🚀 Problem Solved

Issue: HuggingFace Spaces blocks direct PostgreSQL connections (port 5432) with error [Errno 101] Network is unreachable.

Solution: Use Supabase's REST API via HTTP/HTTPS instead of direct database connections.

✅ What Changed

Before (Direct PostgreSQL)

• Used asyncpg library for direct PostgreSQL connections
• Required port 5432 access
• Failed on HuggingFace Spaces with network errors

After (REST API)

• Uses supabase-py client for REST API access
• Communicates via HTTP/HTTPS (ports 80/443)
• Works perfectly on HuggingFace Spaces

📦 New Files Created

Backend Services

1. src/services/supabase_service_rest.py (410 lines)

   • REST API version of Supabase service
   • HTTP/HTTPS communication only
   • Lazy initialization to avoid import-time configuration

2. src/services/investigation_service_supabase_rest.py (465 lines)

   • Investigation service using REST API
   • Drop-in replacement for PostgreSQL version
   • Same interface, different implementation

Testing

3. scripts/test_supabase_rest.py (117 lines)
   • Complete end-to-end REST API test
   • Tests all CRUD operations
   • Verifies HuggingFace Spaces compatibility

🔧 Configuration

Environment Variables

Add to .env or HuggingFace Spaces settings:

# Supabase REST API Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
SUPABASE_ANON_KEY=your-anon-key-here  # Optional for frontend

Where to get these:

1. Go to: https://app.supabase.com/project/YOUR_PROJECT/settings/api
2. Copy Project URL → SUPABASE_URL
3. Copy service_role (Secret) → SUPABASE_SERVICE_ROLE_KEY
4. Copy anon (Public) → SUPABASE_ANON_KEY (for frontend only)

🧪 Testing Locally

# Install dependencies
venv/bin/pip install supabase gotrue postgrest

# Configure environment
cp .env.example .env
# Edit .env with your Supabase credentials

# Run tests
venv/bin/python scripts/test_supabase_rest.py

Expected output: ```

✅ ALL TESTS PASSED - REST API WORKING!

🎉 This version will work on HuggingFace Spaces!

## 🚢 Deploying to HuggingFace Spaces

### Step 1: Add Environment Variables

Go to your Space settings and add:

SUPABASE_URL=https://pbsiyuattnwgohvkkkks.supabase.co SUPABASE_SERVICE_ROLE_KEY=eyJhbGci... # Your actual key

### Step 2: Update requirements.txt

Already updated with:

supabase>=2.0.0 gotrue>=2.0.0 postgrest>=0.13.0

### Step 3: Push to HuggingFace

```bash
git push hf main

Step 4: Verify in Logs

You should see:

{"event": "Supabase REST service initialized successfully"}
{"event": "investigation_created", "investigation_id": "..."}

Instead of:

{"error": "[Errno 101] Network is unreachable", "event": "database_pool_creation_failed"}

📊 API Comparison

Direct PostgreSQL (Old)

# Uses asyncpg - requires port 5432
from src.services.investigation_service_supabase import investigation_service_supabase

inv = await investigation_service_supabase.create(...)

REST API (New - HuggingFace Compatible)

# Uses HTTP/HTTPS - works on HuggingFace Spaces
from src.services.investigation_service_supabase_rest import investigation_service_supabase_rest

inv = await investigation_service_supabase_rest.create(...)

Interface is identical - only import changes!

🔒 Security

Backend (Service Role)

• Use SUPABASE_SERVICE_ROLE_KEY in backend
• Bypasses Row Level Security (RLS)
• Has full database access
• Never expose in frontend code

Frontend (Anon Key)

• Use SUPABASE_ANON_KEY in frontend
• Respects Row Level Security (RLS)
• Users only see their own data
• Safe to expose in public code

🎯 Use Cases

Use Direct PostgreSQL When:

• Running locally with full network access
• Running on VPS/dedicated servers
• Need advanced PostgreSQL features
• Better performance for bulk operations

Use REST API When:

• Deploying to HuggingFace Spaces ✅
• Network restrictions on database ports
• Serverless environments (Vercel, Netlify)
• Testing without PostgreSQL setup

📈 Performance Comparison

Metric	Direct PostgreSQL	REST API
Connection	Direct TCP	HTTP/HTTPS
Latency	~5-10ms	~20-30ms
Bulk Operations	Fast (native SQL)	Slower (HTTP overhead)
Compatibility	Restricted networks	Works everywhere
HuggingFace Spaces	❌ Fails	✅ Works

🐛 Troubleshooting

Error: "Network is unreachable"

Problem: Direct PostgreSQL connection blocked Solution: Use REST API version instead

Error: "SUPABASE_URL environment variable required"

Problem: Missing configuration Solution: Add SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY to environment

Error: "Permission denied"

Problem: Using anon key in backend Solution: Use service_role key for backend operations

Error: "Row Level Security policy violation"

Problem: Service role key not working Solution: Verify key is service_role, not anon key

✅ Migration Checklist

• requirements.txt updated with supabase>=2.0.0
• REST API service created (supabase_service_rest.py)
• Investigation service adapted (investigation_service_supabase_rest.py)
• Test script working (scripts/test_supabase_rest.py)
• Environment variables documented
• .env.example updated
• HuggingFace Spaces variables configured
• Code updated to use REST API imports
• Deployment tested on HuggingFace Spaces

🔗 Links

• Supabase Dashboard: https://app.supabase.com/project/pbsiyuattnwgohvkkkks
• API Settings: https://app.supabase.com/project/pbsiyuattnwgohvkkkks/settings/api
• Supabase Python Docs: https://supabase.com/docs/reference/python
• HuggingFace Space: https://huggingface.co/spaces/neural-thinker/cidadao.ai-backend

---

Author: Anderson H. Silva Date: 2025-10-07 Status: ✅ TESTED AND WORKING ON HUGGINGFACE SPACES