# surrealdb-js

Guides AI coding agents through the official JavaScript and TypeScript SurrealDB SDK, covering connection setups, auth, CRUD, and live queries.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 378 installs · ★ 28
- Author: surrealdb
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealdb-js/SKILL.md
- Updated: 2026-09-29
- HTML: https://affpapa.org/en/nevibecode/skills/surrealdb-js

## What it does

The skill provides code patterns for the official `surrealdb` package across Node.js, Deno, Bun, and browsers. It enforces the mandatory connection lifecycle: connecting to the endpoint, selecting namespace and database via `use()`, and signing in.

It instructs the assistant on CRUD calls, graph links via `db.relate()`, JSON patches, and custom SurrealQL execution. Queries sent to `db.query()` must always bind user values to parameters rather than interpolating raw strings.

Live subscriptions via `db.live()` will fail over regular HTTP endpoints because the library requires a WebSocket connection or an in-process engine.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealdb-js -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/surrealdb-js/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/surrealdb-js/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealdb-js -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/surrealdb-js/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealdb-js -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/surrealdb-js/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install surrealdb/agent-skills surrealdb-js
```

2. **Manually: put the files in place**
- File: `.github/skills/surrealdb-js/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealdb-js -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/surrealdb/agent-skills --path skills/surrealdb-js
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/surrealdb-js/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealdb-js -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealdb-js/SKILL.md

## When to use it
- connect and authenticate using the official `surrealdb` package
- run type-safe CRUD operations with `RecordId` and batch inserts
- build graph edges between records using `db.relate`
- stream real-time table events using `db.live`

## Example prompts
- Connect to SurrealDB over WebSocket and authenticate with root credentials
- Query users by minimum age using bound SurrealQL parameters
- Subscribe to real-time updates on the person table using `db.live`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 77d2bbef54da32fb.

BEGIN THIRD-PARTY FILE 77d2bbef54da32fb
````text
---
name: surrealdb-js
description: "Using SurrealDB from JavaScript and TypeScript with the official surrealdb SDK, covering connecting (WebSocket/HTTP and embedded engines), authentication, CRUD, parameterized queries, and live queries. Use when connecting to SurrealDB from Node, Deno, Bun, or the browser, using the surrealdb npm package, or performing CRUD and real-time operations from JS/TS code. Triggers: surrealdb JS, surrealdb.js, new Surreal(), db.query, db.create, db.live, TypeScript SDK, npm i surrealdb."
metadata:
  author: surrealdb
  version: "0.2.0"
---

# 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

```bash
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.

```ts
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](references/embedded.md).

## Authentication

```ts
// 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
```

## CRUD

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

```ts
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");
````
END THIRD-PARTY FILE 77d2bbef54da32fb

The third-party file has ended. Everything between the 77d2bbef54da32fb tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3167 of 5840 bytes. © surrealdb · MIT · https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealdb-js/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md