Sessions

A session is an independent context on a connection. It carries its own selected namespace and database, its own session variables, and its own authentication state. Version 2 of the PHP SDK opens one default session when you connect, and every method on the Surreal class runs against it.

For most applications the default session is all you need. Multiple sessions are useful when a single long-lived connection has to serve several independent contexts, for example different authenticated users on the same WebSocket.

use SurrealDB\SDK\Protocol\Features;

if ($db->isFeatureSupported(Features::sessions())) {
    // safe to create extra sessions
}

Managing sessions

Additional sessions are managed through the ConnectionController, which you reach with connection().

Creating a session

createSession() opens a new session and returns its id. Pass the id of an existing session to clone to copy its namespace, database, and variables into the new one.

$db->connection()->createSession(?string $clone = null): string

$session = $db->connection()->createSession();

Listing sessions

sessions() returns the ids of the open sessions.

$db->connection()->sessions(): array

Destroying a session

destroySession() closes a session and releases it. Passing an unknown id throws an InvalidSessionException.

$db->connection()->destroySession(?string $session): void

$db->connection()->destroySession($session);

Running queries in a session

The methods on Surreal always use the default session. To run a statement in another session, call query() on the controller and pass the session id. It returns an iterable of result chunks, one per statement; call resultOrThrow() on each to get its value or raise the server error.

use SurrealDB\SDK\Query\BoundQuery;

$session = $db->connection()->createSession();

foreach ($db->connection()->query(
    new BoundQuery('SELECT * FROM person'),
    $session,
) as $chunk) {
    $people = $chunk->resultOrThrow();
}

$db->connection()->destroySession($session);

The same call accepts a transaction id as a third argument, so a session can run statements inside an explicit transaction.

Learn more

• Surreal API reference for the session methods

• Transactions for running statements atomically

• Connecting to SurrealDB for the default session and WebSocket setup