Node.js

This library is a plugin for the SurrealDB JavaScript SDK, which can be used to run SurrealDB as an embedded database within a Node.js server-side environment.

It enables SurrealDB to be run in-memory, or to persist data by running on top of SurrealKV. It allows for a consistent JavaScript and TypeScript API when using the surrealdb.js library by adding support for embedded storage engines (memory, surrealkv) alongside the remote connection protocols (http, https, ws, wss).

The WebAssembly engine is available on NPM as @surrealdb/node and is required to be used as a plugin within the JavaScript SDK.

Important

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

Installation

Before installing the Node.js engine, you need to install the JavaScript SDK using the instructions in the installation documentation.

After installing the SDK, install the Node.js engine using the following command:

npm install --save @surrealdb/node

yarn add @surrealdb/node

pnpm install @surrealdb/node

Configuration

To use the Node.js engine, you need to import the surrealdbNodeEngines function from the @surrealdb/node package, and pass it as an option to the Surreal constructor.

import { Surreal } from 'surrealdb';
import { surrealdbNodeEngines } from '@surrealdb/node';

After importing the surrealdbNodeEngines function, you can pass it as an option to the Surreal constructor.

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

Connecting

Using the .connect() method, you can connect to a SurrealDB instance. The connection string specifies whether to connect to the Wasm engine, in memory or persisted with the mem:// or surrealkv:// prefixes respectively.

Example

import { Surreal } from 'surrealdb';
import { surrealdbNodeEngines } from '@surrealdb/node';

// Enable the WebAssembly engines
const db = new Surreal({
    engines: surrealdbNodeEngines(),
});

// Now we can start SurrealDB as an in-memory database
await db.connect("mem://");
// Or we can start a persisted SurrealKV database
await db.connect("surrealkv://demo");

// Now use the JavaScript SDK as normal.

// Close the database connection
await db.close();

Note

You must close the connection to the database with the .close() method to prevent console warnings.

Next steps

After setting up the Wasm engine, you can continue with the rest of the SDK documentation. You can refer to the methods documentation for more information on using SurrealDB with the Wasm engine also see the data types documentation for more information on how to use the data types supported by SurrealDB.

Sources

• @surrealdb/node on NPM
• GitHub repository