Supabase Setup

This guide will help you set up Supabase as the backend database for Highway, storing verification data and call records.

Prerequisites

A Supabase account
Basic understanding of PostgreSQL
Access to create and manage database tables

Creating a Supabase Project

Go to supabase.com and create an account or sign in.

Create a new project

Click New Project and provide:

Project name: Choose a descriptive name (e.g., “highway-production”)
Database password: Create a strong password (save this securely)
Region: Select the closest region to your users

Wait for provisioning

Supabase will set up your database. This typically takes 1-2 minutes.

Getting API Keys

Once your project is ready, you’ll need two API keys:

Navigate to Project Settings

Click on the Settings icon in the left sidebar, then select API.

Copy the Project URL

Find your Project URL (e.g., https://xxxxx.supabase.co). You’ll need this for the client configuration.

Get the anon key

Copy the anon (public) key. This key is safe to use in frontend applications with Row Level Security enabled.

Get the service_role key

Copy the service_role key. This key bypasses Row Level Security and should only be used server-side.

The service_role key has full database access. Never expose it in client-side code or commit it to version control.

Environment Configuration

Add your Supabase credentials to .env:

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

Database Tables Setup

Highway requires two main tables: verifications and calls.

Verifications Table

Stores customer verification data:

Open SQL Editor

Navigate to SQL Editor in the Supabase dashboard.

Create verifications table

Run the following SQL:

CREATE TABLE verifications (
  id SERIAL PRIMARY KEY,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc', NOW()),
  customer_name TEXT,
  phone_number TEXT,
  verification_data JSONB,
  status TEXT DEFAULT 'pending'
);

Add indexes

Optimize query performance:

CREATE INDEX idx_verifications_phone ON verifications(phone_number);
CREATE INDEX idx_verifications_status ON verifications(status);

Calls Table

Tracks call history and status:

Create calls table

Run this SQL in the SQL Editor:

CREATE TABLE calls (
  id SERIAL PRIMARY KEY,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc', NOW()),
  verification INTEGER REFERENCES verifications(id),
  status TEXT DEFAULT 'in_progress',
  call_sid TEXT,
  duration INTEGER,
  recording_url TEXT,
  transcription TEXT,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc', NOW())
);

Add indexes and constraints

CREATE INDEX idx_calls_verification ON calls(verification);
CREATE INDEX idx_calls_status ON calls(status);
CREATE INDEX idx_calls_created ON calls(created_at DESC);

Table Schemas and Relationships

Verifications Schema

Column	Type	Description
`id`	SERIAL	Primary key, auto-incrementing
`created_at`	TIMESTAMP	Record creation timestamp
`customer_name`	TEXT	Customer’s name
`phone_number`	TEXT	Customer’s phone number
`verification_data`	JSONB	Flexible data storage for verification info
`status`	TEXT	Verification status (pending, completed, failed)

Calls Schema

Column	Type	Description
`id`	SERIAL	Primary key, auto-incrementing
`created_at`	TIMESTAMP	Call creation timestamp
`verification`	INTEGER	Foreign key to verifications table
`status`	TEXT	Call status (in_progress, successful_call, etc.)
`call_sid`	TEXT	Twilio call SID
`duration`	INTEGER	Call duration in seconds
`recording_url`	TEXT	URL to call recording
`transcription`	TEXT	Call transcription text
`updated_at`	TIMESTAMP	Last update timestamp

Relationship Diagram

verifications (1) ─── (many) calls
    ↑                      ↑
    └─ id            verification (FK)

The verification column in the calls table creates a one-to-many relationship, allowing multiple call attempts per verification.

Row Level Security (RLS) Policies

Enable RLS to secure your data:

Enable RLS on tables

ALTER TABLE verifications ENABLE ROW LEVEL SECURITY;
ALTER TABLE calls ENABLE ROW LEVEL SECURITY;

Create policies for verifications

Allow authenticated users to read their own verifications:

CREATE POLICY "Enable read access for authenticated users"
ON verifications
FOR SELECT
TO authenticated
USING (true);

CREATE POLICY "Enable insert for authenticated users"
ON verifications
FOR INSERT
TO authenticated
WITH CHECK (true);

Create policies for calls

CREATE POLICY "Enable read access for authenticated users"
ON calls
FOR SELECT
TO authenticated
USING (true);

CREATE POLICY "Enable insert for authenticated users"
ON calls
FOR INSERT
TO authenticated
WITH CHECK (true);

CREATE POLICY "Enable update for authenticated users"
ON calls
FOR UPDATE
TO authenticated
USING (true)
WITH CHECK (true);

These are basic RLS policies. In production, you should implement more granular policies based on user roles and ownership.

Client Configuration

Backend Configuration

Highway’s backend uses the Supabase client for server-side operations:

routes.js

const { createClient } = require("@supabase/supabase-js");

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);

Using the Client

Creating a call record:

routes.js

const { data } = await supabase
  .from("calls")
  .insert([{ verification: verification, status: "in_progress" }])
  .select();

Fetching verification data:

websocket.js

const { data, error } = await supabase
  .from("verifications")
  .select("*")
  .eq("id", streamId);

Updating call status:

websocket.js

await supabase
  .from("calls")
  .update({ status: response.arguments.status })
  .eq("id", callId);

Frontend Configuration (Optional)

If you have a frontend dashboard, use the anon key:

import { createClient } from '@supabase/supabase-js'

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

Frontend environment variables should be prefixed with NEXT_PUBLIC_ (Next.js) or VITE_ (Vite) to expose them to the client.

Testing Database Operations

Install Supabase client

npm install @supabase/supabase-js

Test connection

Create a test script:

const { createClient } = require('@supabase/supabase-js');

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);

async function testConnection() {
  const { data, error } = await supabase
    .from('verifications')
    .select('count');
  
  if (error) {
    console.error('Error:', error);
  } else {
    console.log('Connection successful!', data);
  }
}

testConnection();

Run the test

node test-supabase.js

Database Monitoring

View table data

Navigate to Table Editor in Supabase to view and edit data directly.

Check logs

Go to Logs > Database to monitor queries and errors.

Monitor performance

Use Reports to track database performance and query patterns.

Best Practices

Security

Use RLS policies: Always enable Row Level Security
Separate keys: Use anon_key for frontend, service_role for backend only
Validate inputs: Sanitize data before inserting into the database
Rotate keys: Regularly rotate API keys for security

Performance

Add indexes: Index frequently queried columns
Use select(): Only fetch columns you need
Batch operations: Use bulk inserts when possible
Monitor queries: Check slow queries in Supabase logs

Data Management

Backup regularly: Enable automated backups in project settings
Clean old data: Archive or delete old call records
Use JSONB wisely: Store flexible data in verification_data
Add timestamps: Track created_at and updated_at for all records

Troubleshooting

Common Issues

Connection errors

Verify your Supabase URL and API keys are correct
Check that your project is not paused (free tier limitation)
Ensure network allows connections to Supabase

RLS blocking queries

Check RLS policies are configured correctly
Verify user authentication status
Use service_role key for server-side operations that need full access

Insert/Update failures

Validate data types match table schema
Check foreign key constraints
Review RLS policies for INSERT/UPDATE permissions

Slow queries

Add indexes on frequently queried columns
Limit result sets with .limit()
Use .select('column1, column2') instead of .select('*')

Next Steps

Configure Twilio for phone integration
Set up OpenAI for AI processing
Learn about Environment Variables

Getting Started

Core Features

Setup & Configuration

Integration Guides

Prerequisites

Creating a Supabase Project

Getting API Keys

Environment Configuration

Database Tables Setup

Verifications Table

Calls Table

Table Schemas and Relationships

Verifications Schema

Calls Schema

Relationship Diagram

Row Level Security (RLS) Policies

Client Configuration

Backend Configuration

Using the Client

Frontend Configuration (Optional)

Testing Database Operations

Database Monitoring

Best Practices

Security

Performance

Data Management

Troubleshooting

Common Issues

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Features

Setup & Configuration

Integration Guides

​Prerequisites

​Creating a Supabase Project

​Getting API Keys

​Environment Configuration

​Database Tables Setup

​Verifications Table

​Calls Table

​Table Schemas and Relationships

​Verifications Schema

​Calls Schema

​Relationship Diagram

​Row Level Security (RLS) Policies

​Client Configuration

​Backend Configuration

​Using the Client

​Frontend Configuration (Optional)

​Testing Database Operations

​Database Monitoring

​Best Practices

​Security

​Performance

​Data Management

​Troubleshooting

​Common Issues

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Creating a Supabase Project

Getting API Keys

Environment Configuration

Database Tables Setup

Verifications Table

Calls Table

Table Schemas and Relationships

Verifications Schema

Calls Schema

Relationship Diagram

Row Level Security (RLS) Policies

Client Configuration

Backend Configuration

Using the Client

Frontend Configuration (Optional)

Testing Database Operations

Database Monitoring

Best Practices

Security

Performance

Data Management

Troubleshooting

Common Issues

Next Steps