Surreal
The Surreal class is the primary interface for connecting to a SurrealDB instance, managing connections, executing queries, and handling database sessions. It extends SurrealSession and inherits all session management and query execution capabilities.
By default, a Surreal instance operates with a default session scope, but you can create additional isolated sessions using the session management methods.
Extends: SurrealSession → SurrealQueryable
Source: api/surreal.ts
Constructor
Syntax
Constructor Syntax
new Surreal(options?)
Parameters
| Parameter | Type | Description |
|---|
options optional | DriverOptions | Driver-wide configuration options for customizing engines, codecs, and implementations. |
Examples
Basic Usage
import { Surreal } from 'surrealdb';
const db = new Surreal();
With Custom Options
import { Surreal } from 'surrealdb';
const db = new Surreal({
codecOptions: {
useNativeDates: true
}
});
Properties
status
Returns the current connection status.
Type: ConnectionStatus
Values: "disconnected" | "connecting" | "reconnecting" | "connected"
Example:
console.log(db.status);
isConnected
Returns whether the connection is currently established. This is equivalent to checking if status === "connected".
Type: boolean
Example:
if (db.isConnected) {
console.log('Database is connected');
}
ready
A promise that resolves when the connection is established and ready, or rejects if a connection error occurs.
Type: Promise<void>
Example:
await db.ready;
console.log('Connection is ready');
Inherited Properties
The Surreal class inherits all properties from SurrealSession, including:
namespace - Current namespacedatabase - Current databaseaccessToken - Current access tokenparameters - Session parameterssession - Session IDisValid - Session validity status
Connection Methods
.connect()
Connect to a local or remote SurrealDB instance.
Calling connect() will reset and dispose of any existing sessions created with newSession().
Method Syntax
db.connect(url, opts?)
Parameters
| Parameter | Type | Description |
|---|
url required | string | URL | The endpoint URL to connect to (e.g., “ws://localhost:8000”, “http://localhost:8000/rpc”). |
opts optional | ConnectOptions | Connection-specific options such as namespace, database, and authentication. |
Returns
Promise<true> - Resolves to true when connection is successful
Examples
WebSocket Connection
await db.connect('ws://localhost:8000');
HTTP Connection
await db.connect('http://localhost:8000/rpc');
With Namespace and Database
await db.connect('ws://localhost:8000', {
namespace: 'my_namespace',
database: 'my_database'
});
With Authentication
await db.connect('ws://localhost:8000', {
namespace: 'my_namespace',
database: 'my_database',
authentication: {
username: 'root',
password: 'root'
}
});
With Custom Reconnect Options
await db.connect('ws://localhost:8000', {
reconnect: {
enabled: true,
attempts: 10,
retryDelay: 1000,
retryDelayMax: 10000,
retryDelayMultiplier: 2
}
});
.close()
Disconnect from the active SurrealDB instance.
Method Syntax
db.close()
Returns
Promise<true> - Resolves to true when disconnection is successful
Example
await db.close();
console.log('Connection closed');
.health()
Check the health status of the connected SurrealDB instance.
Method Syntax
db.health()
Returns
Promise<void> - Resolves if the instance is healthy, rejects otherwise
Example
try {
await db.health();
console.log('Database is healthy');
} catch (error) {
console.error('Health check failed:', error);
}
.version()
Retrieve version information from the connected SurrealDB instance.
Method Syntax
db.version()
Returns
Promise<VersionInfo> - An object containing version information
Example
const info = await db.version();
console.log(info.version);
.isFeatureSupported()
Check whether a specific feature is available in the current connection.
Method Syntax
db.isFeatureSupported(feature)
Parameters
| Parameter | Type | Description |
|---|
feature required | Feature | A feature from the Features object (e.g. Features.LiveQueries, Features.Api). |
Returns
boolean - true if the feature is supported, false otherwise
Example
import { Surreal, Features } from 'surrealdb';
if (db.isFeatureSupported(Features.LiveQueries)) {
console.log('Live queries are supported');
}
Session Management Methods
.sessions()
List all active sessions on the current connection.
Method Syntax
db.sessions()
Returns
Promise<Uuid[]> - An array of session IDs
Example
const sessionIds = await db.sessions();
console.log('Active sessions:', sessionIds);
.newSession()
Create a new isolated session on the current connection. The new session will have its own namespace, database, variables, and authentication state, but will share the same connection.
Sessions are automatically restored when the connection reconnects. Call reset() on the returned session to destroy it.
Method Syntax
db.newSession()
Returns
Promise<SurrealSession> - A new SurrealSession instance
Example
const session = await db.newSession();
await session.use({ namespace: 'other_ns', database: 'other_db' });
const results = await session.select('users');
await session.reset();
.closeSession()
Close the primary session. This is equivalent to calling close() on the connection.
Method Syntax
db.closeSession()
Returns
Promise<void> - Resolves when the session is closed
Example
await db.closeSession();
Data Management Methods
.export()
Export the database contents as a SQL string.
Method Syntax
db.export(options?)
Parameters
| Parameter | Type | Description |
|---|
options optional | SqlExportOptions | Options to customize what gets exported. |
Returns
Promise<string> - The exported database as a SQL string
Examples
Export Everything
const sql = await db.export();
Export Only Specific Tables
const sql = await db.export({
tables: ['users', 'posts'],
records: true
});
Export Schema Only (No Records)
const sql = await db.export({
records: false,
tables: true,
functions: true
});
.import()
Import database contents from a SQL string.
Method Syntax
db.import(input)
Parameters
| Parameter | Type | Description |
|---|
input required | string | The SQL string to import into the database. |
Returns
Promise<void> - Resolves when the import is complete
Example
const sqlData = `
DEFINE TABLE users SCHEMAFULL;
DEFINE FIELD name ON users TYPE string;
CREATE users:john SET name = 'John Doe';
`;
await db.import(sqlData);
console.log('Data imported successfully');
Events
The Surreal class implements the EventPublisher interface and emits various events during the connection lifecycle. Subscribe to events using the subscribe() method.
connecting
Emitted when the connection attempt starts.
Payload: None
Example:
const unsubscribe = db.subscribe('connecting', () => {
console.log('Connecting to database...');
});
connected
Emitted when the connection is successfully established.
Payload: [version: string] - The SurrealDB version string
Example:
db.subscribe('connected', (version) => {
console.log('Connected to SurrealDB version:', version);
});
reconnecting
Emitted when the connection is attempting to reconnect after being disconnected.
Payload: None
Example:
db.subscribe('reconnecting', () => {
console.log('Attempting to reconnect...');
});
disconnected
Emitted when the connection is closed.
Payload: None
Example:
db.subscribe('disconnected', () => {
console.log('Disconnected from database');
});
error
Emitted when a connection error occurs.
Payload: [error: Error] - The error object
Example:
db.subscribe('error', (error) => {
console.error('Connection error:', error.message);
});
Inherited Events
The Surreal class also inherits and re-emits events from SurrealSession:
auth - Emitted when authentication state changesusing - Emitted when namespace/database changes
.subscribe()
Subscribe to connection and session events.
Method Syntax
db.subscribe(event, listener)
Parameters
| Parameter | Type | Description |
|---|
event required | keyof SurrealEvents | The event name to subscribe to. |
listener required | Function | Callback function invoked when the event is emitted. |
Returns
() => void - An unsubscribe function to remove the event listener
Example
const unsubscribe = db.subscribe('connected', (version) => {
console.log('Connected:', version);
});
unsubscribe();
Inherited Methods
As Surreal extends SurrealSession, it inherits all authentication and query methods:
Authentication Methods
Session Configuration Methods
use() - Set namespace and databaseset() - Set a session parameterunset() - Remove a session parameterreset() - Reset the session
Query Methods
As Surreal extends SurrealQueryable (via SurrealSession), it also inherits all query execution methods:
Transaction Method
Type Parameters
This class does not use generic type parameters.
Complete Example
import { Surreal } from 'surrealdb';
const db = new Surreal({
codecOptions: {
useNativeDates: true
}
});
db.subscribe('connecting', () => console.log('Connecting...'));
db.subscribe('connected', (version) => console.log('Connected:', version));
db.subscribe('error', (error) => console.error('Error:', error));
await db.connect('ws://localhost:8000', {
namespace: 'my_namespace',
database: 'my_database',
authentication: {
username: 'root',
password: 'root'
}
});
console.log('Connected:', db.isConnected);
console.log('Status:', db.status);
const version = await db.version();
console.log('Version:', version.version);
const users = await db.select('users');
console.log('Users:', users);
const session = await db.newSession();
await session.use({ namespace: 'other_ns', database: 'other_db' });
const otherData = await session.select('data');
const backup = await db.export({ records: true });
console.log('Backup size:', backup.length);
await db.close();
See Also
