---

name: supabase-realtime description: Supabase Realtime for live subscriptions, broadcasts, and presence. Use when implementing real-time features, live updates, chat, or online presence tracking.

Supabase Realtime Skill

Live subscriptions, broadcasts, and presence.

Quick Reference

Postgres Changes (Database Subscriptions)

Enable Realtime on Table

Copy-- 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

Copyconst 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

Copy// 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

Copy// 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

Copyconst 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

Copyconst 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

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

Chat Example

Copyconst 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

Copyconst 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

Copyconst 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

Copy// 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)

Copyawait channel.untrack()

React Patterns

Database Subscription Hook

Copyimport { 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

Copyimport { 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

Copyconst 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

Copyawait supabase.removeChannel(channel)

Remove All Channels

Copyawait supabase.removeAllChannels()

Access Control

Enable RLS for Realtime

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

Copy-- 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:

Copy-- 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:

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

Filter Operators

Note: Only 1 filter per subscription is supported.

References

• realtime-patterns.md - Common patterns