Supabase Realtime

Expert implementation guide for Supabase Realtime features focusing on scalable patterns and best practices.

Core Principles

Always use broadcast over postgres_changes – postgres_changes is single-threaded and doesn’t scale. Use broadcast with database triggers for all database change notifications.

Use dedicated topics – Never broadcast to global topics. Use granular patterns like room:123:messages, user:456:notifications.

Private channels by default – Set private: true for all database-triggered channels. Enable private-only mode in production.

Quick Reference

Naming Conventions

• Topics: scope:entity:id (e.g., room:123:messages)
• Events: entity_action in snake_case (e.g., message_created)

Client Setup Pattern

const channel = supabase.channel('room:123:messages', {
  config: { 
    broadcast: { self: true, ack: true },
    private: true  // Required for RLS
  }
})

// Set auth before subscribing
await supabase.realtime.setAuth()

channel
  .on('broadcast', { event: 'message_created' }, handler)
  .subscribe((status, err) => {
    if (status === 'SUBSCRIBED') console.log('Connected')
  })

// Cleanup
supabase.removeChannel(channel)

Database Trigger Pattern

-- Use realtime.broadcast_changes for database events
CREATE OR REPLACE FUNCTION notify_table_changes()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.broadcast_changes(
    TG_TABLE_NAME || ':' || COALESCE(NEW.id, OLD.id)::text,
    TG_OP,
    TG_OP,
    TG_TABLE_NAME,
    TG_TABLE_SCHEMA,
    NEW,
    OLD
  );
  RETURN COALESCE(NEW, OLD);
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER messages_broadcast_trigger
  AFTER INSERT OR UPDATE OR DELETE ON messages
  FOR EACH ROW EXECUTE FUNCTION notify_table_changes();

RLS Authorization

-- Required for private channels
CREATE POLICY "room_members_can_read" ON realtime.messages
FOR SELECT TO authenticated
USING (
  topic LIKE 'room:%' AND
  EXISTS (
    SELECT 1 FROM room_members
    WHERE user_id = auth.uid()
    AND room_id = SPLIT_PART(topic, ':', 2)::uuid
  )
);

-- Required index for performance
CREATE INDEX idx_room_members_user_room ON room_members(user_id, room_id);

Implementation Checklist

• ✅ Use broadcast not postgres_changes
• ✅ Dedicated topics per room/user/entity
• ✅ Set private: true for database triggers
• ✅ Create indexes for all RLS policy columns
• ✅ Include cleanup/unsubscribe logic
• ✅ Check channel state before subscribing
• ✅ Use consistent naming conventions

Scripts

• scripts/create_broadcast_trigger.sql – Generic broadcast trigger function
• scripts/migrate_from_postgres_changes.sql – Migration helper script

Advanced Topics

• Framework Integration: See references/framework_patterns.md
• Performance Optimization: See references/performance_scaling.md
• Migration Guide: See references/migration_guide.md