The Surreal class is the entry point for version 2 of the SDK. It manages the connection, the session, authentication, and query execution.

Namespace: SurrealDB\SDK\Surreal

Source: src/Surreal.php

Constructor

new Surreal(?DriverOptions $options = null)

DriverOptions customises driver-wide behaviour such as the codec, HTTP client, scheduler, and middleware. Pass null for the defaults.

use SurrealDB\SDK\Surreal;

$db = new Surreal();

Connection methods

connect()

Connect to a SurrealDB endpoint.

$db->connect(string|Endpoint $url, ?ConnectOptions $options = null): void

$db->connect('ws://127.0.0.1:8000/rpc', new ConnectOptions(
    namespace: 'surrealdb',
    database: 'docs',
));

close()

Close the connection and release its resources.

$db->close(): void

status()

Return the current ConnectionStatus.

$db->status(): ConnectionStatus

isConnected()

Return whether the connection is established. Equivalent to status() === ConnectionStatus::Connected.

$db->isConnected(): bool

health()

Throw if the instance is unreachable, otherwise return nothing.

$db->health(): void

version()

Return the server version string, for example surrealdb-2.1.0.

$db->version(): string

isFeatureSupported()

Return whether a feature is available on the current connection and server.

$db->isFeatureSupported(Feature $feature): bool

subscribe()

Subscribe to a lifecycle event: connecting, connected, reconnecting, disconnected, error, auth, or using. Returns a closure that removes the listener.

$db->subscribe(string $event, callable $listener): Closure

connection()

Return the underlying ConnectionController for advanced operations such as transactions, sessions, and import/export.

$db->connection(): ConnectionController

Session methods

use()

Select a namespace and an optional database.

$db->use(?string $namespace, ?string $database = null): void

let()

Define a session parameter, available in later queries as $name.

$db->let(string $name, mixed $value): void

unset()

Remove a session parameter.

$db->unset(string $name): void

Authentication methods

signin()

Sign in with a credential object or an array. Returns a Tokens object.

$db->signin(Credentials|array $auth): Tokens

signup()

Sign up a new record user. Returns a Tokens object.

$db->signup(Credentials|array $auth): Tokens

authenticate()

Authenticate the session with an existing token.

$db->authenticate(Token|string $token): void

invalidate()

Clear the session's authentication.

$db->invalidate(): void

Query methods

query()

Execute a BoundQuery, returning one result per statement.

$db->query(BoundQuery $query): array

run()

Execute raw SurrealQL with optional bindings, returning one result per statement.

$db->run(string $surql, array $bindings = []): array

Statement builders

These methods start a fluent query builder. Call execute() to run it.

• •

  select($what), create($what), update($what), upsert($what), delete($what)

• •

  insert($tableOrData, $data = null), relate($from, $edge, $to, $data = null)

• •

  call($name, $version = null, $args = []), auth()

live()

Subscribe to a live query by its ID. Returns an iterable of LiveMessage objects.

$db->live(string $queryUuid): iterable

Iterating the result blocks the process while it waits for messages. See running without blocking the application for consuming live queries in a worker.

Supporting types

ConnectOptions

Per-connection settings passed to connect().

Namespace: SurrealDB\SDK\Connection\ConnectOptions

new ConnectOptions(
    ?string $namespace = null,
    ?string $database = null,
    Credentials|Token|AuthProviderInterface|Closure|string|null $authentication = null,
    bool $versionCheck = true,
    bool $invalidateOnExpiry = false,
    bool|array|ReconnectStrategyInterface $reconnect = true,
)

ConnectionStatus

A string-backed enum with the connection lifecycle states.

Namespace: SurrealDB\SDK\Connection\ConnectionStatus

Values: Disconnected, Connecting, Reconnecting, Connected

Tokens

The result of signin() and signup(): an access token and an optional refresh token.

Namespace: SurrealDB\SDK\Auth\Tokens

$tokens->access;   // ?string
$tokens->refresh;  // ?string

LiveMessage

A single live query notification.

Namespace: SurrealDB\SDK\Live\LiveMessage

$message->queryId;  // string
$message->action;   // LiveAction (Create, Update, Delete, Killed)
$message->record;   // mixed: the affected record id
$message->value;    // mixed: the new record value

ConnectionController

The controller orchestrates the connection. Access it with $db->connection() for operations that are not on the Surreal facade.

Namespace: SurrealDB\SDK\Connection\ConnectionController

Transactions

$db->connection()->begin(?string $session = null): string
$db->connection()->commit(string $txn, ?string $session = null): void
$db->connection()->cancel(string $txn, ?string $session = null): void

Import and export

$db->connection()->importSql(string $data): void
$db->connection()->exportSql(array $options = []): string

$sql = $db->connection()->exportSql();
$db->connection()->importSql($sql);

Token renewal

$db->connection()->refresh(Tokens $tokens, ?string $session = null): Tokens
$db->connection()->revoke(Tokens $tokens, ?string $session = null): void

Sessions

$db->connection()->sessions(): array
$db->connection()->createSession(?string $clone = null): string
$db->connection()->destroySession(?string $session): void

See also

• •

  Query Builders for the fluent statement API

• •

  Data types for the value classes

• •

  Utilities for BoundQuery, enums, and driver options

• •

  Connecting to SurrealDB for the connection guide