Documentation

View the JavaScript SDK documentation here, including the embedded engines concept page and the Node.js engine reference.

What is this package?

@surrealdb/node is a native engine plugin for the SurrealDB JavaScript SDK. It embeds SurrealDB directly in your server-side JavaScript runtime using a NAPI addon, so you can run databases in-process without a separate server.

Despite the name, this package works in Node.js, Bun, and Deno. It is not used in browsers - use @surrealdb/wasm for that.

Install it alongside surrealdb and register the engine when constructing your client.

How to install

This package has a peer dependency on surrealdb. Install both:

# using npm
npm i surrealdb @surrealdb/node

# or using pnpm
pnpm i surrealdb @surrealdb/node

# or using yarn
yarn add surrealdb @surrealdb/node

# or using bun
bun add surrealdb @surrealdb/node

Getting started

Register the Node.js engine when you create a Surreal client, then connect to an embedded endpoint:

import { createNodeEngines } from "@surrealdb/node";
import { Surreal } from "surrealdb";

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

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

await db.use({ namespace: "test", database: "test" });

await db.query("CREATE person SET name = 'Tobie'");

To connect to remote SurrealDB instances as well as embedded databases, combine the Node.js engine with the SDK's remote engines:

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

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

Storage backends

The engine supports in-memory and on-disk storage:

// In-memory (data is lost when the process exits)
await db.connect("mem://");

// RocksDB persistence
await db.connect("rocksdb://path/to/storage.db");

// SurrealKV persistence
await db.connect("surrealkv://path/to/storage.db");

// SurrealKV with versioned storage for temporal queries
await db.connect("surrealkv+versioned://path/to/storage.db");

Connection options

Pass optional engine configuration to createNodeEngines:

const db = new Surreal({
    engines: createNodeEngines({
        strict: true,
        query_timeout: 30_000,
        capabilities: {
            scripting: true,
        },
    }),
});

Closing the connection

When using the embedded engine, call .close() when you are done to shut down the database cleanly:

await db.close();

Package contents

| Export | Description | | --- | --- | | createNodeEngines(options?) | Registers mem, rocksdb, surrealkv, and surrealkv+versioned engine factories | | NodeEngine | The underlying engine implementation (advanced use) |

Requirements

• ES modules (import) - CommonJS (require) is not supported
• A compatible surrealdb SDK version (see peerDependencies in package.json)
• Node.js, Bun, or Deno on a supported platform (native binaries are published per OS/architecture)

Contributing

This package is part of the surrealdb.js monorepo. See the main README for local setup, build commands, and contribution guidelines.