adaptationio/supabase-realtime

Supabase Realtime Skill

Live subscriptions, broadcasts, and presence.

Quick Reference

| Feature | Use Case | |---------|----------| | Postgres Changes | Database row changes (INSERT, UPDATE, DELETE) | | Broadcast | Client-to-client messaging (chat, notifications) | | Presence | Track online users, typing indicators |

Postgres Changes (Database Subscriptions)

Enable Realtime on Table

-- Enable realtime for a table
ALTER PUBLICATION supabase_realtime ADD TABLE posts;

-- Enable for specific columns only
ALTER PUBLICATION supabase_realtime ADD TABLE posts (id, title, status);

Subscribe to All Changes

const channel = supabase
  .channel('posts-changes')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'posts' },
    (payload) => {
      console.log('Change:', payload)
      // payload.eventType: 'INSERT' | 'UPDATE' | 'DELETE'
      // payload.new: new row data
      // payload.old: previous row data (UPDATE/DELETE only)
    }
  )
  .subscribe()

Subscribe to Specific Events

// INSERT only
const channel = supabase
  .channel('new-posts')
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'posts' },
    (payload) => console.log('New post:', payload.new)
  )
  .subscribe()

// UPDATE only
const channel = supabase
  .channel('updated-posts')
  .on(
    'postgres_changes',
    { event: 'UPDATE', schema: 'public', table: 'posts' },
    (payload) => console.log('Updated:', payload.old, '->', payload.new)
  )
  .subscribe()

// DELETE only
const channel = supabase
  .channel('deleted-posts')
  .on(
    'postgres_changes',
    { event: 'DELETE', schema: 'public', table: 'posts' },
    (payload) => console.log('Deleted:', payload.old)
  )
  .subscribe()

Filter by Column Value

// Only changes where status = 'published'
const channel = supabase
  .channel('published-posts')
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
      table: 'posts',
      filter: 'status=eq.published'
    },
    (payload) => console.log('Published post change:', payload)
  )
  .subscribe()

// Filter by user_id
const channel = supabase
  .channel('user-posts')
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
      table: 'posts',
      filter: `user_id=eq.${userId}`
    },
    (payload) => console.log('User post change:', payload)
  )
  .subscribe()

Multiple Listeners

const channel = supabase
  .channel('all-changes')
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'posts' },
    (payload) => console.log('New post:', payload.new)
  )
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'comments' },
    (payload) => console.log('New comment:', payload.new)
  )
  .subscribe()

Broadcast (Client-to-Client)

Send Broadcast

const channel = supabase.channel('room-1')

// Subscribe first
channel.subscribe((status) => {
  if (status === 'SUBSCRIBED') {
    // Send message
    channel.send({
      type: 'broadcast',
      event: 'message',
      payload: { text: 'Hello everyone!' }
    })
  }
})

Receive Broadcast

const channel = supabase
  .channel('room-1')
  .on('broadcast', { event: 'message' }, (payload) => {
    console.log('Received:', payload.payload)
  })
  .subscribe()

Chat Example

const roomId = 'chat-room-123'
const channel = supabase.channel(roomId)

// Listen for messages
channel
  .on('broadcast', { event: 'new-message' }, ({ payload }) => {
    console.log(`${payload.username}: ${payload.message}`)
  })
  .subscribe()

// Send message function
function sendMessage(username, message) {
  channel.send({
    type: 'broadcast',
    event: 'new-message',
    payload: { username, message, timestamp: new Date().toISOString() }
  })
}

Presence (Online Users)

Track User Presence

const channel = supabase.channel('online-users')

// Track current user
channel.subscribe(async (status) => {
  if (status === 'SUBSCRIBED') {
    await channel.track({
      user_id: currentUser.id,
      username: currentUser.name,
      online_at: new Date().toISOString()
    })
  }
})

Listen for Presence Changes

const channel = supabase
  .channel('online-users')
  .on('presence', { event: 'sync' }, () => {
    // Get all online users
    const state = channel.presenceState()
    console.log('Online users:', state)
  })
  .on('presence', { event: 'join' }, ({ key, newPresences }) => {
    console.log('User joined:', newPresences)
  })
  .on('presence', { event: 'leave' }, ({ key, leftPresences }) => {
    console.log('User left:', leftPresences)
  })
  .subscribe()

Get Online Users

// After subscribing
const state = channel.presenceState()

// state is an object keyed by user key
// { "user-123": [{ user_id: "...", username: "...", online_at: "..." }] }

const onlineUsers = Object.values(state).flat()
console.log('Online count:', onlineUsers.length)

Untrack (Go Offline)

await channel.untrack()

React Patterns

Database Subscription Hook

import { useEffect, useState } from 'react'

function usePosts() {
  const [posts, setPosts] = useState([])

  useEffect(() => {
    // Initial fetch
    supabase.from('posts').select('*').then(({ data }) => {
      setPosts(data || [])
    })

    // Subscribe to changes
    const channel = supabase
      .channel('posts-realtime')
      .on(
        'postgres_changes',
        { event: '*', schema: 'public', table: 'posts' },
        (payload) => {
          if (payload.eventType === 'INSERT') {
            setPosts(prev => [...prev, payload.new])
          } else if (payload.eventType === 'UPDATE') {
            setPosts(prev =>
              prev.map(post =>
                post.id === payload.new.id ? payload.new : post
              )
            )
          } else if (payload.eventType === 'DELETE') {
            setPosts(prev =>
              prev.filter(post => post.id !== payload.old.id)
            )
          }
        }
      )
      .subscribe()

    return () => {
      supabase.removeChannel(channel)
    }
  }, [])

  return posts
}

Presence Hook

import { useEffect, useState } from 'react'

function useOnlineUsers(roomId) {
  const [onlineUsers, setOnlineUsers] = useState([])

  useEffect(() => {
    const channel = supabase
      .channel(`room-${roomId}`)
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState()
        setOnlineUsers(Object.values(state).flat())
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          await channel.track({
            user_id: currentUser.id,
            username: currentUser.name
          })
        }
      })

    return () => {
      channel.untrack()
      supabase.removeChannel(channel)
    }
  }, [roomId])

  return onlineUsers
}

Subscription Status

const channel = supabase
  .channel('my-channel')
  .on('postgres_changes', { ... }, callback)
  .subscribe((status, err) => {
    if (status === 'SUBSCRIBED') {
      console.log('Connected!')
    } else if (status === 'CLOSED') {
      console.log('Disconnected')
    } else if (status === 'CHANNEL_ERROR') {
      console.error('Error:', err)
    }
  })

Status Values

• SUBSCRIBED - Successfully connected
• TIMED_OUT - Connection timed out
• CLOSED - Channel closed
• CHANNEL_ERROR - Error occurred

Cleanup

Remove Single Channel

await supabase.removeChannel(channel)

Remove All Channels

await supabase.removeAllChannels()

Access Control

Enable RLS for Realtime

Realtime respects RLS policies. Users only see changes they have access to.

-- Policy for realtime
CREATE POLICY "Users see own posts realtime"
ON posts FOR SELECT
TO authenticated
USING (auth.uid() = user_id);

Broadcast Authorization

For broadcast and presence, use RLS on realtime.messages:

-- Create policy for channel access
CREATE POLICY "Channel access"
ON realtime.messages
FOR ALL
TO authenticated
USING (
  realtime.topic() LIKE 'room-' || auth.uid()::text || '%'
);

Old Record Access (REPLICA IDENTITY)

To access old record on UPDATE/DELETE:

-- Enable full replica identity
ALTER TABLE posts REPLICA IDENTITY FULL;

Filter Operators

| Operator | Example | |----------|---------| | eq | filter: 'status=eq.active' | | neq | filter: 'status=neq.deleted' | | in | filter: 'status=in.(active,pending)' |

Note: Only 1 filter per subscription is supported.

References

• realtime-patterns.md - Common patterns