Live queries

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.

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.

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:

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