supabase.realtime — io.github.supabase-community/realtime 1.3.0

Public API for Supabase Realtime: WebSocket-based postgres_changes, broadcast, and presence subscriptions.

Quick start

(require '[supabase.core.client :as sc]
         '[supabase.realtime :as rt])

(def client (sc/make-client "https://abc.supabase.co" "anon-key"))
(def conn   (rt/connect client {:on-error println}))

(def ch (rt/channel conn "room:lobby"
                    {:config {:broadcast {:self false}}}))

(rt/on ch :postgres-changes
       {:event :insert :schema "public" :table "users"}
       (fn [payload] (println "row" payload)))

(rt/on ch :broadcast {:event "typing"}
       (fn [payload] (println "typing" payload)))

(rt/subscribe ch)
(rt/broadcast ch "typing" {:user "alice"})
(rt/track    ch {:online_at (System/currentTimeMillis)})

(rt/unsubscribe ch)
(rt/disconnect conn)

v0.1.0 scope

In: postgres_changes, broadcast send/receive, basic presence, manual set-auth, heartbeat, multi-channel per connection.

Out (deferred): broadcast ack/wait_for_ack, HTTP fallback, binary v2 protocol.

broadcast clj

(broadcast ch event payload)

Sends a broadcast message on ch. Buffered until the channel joins. Returns ch.

When the connection was opened with :http-fallback? true and the socket is not :open, the broadcast is sent over HTTP POST to /api/broadcast instead of buffering — mirrors realtime-ex. In that case returns ch on HTTP success, or the anomaly from the failed request. Broadcasts sent via broadcast-with-ack never fall back; they buffer like today.

broadcast-with-ack clj

(broadcast-with-ack ch event payload)

Sends a broadcast and returns the ack-ref (string) identifying it. The server replies with a phx_reply carrying that ref once the broadcast is accepted — requires :config {:broadcast {:ack true}} on the channel.

(let [ack (rt/broadcast-with-ack ch "typing" {:user "a"})]
  (rt/wait-for-ack ch ack {:timeout-ms 3000}))

Buffered like broadcast until the channel joins.

build clj

channel clj

(channel conn topic)

(channel conn topic opts)

Returns a channel value bound to conn + topic. No network I/O.

opts may include :config (broadcast/presence/private). The channel is registered in connection state so subsequent on / subscribe calls can find it. Returns the channel map or an anomaly.

connect clj

(connect client)

(connect client opts)

Opens a Realtime connection for client. See supabase.realtime.connection/connect for options.

disconnect clj

(disconnect c)

Closes the connection. Idempotent.

eq clj

gt clj

gte clj

ilike clj

imatch clj

in clj

is clj

isdistinct clj

like clj

lt clj

lte clj

match clj

neq clj

not clj

on clj

(on ch binding-type filter callback)

Registers a binding on ch. Returns the channel value (for threading) or an anomaly on validation failure.

Binding types: :postgres-changes — filter {:event :insert/:update/:delete/:all :schema "public" :table "users" :filter "id=eq.42" (optional) :select ["id" "email"] (optional)} :broadcast — filter {:event "typing"} (use "*" for all) :presence — filter {:event :sync | :join | :leave}

The postgres_changes :filter also accepts a builder from supabase.realtime.filters — it is serialized to its wire string at registration time:

(rt/on ch :postgres-changes
       {:event :update :schema "public" :table "orders"
        :filter (-> (f/gt "amount" 100) (f/eq "status" "open"))}
       handle-order)

:select narrows the payload to the listed columns (the primary key always comes through). Registering the same postgres_changes filter twice is a no-op (the duplicate is dropped and the connection's :on-error is notified with a :duplicate-binding anomaly): the server collapses identical filters into one subscription, so keeping the duplicate would desync client and server binding lists and fail subscribe with a mismatch.

Must be called BEFORE subscribe for postgres_changes — server-side binding ids are correlated at join time.

presence-state clj

(presence-state ch)

Returns the latest presence map captured for ch. Empty if no presence_state received yet.

set-auth clj

(set-auth ch-or-conn token)

Refreshes the auth token for a channel or every joined channel on a connection. Sends an access_token event per joined channel.

The token is recorded on the connection and resolved into subsequent join/rejoin payloads (unless an :access-token-fn is set — its result always wins). Pass nil to clear it on sign-out, so a stale token no longer leaks into later join payloads.

subscribe clj

(subscribe ch)

Sends phx_join for ch and transitions to :joining. The channel receives :joined asynchronously when the server replies. Returns ch.

track clj

(track ch state)

Sends a presence track message with state. Returns ch.

unsubscribe clj

(unsubscribe ch)

Sends phx_leave and transitions to :leaving. Channel state is removed when the server acks.

untrack clj

(untrack ch)

Sends a presence untrack message. Returns ch.

wait-for-ack clj

(wait-for-ack ch ack-ref)

(wait-for-ack ch ack-ref {:keys [timeout-ms] :or {timeout-ms 5000}})

Blocks up to timeout-ms (default 5000) for the server ack of ack-ref from broadcast-with-ack. Returns :acknowledged, or an anomaly: :ack-timeout when the wait expires, :ack-not-found for an unknown ref.