Real‑Time Dashboards Made Easy with SurrealDB’s Built‑In Subscription Feature

Live Data Without Polling

In many dashboards you still rely on periodic queries to keep the UI in sync. That adds latency, increases load, and wastes bandwidth. SurrealDB solves this with a native SUBSCRIBE command that pushes only the changes you care about over WebSockets. The result is a truly reactive UI that stays fresh without extra polling.

How SUBSCRIBE Works

The command is SQL‑like and can be executed from the SurrealDB CLI, any WebSocket client, or a language‑specific SDK. A subscription is defined by a query and an optional WHERE clause that filters events. SurrealDB then tracks the delta that satisfies the filter and streams INSERT, UPDATE, and DELETE events as JSON payloads.

Example subscription that listens to all pending orders:

SUBSCRIBE "SELECT * FROM orders WHERE status = 'pending'"

When an order is inserted, updated, or deleted while it matches the filter, the client receives a JSON object describing the event type and the affected record. The subscription remains active until the client disconnects or explicitly unsubscribes.

Practical Setup Example

Below is a step‑by‑step guide to create a subscription that pushes updates for orders over a WebSocket. The example uses wscat for simplicity, but any WebSocket library will work.

1. Start SurrealDB (Docker or local binary). Ensure the database is running on localhost:8000 and that authentication is enabled.

   docker run -p 8000:8000 surrealdb/surrealdb:latest start --auth
   

2. Connect to the database via WebSocket. Use wscat to open a session with a bearer token.

   wscat -c wss://localhost:8000/rpc -p "Bearer <YOUR_TOKEN>"
   

   Replace <YOUR_TOKEN> with a valid token from your SurrealDB auth system.

3. Register the subscription. Send the SUBSCRIBE command over the WebSocket connection.

   SUBSCRIBE "SELECT * FROM orders WHERE status = 'pending'"
   

   SurrealDB will reply with a subscription ID, e.g., subscription:1234. Keep this ID if you need to unsubscribe later.

4. Insert a test record from another terminal or via the SurrealDB CLI.

   INSERT INTO orders (id, status, amount) VALUES ('order:001', 'pending', 250);
   

   In the WebSocket client you should see a JSON payload similar to:

   {"event":"INSERT","record":{"id":"order:001","status":"pending","amount":250}}
   

   Update the record to trigger an UPDATE event.

   UPDATE orders SET status = 'shipped' WHERE id = 'order:001';
   

   The client receives a payload with event":"UPDATE". Because the new status no longer matches the filter, no further events are sent for this record.

5. Verify deletion. Delete the record.

   DELETE FROM orders WHERE id = 'order:001';
   

   If the record was still matching the filter, a DELETE event would be pushed.

6. Check SurrealDB logs to confirm the subscription was registered and events were dispatched. Look for entries like "subscription registered" or “event dispatched”.

Trade‑Offs and Best Practices

• Network overhead: Each event travels over WebSocket. Implement reconnection logic and exponential back‑off to handle transient network issues.
• High write volume: Large tables with frequent writes can flood clients. Use tight WHERE filters or batch updates on the client side.
• Security: Subscriptions expose real‑time data. Always authenticate clients and restrict subscriptions to authorized scopes.
• Version differences: The exact SUBSCRIBE syntax may change between major releases. Refer to the version‑specific documentation for your deployment.
• State management: Because you receive only deltas, ensure your client can reconcile state if the connection drops and you miss events. A fallback full refresh can mitigate this.

Getting Started

To integrate SurrealDB’s subscriptions into your stack:

1. Choose a WebSocket client or use SurrealDB’s SDK for your language.
2. Authenticate against SurrealDB (JWT, OAuth, or API key).
3. Send a SUBSCRIBE command with a filter that matches the data you need.
4. Handle incoming JSON payloads – map event types to UI updates.
5. Gracefully handle disconnects by re‑subscribing and reconciling missed changes.

With this pattern you can build dashboards that reflect live data instantly, without the complexity of polling loops or external message brokers.