surrealdb-js

SurrealDB JavaScript SDK

The official SDK (surrealdb on npm) works in Node.js, Deno, Bun, and the browser. It connects to a remote SurrealDB instance over WebSocket/HTTP, or runs an embedded engine in-process. Target the latest stable surrealdb release; install without pinning (npm i surrealdb) unless the user requires a specific version.

Installation

npm i surrealdb
# or: pnpm i surrealdb / yarn add surrealdb / bun add surrealdb

Connect & select namespace/database

Always connect, then use a namespace + database, then authenticate. Close the connection when finished.

import { Surreal } from "surrealdb";

const db = new Surreal();
await db.connect("ws://127.0.0.1:8000/rpc");
await db.use({ namespace: "test", database: "test" });
await db.signin({ username: "root", password: "root" });

// ... work ...

await db.close();

Run a local server with surreal start -u root -p root rocksdb:mydb (or in-memory with surreal start -u root -p root). To run SurrealDB in-process with no server, see references/embedded.md.

Authentication

// Root / namespace / database users
await db.signin({ username: "root", password: "root" });
await db.signin({ namespace: "test", username: "ns_user", password: "..." });
await db.signin({ namespace: "test", database: "test", username: "db_user", password: "..." });

// Record (scope) access — sign in / sign up against a DEFINE ACCESS method
const token = await db.signin({
  namespace: "test",
  database: "test",
  access: "user",          // name of the access method
  variables: { email: "[email protected]", pass: "secret" },
});

await db.signup({
  namespace: "test",
  database: "test",
  access: "user",
  variables: { email: "[email protected]", pass: "secret" },
});

await db.authenticate(token); // re-auth with a stored JWT
await db.invalidate();        // log out the current session
const me = await db.info();   // info about the authenticated record user

CRUD

Pass a table as a string ("person") or a RecordId for a specific record. See references/data-types.md for RecordId, Table, Duration, Decimal, and other value classes.