SurrealSession

The SurrealSession class represents a scoped contextual session attached to a SurrealDB connection. It provides authentication, session configuration, and inherits all query execution methods from SurrealQueryable.

Sessions allow you to maintain isolated contexts with their own namespace, database, variables, and authentication state, while sharing the underlying connection.

Extends: SurrealQueryable

Extended by: Surreal

Source: api/session.ts

Constructor

The constructor is typically not called directly. Use Surreal.newSession() or forkSession() to create new sessions.

Properties

namespace

Returns the currently selected namespace for this session.

Type: string | undefined

Example:

console.log(session.namespace); // "my_namespace"

database

Returns the currently selected database for this session.

Type: string | undefined

Example:

console.log(session.database); // "my_database"

accessToken

Returns the current authentication access token for this session.

Type: string | undefined

Example:

if (session.accessToken) {
    console.log('Session is authenticated');
}

parameters

Returns all parameters currently defined on the session.

Type: Record<string, unknown>

Example:

console.log(session.parameters); // { user_id: '123', role: 'admin' }

session

Returns the unique session ID. For the default session, undefined is returned.

Type: Uuid | undefined

Example:

const sessionId = session.session;
console.log('Session ID:', sessionId);

isValid

Returns whether the session is valid and can be used. This is always true for the default session, but will be false for sessions that have been disposed via reset() or closeSession().

Type: boolean

Example:

if (session.isValid) {
    await session.select('users');
} else {
    console.log('Session has been closed');
}

Session Management Methods

.forkSession()

Create a new session by cloning the current session. The new session inherits all properties from the parent session including namespace, database, variables, and authentication state.

Sessions are automatically restored when the connection reconnects. Call reset() on the created session to destroy it.

Method Syntax
session.forkSession()

Returns

Promise<SurrealSession> - A new session instance

Example

// Create a forked session that inherits parent state
const childSession = await session.forkSession();

// The child inherits parent's namespace and database
console.log(childSession.namespace); // Same as parent
console.log(childSession.database); // Same as parent

// But can be changed independently
await childSession.use({ database: 'other_db' });

// Parent session remains unchanged
console.log(session.database); // Original database
console.log(childSession.database); // 'other_db'

// Clean up when done
await childSession.reset();

.closeSession()

Closes the current session and disposes of it. After this method is called, the session cannot be used again, and isValid will return false.

Method Syntax
session.closeSession()

Returns

Promise<void> - Resolves when the session is closed

Example

await session.closeSession();
console.log(session.isValid); // false

Transaction Methods

.beginTransaction()

Create a new transaction scoped to the current session. Transactions allow you to execute multiple queries atomically.

Call commit() on the transaction to apply changes, or cancel() to discard them.

Method Syntax
session.beginTransaction()

Returns

Promise<SurrealTransaction> - A new SurrealTransaction instance

Example

// Start a transaction
const txn = await session.beginTransaction();

try {
    // Execute queries within the transaction
    await txn.create(new RecordId('users', 'john'), {
        content: { name: 'John Doe', email: 'john@example.com' }
    });
    
    await txn.create(new RecordId('posts', '1'), {
        content: { author: new RecordId('users', 'john'), title: 'Hello' }
    });
    
    // Commit all changes atomically
    await txn.commit();
    console.log('Transaction committed successfully');
} catch (error) {
    // Roll back on error
    await txn.cancel();
    console.error('Transaction cancelled:', error);
}

Session Configuration Methods

.use()

Switch to the specified namespace and/or database for this session.

Leaving the namespace or database undefined will leave the current value unchanged, while passing null will unset the selected namespace or database.

Method Syntax
session.use(what)

Parameters

Returns

Promise<NamespaceDatabase> - The newly selected namespace and database

Examples

Switch Both Namespace and Database
await session.use({ 
    namespace: 'production', 
    database: 'main' 
});

Switch Only Database
await session.use({ 
    database: 'analytics' 
});
// Namespace remains unchanged

Unset Database
await session.use({ 
    database: null 
});
// Database is now undefined

.set()

Define a variable for the current session. Variables can be used in SurrealQL queries with the $ prefix.

Method Syntax
session.set(variable, value)

Parameters

Returns

Promise<void> - Resolves when the variable is set

Example

// Set a variable
await session.set('user_id', '12345');

// Use it in a query
const result = await session.query(
    'SELECT * FROM posts WHERE author = $user_id'
).collect();

.unset()

Remove a variable from the current session.

Method Syntax
session.unset(variable)

Parameters

Returns

Promise<void> - Resolves when the variable is removed

Example

await session.unset('user_id');

.reset()

Resets the current session to its initial state, clearing authentication state, variables, and selected namespace/database.

For non-default sessions, this also closes and disposes of the session.

Method Syntax
session.reset()

Returns

Promise<void> - Resolves when the session is reset

Example

// Reset session to clean state
await session.reset();

// Session is now cleared
console.log(session.namespace); // undefined
console.log(session.accessToken); // undefined
console.log(session.parameters); // {}

Authentication Methods

.signup()

Sign up a new record user to the SurrealDB instance.

Note

When this method is called, the authentication property passed to connect() will be ignored. You are responsible for handling session invalidation by listening to the auth event.

Method Syntax
session.signup(auth)

Parameters

Returns

Promise<Tokens> - The authentication tokens (access and refresh tokens)

Example

const tokens = await session.signup({
    namespace: 'my_namespace',
    database: 'my_database',
    access: 'user_access',
    variables: {
        email: 'user@example.com',
        password: 'secure_password',
        name: 'John Doe'
    }
});

console.log('Access token:', tokens.access);
console.log('Refresh token:', tokens.refresh);

.signin()

Sign in to the SurrealDB instance with authentication credentials.

Note

When this method is called, the authentication property passed to connect() will be ignored. You are responsible for handling session invalidation by listening to the auth event.

Method Syntax
session.signin(auth)

Parameters

Returns

Promise<Tokens> - The authentication tokens

Examples

System User Authentication
const tokens = await session.signin({
    username: 'root',
    password: 'root'
});

Record User Authentication
const tokens = await session.signin({
    namespace: 'my_namespace',
    database: 'my_database',
    access: 'user_access',
    variables: {
        email: 'user@example.com',
        password: 'secure_password'
    }
});

.authenticate()

Authenticate the session using an existing access token or access and refresh token combination.

When authenticating with a refresh token, a new refresh token will be issued and returned.

Note

When this method is called, the authentication property passed to connect() will be ignored. You are responsible for handling session invalidation by listening to the auth event.

Method Syntax
session.authenticate(token)

Parameters

Returns

Promise<Tokens> - The authentication tokens (may include new refresh token)

Examples

Authenticate with Access Token
await session.authenticate(accessToken);

Authenticate with Refresh Token
const newTokens = await session.authenticate({
    access: oldAccessToken,
    refresh: refreshToken
});

// Store new tokens
console.log('New access token:', newTokens.access);
console.log('New refresh token:', newTokens.refresh);

.invalidate()

Invalidate the authentication for the current session, signing the user out.

Method Syntax
session.invalidate()

Returns

Promise<void> - Resolves when authentication is invalidated

Example

await session.invalidate();
console.log('User signed out');

Events

The SurrealSession class emits events that you can subscribe to for tracking session state changes.

auth

Emitted when the authentication state changes for this session.

Payload: [tokens: Tokens | null] - The new authentication tokens, or null if invalidated

Example:

session.subscribe('auth', (tokens) => {
    if (tokens) {
        console.log('Authenticated with token:', tokens.access);
    } else {
        console.log('Authentication invalidated');
    }
});

using

Emitted when the namespace or database changes for this session.

Payload: [using: NamespaceDatabase] - Object containing the new namespace and database

Example:

session.subscribe('using', (using) => {
    console.log('Now using:', using.namespace, '/', using.database);
});

.subscribe()

Subscribe to session events.

Method Syntax
session.subscribe(event, listener)

Parameters

Returns

() => void - An unsubscribe function

Example

const unsubscribe = session.subscribe('auth', (tokens) => {
    console.log('Auth changed:', tokens);
});

// Later, unsubscribe
unsubscribe();

Inherited Methods

As SurrealSession extends SurrealQueryable, it 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
• api - Access user-defined APIs

Complete Example

import { Surreal } from 'surrealdb';

const db = new Surreal();
await db.connect('ws://localhost:8000');

// Use the default session
await db.use({ namespace: 'test', database: 'test' });

// Sign in
await db.signin({
    username: 'root',
    password: 'root'
});

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

// Configure the session
await session.use({ 
    namespace: 'production', 
    database: 'main' 
});

// Set session variables
await session.set('user_role', 'admin');

// Subscribe to session events
session.subscribe('auth', (tokens) => {
    console.log('Session auth changed:', tokens ? 'authenticated' : 'signed out');
});

session.subscribe('using', (using) => {
    console.log('Using:', using);
});

// Authenticate as a record user
const tokens = await session.signin({
    namespace: 'production',
    database: 'main',
    access: 'user_access',
    variables: {
        email: 'user@example.com',
        password: 'password'
    }
});

// Execute queries in the session context
const users = await session.select('users');

// Start a transaction
const txn = await session.beginTransaction();
await txn.create('logs:1', { content: { message: 'User logged in' } });
await txn.commit();

// Fork the session to create an isolated copy
const childSession = await session.forkSession();
await childSession.use({ database: 'analytics' });

// Clean up
await childSession.reset();
await session.closeSession();

See Also

• Surreal - Main connection class
• SurrealQueryable - Query execution methods
• SurrealTransaction - Transaction support
• Authentication Types - Authentication type definitions