Live queries | SurrealDB

Subscribe to real-time changes from SurrealDB over a WebSocket connection with version 2 of the PHP SDK.

Live queries notify your application whenever records that match a query are created, updated, or deleted. You start a LIVE SELECT statement to get a query ID, then iterate the messages the server pushes for that ID.

Note

Live queries require a WebSocket connection. They are not available over HTTP. Check support with isFeatureSupported() before relying on one.

Starting a live query

Run a LIVE SELECT statement with run(). The result is the live query ID.

[$queryId] = $db->run('LIVE SELECT * FROM person');

Receiving messages

Pass the ID to live(). It returns an iterable of LiveMessage objects, one per change. Each message carries the action, the affected record ID, and the new value.

use SurrealDB\SDK\Live\LiveAction;

foreach ($db->live($queryId) as $message) {
    match ($message->action) {
        LiveAction::Create => handleCreate($message->value),
        LiveAction::Update => handleUpdate($message->value),
        LiveAction::Delete => handleDelete($message->record),
        LiveAction::Killed => break,
    };
}

Running without blocking the application

A foreach over live() blocks the current PHP process while it waits for the next message. The standard PHP runtime (PHP-FPM or the CLI) handles one task per worker, so a process parked on a live query cannot serve anything else.

Warning

Consume live queries in a dedicated, long-running worker, and run the PHP runtime with several workers so that one worker blocked on a live query does not freeze the rest of your application. Avoid opening a live query inside a normal web request.

To run live queries alongside the rest of your application, choose an asynchronous runtime or run dedicated workers. See Runtimes and workers for configuring PHP-FPM with dedicated workers, OpenSwoole, and FrankenPHP.

Live actions

Every message has an action from the LiveAction enum:

Action	Description
`LiveAction::Create`	A new record matched the query
`LiveAction::Update`	A matching record was modified
`LiveAction::Delete`	A matching record was removed
`LiveAction::Killed`	The live query was stopped on the server

Stopping a live query

Stop a live query by running a KILL statement with its ID. The loop receives a final LiveAction::Killed message and ends.

$db->run('KILL $id', ['id' => $queryId]);

Learn more

Surreal API reference for the live() signature
LIVE SELECT for the SurrealQL syntax
Connecting to SurrealDB for WebSocket setup