Node.js engine

The @surrealdb/node package is a plugin for the JavaScript SDK that allows you to run SurrealDB as an embedded database within a Node.js server-side environment. It supports in-memory databases and persistent storage via RocksDB and SurrealKV, and is also compatible with Bun and Deno.

Important

This package works with ES modules (import), not CommonJS (require).

Installing the Node.js engine

Before installing the Node.js engine, you need the core JavaScript SDK installed. Then add the @surrealdb/node package.

npm install --save @surrealdb/node

yarn add @surrealdb/node

pnpm install @surrealdb/node

Registering the engine

Import createNodeEngines from @surrealdb/node and spread it into the engines option alongside createRemoteEngines from the core SDK. This registers the embedded protocols while keeping remote connections available.

import { Surreal, createRemoteEngines } from 'surrealdb';
import { createNodeEngines } from '@surrealdb/node';

const db = new Surreal({
    engines: {
        ...createRemoteEngines(),
        ...createNodeEngines(),
    },
});

Supported connection protocols

Once the Node.js engine is registered, you can connect to SurrealDB using the embedded protocols.

await db.connect('mem://');

await db.connect('surrealkv://./data');

To enable versioned storage for temporal queries, append ?versioned=true to the connection string.

await db.connect('surrealkv://./data?versioned=true');

Remote protocols (ws://, wss://, http://, https://) remain available when createRemoteEngines() is also registered.

Bun and Deno compatibility

The @surrealdb/node engine is compatible with Bun and Deno in addition to Node.js. The installation and usage are the same across all three runtimes.

Closing the connection

When using the Node.js engine, you must close the connection with .close() when you are done to ensure the database is properly shut down and to avoid console warnings.

await db.close();

Learn more

• Node.js engine reference for additional engine configuration
• Connecting to SurrealDB for connection options and reconnection behavior
• @surrealdb/node on npm