Push live updates with realtime and queues

Updates without polling

Instead of asking the server "anything new?" every few seconds, realtime pushes an update the moment something happens. You will broadcast an event, receive it in a browser, and then see how queues carry work reliably.

Try a broadcast in the Console

1. Open Realtime Channels in the sidebar.
2. Under Broadcast Event, set Target Channel to notes, Event Name to note_created and a JSON Payload such as {"id": 1}.
3. Choose Broadcast to Channel.
4. Look at the Live Channel Stream Terminal. Your event arrived instantly. Choose Clear to empty it.

A channel is just a name. Channels belong to your project, so another project's notes channel never mixes with yours.

Subscribe from a page

Browsers subscribe with Server-Sent Events, a long-lived connection that needs no extra library:

const es = new EventSource("https://api.pgbhub.app/api/v1/realtime/stream?channel=notes&project=my-project");
es.addEventListener("note_created", (e) => console.log(JSON.parse(e.data)));

Or with the SDK: const stop = pgb.realtime.subscribe("notes", (evt) => console.log(evt)). Call stop() to unsubscribe.

Broadcast from your server

await admin.realtime.broadcast("notes", { id: 42 }, { event: "note_created" });

Publishing needs a secret key, or a publishable key together with a signed-in user's token. The sender your listeners see is set by PGB from that credential, so a browser cannot pose as someone else.

Warning: Subscribing needs only your project identifier, so treat anything broadcast as readable by anyone who knows the channel name. Send ids or "something changed" signals, and let the app load details through your protected data calls.

Realtime delivers events you broadcast. It does not watch your tables on its own. To broadcast on a data change, call broadcast from a function, or add a realtime effect to an action.

Queues for work that must not be lost

Realtime is for whoever is listening now. A queue holds messages until a worker is ready.

1. Open Queues & Workers and choose + Create Queue.
2. Queue Name: thumbnails. Leave Visibility Timeout (sec) at 30 and Max Retries at 5. Name a Dead-Letter Queue (optional) such as thumbnails_failed.
3. Choose Create Queue, then Inspect.
4. Use Enqueue Test Message with {"note_id": 42}. It appears as PENDING.

A worker then receives the message (it becomes IN_FLIGHT and locked for the visibility timeout), does the work and acknowledges it (ACKED). If it crashes, the message reappears after the timeout. After too many failures it moves to the dead-letter queue.

curl -X POST https://api.pgbhub.app/api/v1/projects/my-project/queues/thumbnails/receive \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"max_messages": 1, "visibility_timeout": 30}'

Then call /ack with the message_id. Delivery is at least once, so make workers repeatable.

Reacting to events

Events & Webhooks lets you route an event such as user.created to a queue, function, webhook or email, with no code change in sign-up. Create a rule with + Create Event Rule, then test it with Emit a Test Event.

Recap

• Broadcast and subscribe over named channels for instant updates.
• Do not broadcast private data.
• Queues keep work safe until a worker acknowledges it, with retries and a dead-letter queue.
• Event rules connect "something happened" to "do this next".