Terminal
Terminal/Skill
Instructions for the official SurrealDB JavaScript and TypeScript SDK to connect, sign in, run CRUD and queries, and subscribe to live changes.
By SurrealDB
Works with
npx skills add surrealdb/agent-skills --skill surrealdb-jsThe 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.
npm i surrealdb
# or: pnpm i surrealdb / yarn add surrealdb / bun add surrealdb
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.
// 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: "a@b.com", pass: "secret" },
});
await db.signup({
namespace: "test",
database: "test",
access: "user",
variables: { email: "a@b.com", 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
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.
import { RecordId } from "surrealdb";
interface Person { id: RecordId; name: string; age?: number; }
// Create (random id, or a specific RecordId)
await db.create<Person>("person", { name: "Tobie" });
await db.create<Person>(new RecordId("person", "tobie"), { name: "Tobie" });
// Select all from a table, or a single record
const people = await db.select<Person>("person");
const tobie = await db.select<Person>(new RecordId("person", "tobie"));
// Replace the whole record(s)
await db.update<Person>(new RecordId("person", "tobie"), { name: "Tobie", age: 30 });
// Insert or update (upsert)
await db.upsert<Person>(new RecordId("person", "tobie"), { name: "Tobie" });
// Merge partial data into record(s)
await db.merge<Person>("person", { active: true });
// JSON Patch a record
await db.patch(new RecordId("person", "tobie"), [
{ op: "replace", path: "/name", value: "Tobie M H" },
]);
// Bulk insert
await db.insert<Person>("person", [{ name: "A" }, { name: "B" }]);
// Graph relation: person:tobie ->wrote-> article:surreal
await db.relate(new RecordId("person", "tobie"), "wrote", new RecordId("article", "surreal"));
// Delete record(s)
await db.delete("person");
await db.delete(new RecordId("person", "tobie"));
db.query<T>(sql, vars) runs raw SurrealQL and returns an array with one entry
per statement. Always pass user input via bound parameters, never string
interpolation.
const [people, count] = await db.query<[Person[], number]>(
`SELECT * FROM person WHERE age > $min;
SELECT count() FROM person GROUP ALL;`,
{ min: 18 },
);
// Bind values and RecordIds as parameters
const [found] = await db.query<[Person[]]>(
"SELECT * FROM person WHERE id = $who",
{ who: new RecordId("person", "tobie") },
);
Other helpers: db.let(name, value) / db.unset(name) set session parameters
usable as $name in later queries; db.run(fnName, version, args) invokes a
defined function; db.queryRaw() returns the unparsed RPC response (status +
timing per statement).
Subscribe to real-time changes on a table with db.live(). Requires a
WebSocket (or embedded) connection — not HTTP. See
references/live-queries.md.
const queryUuid = await db.live<Person>("person", (action, result) => {
// action: "CREATE" | "UPDATE" | "DELETE" | "CLOSE"
console.log(action, result);
});
await db.kill(queryUuid); // stop the subscription
RecordId, Table,
Duration, Decimal, Uuid, geometry, and CBOR mapping.@surrealdb/node (RocksDB / SurrealKV / in-memory) and @surrealdb/wasm
(in-memory / IndexedDB).live,
subscribeLive, and kill patterns.