# Configuration

Configure the SurrealDB Laravel integration with environment variables, authentication modes, multiple named connections, and the ORM model list.

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.

```dotenv
SURREALDB_CONNECTION=default
SURREALDB_URL=ws://127.0.0.1:8000/rpc
SURREALDB_NAMESPACE=test
SURREALDB_DATABASE=test
SURREALDB_USERNAME=root
SURREALDB_PASSWORD=secret
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.

| `SURREALDB_AUTH_MODE` | SDK credential |
|-----------------------|----------------|
| `namespace` | `NamespaceAuth` |
| `database` | `DatabaseAuth` |
| `record` | `RecordAccessAuth` |
| `bearer` | `BearerAuth` |
| `token` | An existing token |
| `none` | No authentication |

See [Authentication](/docs/reference/php/v2/concepts/authentication.md) 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.

```php
'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](/docs/reference/php/frameworks/laravel/queries-and-transactions.md) and the `--connection` option on the [schema commands](/docs/reference/php/frameworks/laravel/schema-commands.md).

## ORM configuration

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

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

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

The `models` list is used by the [schema commands](/docs/reference/php/frameworks/laravel/schema-commands.md).

## Lifecycle and Octane

Under PHP-FPM the SDK client is resolved once per request and disconnected on terminate. Under [Laravel Octane](https://laravel.com/docs/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](/docs/reference/php/v2/concepts/runtimes.md).

## Learn more

- [Container and facades](/docs/reference/php/frameworks/laravel/container-and-facades.md) for the bindings these settings drive
- [Authentication](/docs/reference/php/v2/concepts/authentication.md) for the credential types
- [Connecting to SurrealDB](/docs/reference/php/v2/concepts/connecting-to-surrealdb.md) for the SDK connection options