Supabase Integration Guide

Overview

Supabase is an open-source Firebase alternative built on PostgreSQL. It provides a complete backend platform with authentication, real-time features, and a powerful REST API.

Integration Type: PostgreSQL-based with REST API access
Authentication: JWT token-based
Protocol: HTTPS REST API
Database Type: PostgreSQL

Getting Started

Prerequisites:

A Supabase account (free or paid)
A Supabase project created
Access to your Supabase project dashboard

Steps to Create a Supabase Project:

Go to https://supabase.com
Sign in or create an account
Click "New Project"
Give your project a name
Create a strong password for the database
Select your region (choose closest to your location)
Click "Create new project" and wait for initialization (2-3 minutes)

Obtaining Credentials

You need 3 main credentials from Supabase:

A) Supabase URL (Project URL)

Location: Your Supabase Dashboard > Project Settings > API > Project URL
Format: https://xxxxxxxxxxxx.supabase.co

B) Anon Key (Anonymous/Public API Key)

Location: Your Supabase Dashboard > Project Settings > API > anon key
Note: This is a safe public key that can be shared in frontend code

C) Service Role Key (Private API Key)

Location: Your Supabase Dashboard > Project Settings > API > service_role key
⚠️ WARNING: Keep this secret! Never share this key!

Step-by-Step to Find Credentials:
1. Login to https://supabase.com
2. Click on your project
3. Go to Settings (bottom left sidebar menu)
4. Click "API" in the Settings menu
5. Copy the Project URL
6. Copy the Anon key
7. Copy the Service Role key

Configuration in Dashboard

Click "Add Project" or "New Project"
Fill in Project Details
- Name: Give your project a meaningful name
- Database Provider: Select "Supabase"
Fill in Supabase Credentials
- Supabase URL: Paste your project URL
- Anon Key: Paste your anon key
- Service Role Key: Paste your service role key
- Management API Key: (Optional)
Click "Test Connection" to verify credentials are correct
Select Theme Color (optional)
Click "Save Project"

Tellus Integration

Add your Supabase database to your Tellus configuration. In your tellus.config.js or within your initialized client instance, define the connection:

import { Tellus } from '@tellus/client';

const tellus = new Tellus({
  databases: {
    primary: {
      provider: 'supabase',
      url: process.env.SUPABASE_URL,
      key: process.env.SUPABASE_ANON_KEY
    }
  }
});

Basic Operations (CRUD)

With Tellus, querying Supabase is standardized. Below are examples of Create, Read, Update, and Delete operations using the unified Tellus API.

1. Create (Insert)

// Insert a new user into the 'users' table
const newUser = await tellus.db('primary').collection('users').insert({
  name: 'Jane Doe',
  email: 'jane@example.com',
  status: 'active'
});

2. Read (Select)

// Fetch active users with specific fields
const activeUsers = await tellus.db('primary').collection('users')
  .find({ status: 'active' })
  .select(['id', 'name', 'email'])
  .limit(10)
  .execute();

3. Update

// Update a specific user's status
await tellus.db('primary').collection('users')
  .where('email', '==', 'jane@example.com')
  .update({ status: 'inactive' });

4. Delete

// Remove a user
await tellus.db('primary').collection('users')
  .where('email', '==', 'jane@example.com')
  .delete();

Using Supabase in the Dashboard

Once connected, you can:

Browse Your Database Schema - View all tables, columns, and data types
Query Data - Execute custom SQL queries and view results
Manage Authentication - View and manage user accounts
Access Tables - Browse, filter, and manage records directly
View Real-time Subscriptions - Monitor active connections

Example Setup: Blog Database

Step 1: Create Tables

CREATE TABLE posts (
  id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
  title TEXT NOT NULL,
  content TEXT,
  author_id UUID REFERENCES auth.users(id),
  published BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE comments (
  id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
  post_id BIGINT REFERENCES posts(id) ON DELETE CASCADE,
  user_id UUID REFERENCES auth.users(id),
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Step 2: Setup Row Level Security

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
ALTER TABLE comments ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Anyone can read posts"
ON posts FOR SELECT USING (true);

Step 3: Add to Dashboard

Go to Dashboard > Add Project
Enter your Supabase credentials
Test connection
Navigate to your posts table to see the data!

Common Issues & Solutions

❌ "Invalid credentials" error

Verify you're using the correct Supabase project URL
Check that you copied the full anon key
Ensure project is fully initialized (wait 2-3 minutes)

❌ "Table not found" error

Check if the table exists in your Supabase database
Verify the table name spelling and case sensitivity
Make sure you have permissions

❌ Can't see data in dashboard

Check Row Level Security (RLS) policies
Verify the user has read permissions
Try disabling RLS temporarily to test

Security Best Practices

API Keys: Always use anon key for public operations. Use service role key ONLY in secure backend.
Row Level Security: Enable RLS on all sensitive tables.
Connection Strings: Don't commit credentials to version control.
Monitoring: Check Supabase logs for suspicious activity.
Rotation: Rotate credentials periodically if compromised.