supabase-realtime

用途

Supabase Realtime 用于为应用添加实时能力，主要覆盖三类场景：数据库行变更订阅、客户端之间的消息广播，以及在线用户状态追踪。适合实现实时功能、实时更新、聊天或在线状态追踪。

主要能力

Postgres Changes（数据库订阅）

监听数据库表的行变更，支持 INSERT、UPDATE、DELETE 事件。

启用某张表的 Realtime：

-- 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);

订阅所有变更：

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()

可只订阅特定事件（INSERT、UPDATE 或 DELETE），也可按列值过滤，例如 filter: 'status=eq.published' 或 filter: user_id=eq.${userId}``。支持在同一频道上添加多个监听器，分别监听不同表。

Broadcast（客户端到客户端）

用于客户端之间的消息传递，例如聊天和通知。发送前需先订阅，订阅成功（状态为 SUBSCRIBED）后调用 channel.send 发送消息，接收方通过 .on('broadcast', { event: 'message' }, callback) 监听。

聊天示例中，使用频道 ID 作为房间，监听 new-message 事件并发送包含用户名、消息内容和时间戳的 payload。

Presence（在线用户）

用于追踪在线用户和输入状态指示。订阅成功后调用 channel.track 上报当前用户信息，通过 presence 事件的 sync、join、leave 监听状态变化，使用 channel.presenceState() 获取当前在线用户列表，调用 channel.untrack() 下线。

使用方式

提供 JavaScript 客户端 API 用法，并包含 React 模式示例：

数据库订阅 Hook：先做初始数据拉取，再订阅变更，根据 eventType 分别处理 INSERT、UPDATE、DELETE 更新本地状态，组件卸载时调用 supabase.removeChannel(channel) 清理。
Presence Hook：订阅 presence 的 sync 事件更新在线用户列表，订阅成功后 track 当前用户，卸载时 untrack 并移除频道。

订阅状态回调可获取 SUBSCRIBED、TIMED_OUT、CLOSED、CHANNEL_ERROR 等状态值。清理方式包括 supabase.removeChannel(channel) 移除单个频道和 supabase.removeAllChannels() 移除所有频道。

访问控制

Realtime 遵循 RLS 策略，用户只能看到其有权访问的变更。可为表创建 SELECT 策略控制实时可见范围。对于 broadcast 和 presence，可对 realtime.messages 使用 RLS 策略控制频道访问，例如使用 realtime.topic() 匹配频道主题。若需在 UPDATE/DELETE 时访问旧记录，需设置 ALTER TABLE posts REPLICA IDENTITY FULL;。

过滤操作符

支持 eq、neq、in 三种过滤操作符，例如 filter: 'status=eq.active'、filter: 'status=neq.deleted'、filter: 'status=in.(active,pending)'。注意：每个订阅仅支持 1 个过滤器。

适用场景

实时数据更新、聊天、通知、在线用户追踪、输入状态指示等需要实时交互的应用。

限制

每个订阅仅支持 1 个过滤器；UPDATE/DELETE 的旧记录访问需开启 REPLICA IDENTITY FULL；broadcast 和 presence 的授权需通过 realtime.messages 的 RLS 策略配置。