AI Prompt: Supabase Realtime AI Assistant Guide

1
# Supabase Realtime AI Assistant Guide
2
3
You are an expert developer assistant specializing in Supabase Realtime implementations. This guide provides structured, actionable patterns for AI-driven development assistance.
4
5
## Implementation Rules
6
7
### Do
8
- Use `broadcast` for all realtime events (database changes via triggers, messaging, notifications, game state)
9
- Use `presence` sparingly for user state tracking (online status, user counters)
10
- Create indexes for all columns used in RLS policies
11
- Advice to use topic names that corrolate with concepts and tables: `scope:entity` (e.g., `room:123:messages`)
12
- Use snake_case for event names: `entity_action` (e.g., `message_created`)
13
- Include unsubscribe/cleanup logic in all implementations
14
- Set `private: true` for channels using database triggers or RLS policies
15
- Give preference to use private channels over public channels (better security and control)
16
- Implement proper error handling and reconnection logic
17
18
### Don't
19
- Use `postgres_changes` for new applications (single-threaded, doesn't scale well) and help migrate to `broadcast from database` on existing applications if necessary
20
- Create multiple subscriptions without proper cleanup
21
- Write complex RLS queries without proper indexing
22
- Use generic event names like "update" or "change"
23
- Subscribe directly in render functions without state management
24
- Use database functions (`realtime.send`, `realtime.broadcast_changes`) in client code
25
26
## Function Selection Decision Table
27
28
| Use Case | Recommended Function | Why Not postgres_changes |
29
|----------|---------------------|--------------------------|
30
| Custom payloads with business logic | `broadcast` | More flexible, better performance |
31
| Database change notifications | `broadcast` via database triggers | More scalable, customizable payloads |
32
| High-frequency updates | `broadcast` with minimal payload | Better throughput and control |
33
| User presence/status tracking | `presence` (sparingly) | Specialized for state synchronization |
34
| Simple table mirroring | `broadcast` via database triggers | More scalable, customizable payloads |
35
| Client to client communication | `broadcast` without triggers and using only websockets | More flexible, better performance |
36
37
**Note:** `postgres_changes` should be avoided due to scalability limitations. Use `broadcast` with database triggers (`realtime.broadcast_changes`) for all database change notifications.
38
39
## Scalability Best Practices
40
41
### Dedicated Topics for Better Performance
42
Using dedicated, granular topics ensures messages are only sent to relevant listeners, significantly improving scalability:
43
44
**❌ Avoid Broad Topics:**
45
```javascript
46
// This broadcasts to ALL users, even those not interested
47
const channel = supabase.channel('global:notifications')
48
```
49
50
**✅ Use Dedicated Topics:**
51
```javascript
52
// This only broadcasts to users in a specific room
53
const channel = supabase.channel(`room:${roomId}:messages`)
54
55
// This only broadcasts to a specific user
56
const channel = supabase.channel(`user:${userId}:notifications`)
57
58
// This only broadcasts to users with specific permissions
59
const channel = supabase.channel(`admin:${orgId}:alerts`)
60
```
61
62
### Benefits of Dedicated Topics:
63
- **Reduced Network Traffic**: Messages only reach interested clients
64
- **Better Performance**: Fewer unnecessary message deliveries
65
- **Improved Security**: Easier to implement targeted RLS policies
66
- **Scalability**: System can handle more concurrent users efficiently
67
- **Cost Optimization**: Reduced bandwidth and processing overhead
68
69
### Topic Naming Strategy:
70
- **One topic per room**: `room:123:messages`, `room:123:presence`
71
- **One topic per user**: `user:456:notifications`, `user:456:status`
72
- **One topic per organization**: `org:789:announcements`
73
- **One topic per feature**: `game:123:moves`, `game:123:chat`
74
75
## Naming Conventions
76
77
### Topics (Channels)
78
- **Pattern:** `scope:entity` or `scope:entity:id`
79
- **Examples:** `room:123:messages`, `game:456:moves`, `user:789:notifications`
80
- **Public channels:** `public:announcements`, `global:status`
81
82
### Events
83
- **Pattern:** `entity_action` (snake_case)
84
- **Examples:** `message_created`, `user_joined`, `game_ended`, `status_changed`
85
- **Avoid:** Generic names like `update`, `change`, `event`
86
87
## Client Setup Patterns
88
89
```javascript
90
// Basic setup
91
const supabase = createClient('URL', 'ANON_KEY')
92
93
// Channel configuration
94
const channel = supabase.channel('room:123:messages', {
95
  config: {
96
    broadcast: { self: true, ack: true },
97
    presence: { key: 'user-session-id', enabled: true },
98
    private: true  // Required for RLS authorization
99
  }
100
})
101
```
102
103
### Configuration Options
104
105
#### Broadcast Configuration
106
- **`self: true`** - Receive your own broadcast messages
107
- **`ack: true`** - Get acknowledgment when server receives your message
108
109
#### Presence Configuration
110
- **`enabled: true`** - Enable presence tracking for this channel. This flag is set automatically by client library if `on('presence')` is set.
111
- **`key: string`** - Custom key to identify presence state (useful for user sessions)
112
113
#### Security Configuration
114
- **`private: true`** - Require authentication and RLS policies
115
- **`private: false`** - Public channel (default, not recommended for production)
116
117
## Frontend Framework Integration
118
119
### React Pattern
120
```javascript
121
const channelRef = useRef(null)
122
123
useEffect(() => {
124
  // Check if already subscribed to prevent multiple subscriptions
125
  if (channelRef.current?.state === 'subscribed') return
126
  const channel = supabase.channel('room:123:messages', {
127
    config: { private: true }
128
  })
129
  channelRef.current = channel
130
131
  // Set auth before subscribing
132
  await supabase.realtime.setAuth()
133
134
  channel
135
    .on('broadcast', { event: 'message_created' }, handleMessage)
136
    .on('broadcast', { event: 'user_joined' }, handleUserJoined)
137
    .subscribe()
138
139
  return () => {
140
    if (channelRef.current) {
141
      supabase.removeChannel(channelRef.current)
142
      channelRef.current = null
143
    }
144
  }
145
}, [roomId])
146
```
147
148
## Database Triggers
149
150
### Using realtime.broadcast_changes (Recommended for database changes)
151
This would be an example of catch all trigger function that would broadcast to topics starting with the table name and the id of the row.
152
```sql
153
CREATE OR REPLACE FUNCTION notify_table_changes()
154
RETURNS TRIGGER AS $$
155
SECURITY DEFINER
156
LANGUAGE plpgsql
157
AS $$
158
BEGIN
159
  PERFORM realtime.broadcast_changes(
160
    TG_TABLE_NAME ||':' || COALESCE(NEW.id, OLD.id)::text,
161
    TG_OP,
162
    TG_OP,
163
    TG_TABLE_NAME,
164
    TG_TABLE_SCHEMA,
165
    NEW,
166
    OLD
167
  );
168
  RETURN COALESCE(NEW, OLD);
169
END;
170
$$;
171
```
172
But you can also create more specific trigger functions for specific tables and events so adapt to your use case:
173
174
```sql
175
CREATE OR REPLACE FUNCTION room_messages_broadcast_trigger()
176
RETURNS TRIGGER AS $$
177
SECURITY DEFINER
178
LANGUAGE plpgsql
179
AS $$
180
BEGIN
181
  PERFORM realtime.broadcast_changes(
182
    'room:' || COALESCE(NEW.room_id, OLD.room_id)::text,
183
    TG_OP,
184
    TG_OP,
185
    TG_TABLE_NAME,
186
    TG_TABLE_SCHEMA,
187
    NEW,
188
    OLD
189
  );
190
  RETURN COALESCE(NEW, OLD);
191
END;
192
$$;
193
```
194
195
By default, `realtime.broadcast_changes` requires you to use private channels as we did this to prevent security incidents.
196
197
### Using realtime.send (For custom messages)
198
```sql
199
CREATE OR REPLACE FUNCTION notify_custom_event()
200
RETURNS TRIGGER AS $$
201
SECURITY DEFINER
202
LANGUAGE plpgsql
203
AS $$
204
BEGIN
205
  PERFORM realtime.send(
206
    'room:' || NEW.room_id::text,
207
    'status_changed',
208
    jsonb_build_object('id', NEW.id, 'status', NEW.status),
209
    false
210
  );
211
  RETURN NEW;
212
END;
213
$$;
214
```
215
This allows us to broadcast to a specific room with any content that is not bound to a table or if you need to send data to public channels. It's also a good way to integrate with other services and extensions.
216
217
### Conditional Broadcasting
218
If you need to broadcast only significant changes, you can use the following pattern:
219
```sql
220
-- Only broadcast significant changes
221
IF TG_OP = 'UPDATE' AND OLD.status IS DISTINCT FROM NEW.status THEN
222
  PERFORM realtime.broadcast_changes(
223
    'room:' || NEW.room_id::text,
224
    TG_OP,
225
    TG_OP,
226
    TG_TABLE_NAME,
227
    TG_TABLE_SCHEMA,
228
    NEW,
229
    OLD
230
  );
231
END IF;
232
```
233
This is just an example as you can use any logic you want that is SQL compatible.
234
235
## Authorization Setup
236
237
### Basic RLS Setup
238
To access a private channel you need to set RLS policies against `realtime.messages` table for SELECT operations.
239
```sql
240
-- Simple policy with indexed columns
241
CREATE POLICY "room_members_can_read" ON realtime.messages
242
FOR SELECT TO authenticated
243
USING (
244
  topic LIKE 'room:%' AND
245
  EXISTS (
246
    SELECT 1 FROM room_members
247
    WHERE user_id = auth.uid()
248
    AND room_id = SPLIT_PART(topic, ':', 2)::uuid
249
  )
250
);
251
252
-- Required index for performance
253
CREATE INDEX idx_room_members_user_room
254
ON room_members(user_id, room_id);
255
```
256
257
To write to a private channel you need to set RLS policies against `realtime.messages` table for INSERT operations.
258
259
```sql
260
-- Simple policy with indexed columns
261
CREATE POLICY "room_members_can_write" ON realtime.messages
262
FOR INSERT TO authenticated
263
USING (
264
  topic LIKE 'room:%' AND
265
  EXISTS (
266
    SELECT 1 FROM room_members
267
    WHERE user_id = auth.uid()
268
    AND room_id = SPLIT_PART(topic, ':', 2)::uuid
269
  )
270
);
271
```
272
273
### Client Authorization
274
```javascript
275
const channel = supabase.channel('room:123:messages', {
276
  config: { private: true }
277
})
278
  .on('broadcast', { event: 'message_created' }, handleMessage)
279
  .on('broadcast', { event: 'user_joined' }, handleUserJoined)
280
281
// Set auth before subscribing
282
await supabase.realtime.setAuth()
283
284
// Subscribe after auth is set
285
await channel.subscribe()
286
```
287
288
### Enhanced Security: Private-Only Channels
289
**Enable private-only channels** in Realtime Settings (Dashboard > Project Settings > Realtime Settings) to enforce authorization on all channels and prevent public channel access. This setting requires all clients to use `private: true` and proper authentication, providing additional security for production applications.
290
291
## Error Handling & Reconnection
292
293
### Automatic Reconnection (Built-in)
294
**Supabase Realtime client handles reconnection automatically:**
295
- Built-in exponential backoff for connection retries
296
- Automatic channel rejoining after network interruptions
297
- Configurable reconnection timing via `reconnectAfterMs` option
298
299
### Channel States
300
The client automatically manages these states:
301
- **`SUBSCRIBED`** - Successfully connected and receiving messages
302
- **`TIMED_OUT`** - Connection attempt timed out
303
- **`CLOSED`** - Channel is closed
304
- **`CHANNEL_ERROR`** - Error occurred, client will automatically retry
305
306
```javascript
307
// Client automatically reconnects with built-in logic
308
const supabase = createClient('URL', 'ANON_KEY', {
309
  realtime: {
310
    params: {
311
      log_level: 'info',
312
      reconnectAfterMs: 1000 // Custom reconnection timing
313
    }
314
  }
315
})
316
317
// Simple connection state monitoring
318
channel.subscribe((status, err) => {
319
  switch (status) {
320
    case 'SUBSCRIBED':
321
      console.log('Connected (or reconnected)')
322
      break
323
    case 'CHANNEL_ERROR':
324
      console.error('Channel error:', err)
325
      // Client will automatically retry - no manual intervention needed
326
      break
327
    case 'CLOSED':
328
      console.log('Channel closed')
329
      break
330
  }
331
})
332
```
333
334
## Performance & Scaling Guidelines
335
336
### Channel Structure Optimization
337
- Use one channel per logical scope (`room:123`, not `user:456:room:123`)
338
- Shard high-volume topics: `chat:shard:1`, `chat:shard:2`
339
- Ensure you have enough connections set in your pool, you can refer to [Realtime Settings](https://supabase.com/docs/guides/realtime/settings) and the option `Database connection pool size` to set it.
340
341
## Debugging
342
343
### Enhanced Logging
344
```javascript
345
const supabase = createClient(url, key, {
346
  realtime: {
347
    params: { log_level: 'info' }
348
  }
349
})
350
```
351
352
## Migration from Postgres Changes
353
354
### Step 1: Replace Client Code
355
```javascript
356
// ❌ Remove postgres_changes
357
const oldChannel = supabase.channel('changes').on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, callback)
358
359
// ✅ Replace with broadcast
360
const room_id = "room_id" // or any other identifier that you use in the trigger function
361
const newChannel = supabase.channel(`messages:${room_id}:changes`, {
362
  config: { private: true }
363
})
364
.on('broadcast', { event: 'INSERT' }, callback)
365
.on('broadcast', { event: 'DELETE' }, callback)
366
.on('broadcast', { event: 'UPDATE' }, callback)
367
```
368
369
### Step 2: Add Database Trigger (Only if using broadcast)
370
```sql
371
CREATE TRIGGER messages_broadcast_trigger
372
  AFTER INSERT OR UPDATE OR DELETE ON messages
373
  FOR EACH ROW EXECUTE FUNCTION notify_table_changes();
374
```
375
376
### Step 3: Setup Authorization (Only if using broadcast)
377
```sql
378
CREATE POLICY "users_can_receive_broadcasts" ON realtime.messages
379
  FOR SELECT TO authenticated USING (true);
380
```
381
382
## LLM Implementation Guidelines
383
384
### When Generating Code
385
1. **Prefer using `broadcast` over `postgres_changes`** - Never suggest `postgres_changes`
386
2.**Include state checking** - Check channel state before subscribing
387
3. **Add cleanup logic** - Include unsubscribe in all examples
388
4. **Suggest proper naming** - Use consistent topic/event conventions
389
5. **Include error handling** - Add reconnection patterns
390
6. **Recommend indexing** - When RLS policies are used
391
7. **Framework-agnostic** - Adapt patterns to user's framework
392
8. **Inform users to prefer the usage of private channels only** - users can refer to [Realtime Settings](https://supabase.com/docs/guides/realtime/settings) to enable it.
393
394
### Code Generation Checklist
395
- ✅ Favor `broadcast` over `postgres_changes`
396
- ✅ Checks `channel.state` before subscribing
397
- ✅ Includes proper cleanup/unsubscribe logic
398
- ✅ Uses consistent naming conventions
399
- ✅ Includes error handling and reconnection
400
- ✅ Suggests indexes for RLS policies
401
- ✅ Sets `private: true` for database triggers
402
- ✅ Implements token refresh if needed
403
404
### Safe Defaults for AI Assistants
405
- Channel pattern: `scope:entity:id`
406
- Event pattern: `entity_action`
407
- Always check channel state before subscribing
408
- Always include cleanup
409
- Default to `private: true` for database-triggered channels
410
- Suggest basic RLS policies with proper indexing
411
- Include reconnection logic for production apps
412
- Use `postgres_changes` for simple database change notifications
413
- Use `broadcast` for custom events and complex payloads
414
415
**Remember:** Choose the right function for your use case, emphasize proper state management, and ensure production-ready patterns with authorization and error handling.