Docs: Conflicting Descriptions Of The Private Flag For Realtime.Send / Realtime.Send_binary
The Supabase Realtime broadcast documentation contains contradictory inline comments for the `private` parameter in SQL examples. Two of three examples reverse the meaning of `true` and `false`, and none explain what the boolean actually does. This can lead developers to accidentally send messages to the wrong channel type (public vs private), causing authorization bypass or unexpected visibility. The underlying SQL functions define `private => true` as private channel (default) and `false` as public channel.
The documentation examples for `realtime.send` and `realtime.send_binary` use inconsistent and partially reversed labels for the `private` argument. The SQL function signature clearly states `private boolean default true`, meaning `true` corresponds to a private channel and `false` to a public channel. However, the inline comments mislabel the values, leading to misinterpretation.
1. Visit the Supabase Realtime broadcast documentation page (https://supabase.com/docs/guides/realtime/broadcast#broadcast-from-the-database).
2. Observe the three SQL examples: `realtime.send` example labels `false` as 'Public / Private flag'; `realtime.send_binary` example labels `true` as 'Private / Public flag (defaults to true)'; the 'Broadcasting from your database' section labels `FALSE` as 'Public / Private flag'.
3. Compare with the actual SQL function definition (e.g., `create or replace function realtime.send(..., private boolean default true)`).
4. Note the contradiction and missing explanation of what `true` and `false` do.
Fixing Code Block
-- Corrected realtime.send example using named notation and explicit description
select realtime.send(
payload => jsonb_build_object('hello', 'world'),
event => 'event',
topic => 'topic',
private => true -- true = private channel (default), false = public channel
);
-- Corrected realtime.send_binary example
select realtime.send_binary(
payload => convert_to('hello', 'UTF8'),
event => 'event',
topic => 'topic',
private => false -- true = private channel (default), false = public channel
);
-- Note: The `private` flag determines who can subscribe to the topic.
-- Setting `private => true` (default) restricts the channel to authorized subscribers,
-- while `private => false` makes it publicly subscribable.
The fix unifies the inline comments across all examples to accurately describe the `private` parameter: `true` means private channel (default), `false` means public channel. It also adopts named notation (`payload =>`, `event =>`, `topic =>`, `private =>`) to make the call self-documenting and reduces the chance of positional errors. The examples now explicitly show the default `true` for `realtime.send` and demonstrate both `true` and `false` cases.
Edge Case Audit
This is a documentation-only change; no runtime code is altered. However, developers who previously followed the incorrect comments may have inadvertently used the wrong boolean value. Recommend auditing existing `realtime.send` and `realtime.send_binary` calls in production to ensure `private` is set as intended. When rolling back this documentation update, ensure all related pages (broadcast guide, API references) are reverted consistently to avoid re-introducing contradictions. No multi-threading, concurrency, or cross-platform issues apply.
