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

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 // Use native Date objects instead of DateTime
    }
});

Properties

status

Returns the current connection status.

Type: ConnectionStatus

Values: "disconnected" | "connecting" | "reconnecting" | "connected"

Example:

console.log(db.status); // "connected"

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 namespace
• database - Current database
• accessToken - Current access token
• parameters - Session parameters
• session - Session ID
• isValid - Session validity status

Connection Methods

.connect()

Connect to a local or remote SurrealDB instance.

Warning

Calling connect() will reset and dispose of any existing sessions created with newSession().

Method Syntax
db.connect(url, opts?)

Parameters

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); // "surrealdb-2.1.0"

.isFeatureSupported()

Check whether a specific feature is available in the current connection.

Method Syntax
db.isFeatureSupported(feature)

Parameters

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

// Create a new isolated session
const session = await db.newSession();

// Use different namespace/database in the new session
await session.use({ namespace: 'other_ns', database: 'other_db' });

// Query in the new session context
const results = await session.select('users');

// Destroy the session when done
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

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

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 changes
• using - Emitted when namespace/database changes

.subscribe()

Subscribe to connection and session events.

Method Syntax
db.subscribe(event, listener)

Parameters

Returns

() => void - An unsubscribe function to remove the event listener

Example

const unsubscribe = db.subscribe('connected', (version) => {
    console.log('Connected:', version);
});

// Later, unsubscribe from the event
unsubscribe();

Inherited Methods

As Surreal extends SurrealSession, it inherits all authentication and query methods:

Authentication Methods

• signup() - Sign up a new user
• signin() - Sign in with credentials
• authenticate() - Authenticate with a token
• invalidate() - Invalidate the session

Session Configuration Methods

• use() - Set namespace and database
• set() - Set a session parameter
• unset() - Remove a session parameter
• reset() - Reset the session

Query Methods

As Surreal extends SurrealQueryable (via SurrealSession), it also inherits all query execution methods:

• query() - Execute raw SurrealQL
• select() - Select records
• create() - Create records
• insert() - Insert records
• update() - Update records
• upsert() - Upsert records
• delete() - Delete records
• relate() - Create graph relationships
• live() - Subscribe to live queries
• run() - Execute functions

Transaction Method

• beginTransaction() - Start a transaction

Type Parameters

This class does not use generic type parameters.

Complete Example

import { Surreal } from 'surrealdb';

// Create and connect
const db = new Surreal({
    codecOptions: {
        useNativeDates: true
    }
});

// Subscribe to connection events
db.subscribe('connecting', () => console.log('Connecting...'));
db.subscribe('connected', (version) => console.log('Connected:', version));
db.subscribe('error', (error) => console.error('Error:', error));

// Connect to database
await db.connect('ws://localhost:8000', {
    namespace: 'my_namespace',
    database: 'my_database',
    authentication: {
        username: 'root',
        password: 'root'
    }
});

// Check connection status
console.log('Connected:', db.isConnected); // true
console.log('Status:', db.status); // "connected"

// Get version info
const version = await db.version();
console.log('Version:', version.version);

// Execute queries (inherited from SurrealSession/SurrealQueryable)
const users = await db.select('users');
console.log('Users:', users);

// Create a new isolated session
const session = await db.newSession();
await session.use({ namespace: 'other_ns', database: 'other_db' });
const otherData = await session.select('data');

// Export database
const backup = await db.export({ records: true });
console.log('Backup size:', backup.length);

// Close connection
await db.close();

See Also

• SurrealSession - Session management and authentication
• SurrealQueryable - Query execution methods
• SurrealTransaction - Transaction support
• Connection Engines - Engine-specific documentation
• Data Types - Working with data types