Configuration

The integration keeps SDK and ORM configuration separate. config/surrealdb.php configures the SDK client, and config/surqlize.php configures the ORM.

Connection environment variables

config/surrealdb.php reads these environment variables for the default connection.

SURREALDB_CONNECTION=default
SURREALDB_URL=ws://127.0.0.1:8000/rpc
SURREALDB_NAMESPACE=test
SURREALDB_DATABASE=test
SURREALDB_USERNAME=root
SURREALDB_PASSWORD=root
SURREALDB_AUTO_CONNECT=true
SURREALDB_CONNECT_ON_RESOLVE=true
SURREALDB_DISCONNECT_ON_TERMINATE=true
SURREALDB_HEALTH_CHECK_ON_RESOLVE=false

The lifecycle flags control when the integration opens and closes connections: whether to connect automatically, connect when the client is first resolved from the container, disconnect when the request terminates, and run a health check on resolve.

Authentication modes

When SURREALDB_USERNAME is set, the integration authenticates with the SDK's RootAuth by default. For scoped authentication, set SURREALDB_AUTH_MODE and fill the matching keys in the published config.

See Authentication for what each credential needs.

Multiple connections

The SDK config supports several named connections under a connections key, with a default selecting which to use.

'default' => env('SURREALDB_CONNECTION', 'default'),

'connections' => [
    'default' => [
        'url' => env('SURREALDB_URL', 'ws://127.0.0.1:8000/rpc'),
        'namespace' => env('SURREALDB_NAMESPACE', 'test'),
        'database' => env('SURREALDB_DATABASE', 'test'),
        // auth, lifecycle, and driver options...
    ],

    'analytics' => [
        'url' => env('SURREALDB_ANALYTICS_URL'),
        'namespace' => env('SURREALDB_ANALYTICS_NAMESPACE'),
        'database' => env('SURREALDB_ANALYTICS_DATABASE'),
        'auto_connect' => false,
    ],
],

A non-default connection is selected with the connection: argument on the facade methods and the --connection option on the schema commands.

ORM configuration

config/surqlize.php holds the model list and the executor binding. The executor defaults to the Laravel-managed SurrealDB connection.

'executor' => env('SURQLIZE_EXECUTOR', 'surrealdb.connection'),

'models' => [
    App\Models\User::class,
],

The models list is used by the schema commands.

Lifecycle and Octane

Under PHP-FPM the SDK client is resolved once per request and disconnected on terminate. Under Laravel Octane, queue workers, or long-running commands, the container, and therefore the client, lives longer. The disconnect_on_terminate flag and Octane's worker model determine how long a connection stays open. For live queries, run them in dedicated workers as described in Runtimes and workers.

Learn more

• Container and facades for the bindings these settings drive

• Authentication for the credential types

• Connecting to SurrealDB for the SDK connection options