Migration guide | SurrealDB

Move a project from version 1 to version 2 of the SurrealDB PHP SDK, with a method-by-method mapping of the breaking changes.

Version 2 is a rewrite of the PHP SDK. The namespace, the query API, the credential types, and the connection options all changed. This guide maps each v1 pattern to its v2 equivalent.

Important

Version 2 is published as 2.0.0-alpha.1 and requires PHP 8.4 or later. It is an alpha, so review the changes here and test before upgrading a production project. Version 1 remains the stable release.

What changed

The namespace moved from Surreal\ to SurrealDB\SDK\.
Mutations use fluent builders that end in execute(), instead of taking data as a second argument.
Raw SurrealQL runs through run(). In v1, query() ran SurrealQL; in v2, query() takes a pre-built BoundQuery.
Credentials are typed classes such as RootAuth, and signin() returns a Tokens object instead of a string.
Connection settings are passed as a ConnectOptions object, and use() takes positional arguments.
Data type classes moved to SurrealDB\SDK\Types and use named constructors such as RecordId::from().
Import and export moved to $db->connection().

1. Install version 2

Update your PHP version to 8.4 or later, then require the alpha release and a PSR-18 HTTP client.

composer require surrealdb/surrealdb.php:2.0.0-alpha.1
composer require guzzlehttp/guzzle php-http/discovery

2. Update the namespace

// v1
use Surreal\Surreal;

// v2
use SurrealDB\SDK\Surreal;

3. Update the connection

In v2, pass connection settings as a ConnectOptions object and select the namespace and database with positional arguments.

// v1
$db->connect('ws://127.0.0.1:8000/rpc');
$db->use(['namespace' => 'surrealdb', 'database' => 'docs']);

// v2
use SurrealDB\SDK\Connection\ConnectOptions;

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

4. Update authentication

Credentials are now typed classes, and signin() returns a Tokens object.

// v1
$token = $db->signin(['user' => 'root', 'pass' => 'root']);

// v2
use SurrealDB\SDK\Auth\RootAuth;

$tokens = $db->signin(new RootAuth('root', 'root'));
$token = $tokens->access;

Record access uses RecordAccessAuth, and the scope key is now access.

// v1
$db->signin([
    'namespace' => 'surrealdb',
    'database' => 'docs',
    'scope' => 'user',
    'email' => 'a@b.com',
    'pass' => 'secret',
]);

// v2
use SurrealDB\SDK\Auth\RecordAccessAuth;

$db->signin(new RecordAccessAuth(
    namespace: 'surrealdb',
    database: 'docs',
    access: 'user',
    variables: ['email' => 'a@b.com', 'pass' => 'secret'],
));

5. Update queries

Raw SurrealQL moves from query() to run(). Mutations become fluent builders.

// v1
$people = $db->query('SELECT * FROM person WHERE age > $min', ['min' => 18]);
$person = $db->create('person:tobie', ['name' => 'Tobie']);
$db->merge('person:tobie', ['age' => 33]);

// v2
$people = $db->run('SELECT * FROM person WHERE age > $min', ['min' => 18]);
$person = $db->create(new RecordId('person', 'tobie'))
    ->content(['name' => 'Tobie'])
    ->execute();
$db->update(new RecordId('person', 'tobie'))
    ->merge(['age' => 33])
    ->execute();

6. Update data types

Data type classes moved to SurrealDB\SDK\Types and use named constructors.

// v1
use Surreal\Cbor\Types\Record\RecordId;
$id = RecordId::create('person', 'tobie');

// v2
use SurrealDB\SDK\Types\RecordId;
$id = RecordId::from('person', 'tobie'); // or new RecordId('person', 'tobie')

The RecordId properties also changed: ->tb is now ->table.

7. Update import and export

// v1
$db->import($sql, 'root', 'root');
$dump = $db->export('root', 'root');

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

Method mapping

v1	v2
`new \Surreal\Surreal()`	`new \SurrealDB\SDK\Surreal()`
`connect($url, ['namespace' => ..., 'database' => ...])`	`connect($url, new ConnectOptions(namespace: ..., database: ...))`
`use(['namespace' => $ns, 'database' => $db])`	`use($ns, $db)`
`signin([...]): string`	`signin(new RootAuth(...)): Tokens`
`query($sql, $vars)`	`run($sql, $vars)`
`select($thing)`	`select($thing)->execute()`
`create($thing, $data)`	`create($thing)->content($data)->execute()`
`update($thing, $data)`	`update($thing)->content($data)->execute()`
`merge($thing, $data)`	`update($thing)->merge($data)->execute()`
`patch($thing, $patches)`	`update($thing)->patch($patches)->execute()`
`insert($table, $data)`	`insert(new Table($table), $data)->execute()`
`insertRelation($table, $data)`	`insert(new Table($table), $data)->relation()->execute()`
`delete($thing)`	`delete($thing)->execute()`
`relate($from, $edge, $to, $data)`	`relate($from, $edge, $to, $data)->execute()`
`run('fn::foo', '1.0', $args)`	`call('fn::foo', '1.0', $args)->execute()`
`RecordId::create('t', 'id')`	`RecordId::from('t', 'id')`
`Table::create('t')`	`new Table('t')`
`import($sql, $user, $pass)`	`connection()->importSql($sql)`
`export($user, $pass)`	`connection()->exportSql()`
`status(): int`	`status(): ConnectionStatus`

Removed and changed APIs

info() is not exposed on the v2 Surreal class. Use the auth() builder, which compiles to SELECT * FROM ONLY $auth.
The SurrealML import and export helpers (importML(), exportML()) are not part of the v2 public API.
query() no longer runs raw SurrealQL. It executes a BoundQuery; use run() for raw statements.
status() returns a ConnectionStatus enum rather than an HTTP status integer.

Learn more

v2 overview for the new SDK
Executing queries for the builder API
Authentication for the credential types