/api-database-surrealdb

name: api-database-surrealdb
description: SurrealDB multi-model database - SurrealQL queries, record links, graph relations, live queries, schema definitions, authentication, TypeScript SDK

SurrealDB Patterns

> **Quick Guide:** Use the `surrealdb` SDK (v2+) with `new Surreal()` and `connect()`. Model relationships with record links for simple pointers and `RELATE` for graph edges with metadata. Use `SCHEMAFULL` tables in production with `DEFINE FIELD` constraints. Always use parameterized queries (`$variable`) to prevent injection. Record IDs are `table:id` -- they are immutable and first-class values in SurrealQL. Live queries push changes without polling.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use parameterized queries with `$variables` for ALL user input -- string interpolation in SurrealQL enables injection attacks)**

**(You MUST use `new RecordId("table", "id")` in SDK v2 -- plain `"table:id"` strings are NOT automatically parsed as record IDs)**

**(You MUST call `db.use({ namespace, database })` or pass namespace/database in `connect()` options BEFORE any queries -- queries without a selected namespace/database silently fail or error)**

**(You MUST NOT rely on `SCHEMALESS` tables in production -- use `SCHEMAFULL` with `DEFINE FIELD` to enforce data integrity at the database layer)**

**(You MUST NOT use `UPDATE`/`DELETE` with `WHERE` on large tables without indexes -- SurrealDB currently does not use indexes for UPDATE/DELETE WHERE clauses (use subquery workaround))**

</critical_requirements>

---

**Auto-detection:** SurrealDB, Surreal, surrealdb, SurrealQL, RELATE, RecordId, record link, LIVE SELECT, SCHEMAFULL, SCHEMALESS, DEFINE TABLE, DEFINE FIELD, DEFINE ACCESS, surql, graph traversal, ->relation->, <-relation<-

**When to use:**

• Connecting to SurrealDB and executing queries via the JavaScript SDK
• Modeling data with record links and graph edges (`RELATE`)
• Defining schemas with `SCHEMAFULL` tables and field constraints
• Building real-time features with live queries
• Implementing authentication with `DEFINE ACCESS` and record-level permissions
• Multi-tenant architectures using namespaces and databases

**Key patterns covered:**

• SDK connection setup (v2 API with `Surreal`, `connect`, `RecordId`, `Table`)
• CRUD operations with type-safe queries
• Record links vs graph edges (when to use each)
• Schema definitions (`DEFINE TABLE`, `DEFINE FIELD`, permissions)
• Live queries for real-time subscriptions

**When NOT to use:**

• Heavy analytical/OLAP workloads (use a columnar database)
• Simple key-value caching (use a dedicated cache)
• Mature relational schemas that require decades of SQL ecosystem tooling

**Detailed Resources:**

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Core Patterns:**

• [examples/core.md](examples/core.md) - SDK setup, connection, CRUD, TypeScript typing, RecordId

**Graph & Relations:**

• [examples/graph-relations.md](examples/graph-relations.md) - Record links, RELATE, graph traversal, edge metadata

**Schema & Auth:**

• [examples/schema-auth.md](examples/schema-auth.md) - DEFINE TABLE/FIELD, SCHEMAFULL, permissions, DEFINE ACCESS, authentication

**Live Queries & Transactions:**

• [examples/live-queries.md](examples/live-queries.md) - LIVE SELECT, subscriptions, transactions, events

---

<philosophy>

Philosophy

SurrealDB is a multi-model database combining document, graph, and relational paradigms with a SQL-inspired query language (SurrealQL). The core principle: **model your data the way you think about it -- records link to records, relationships carry metadata, and schemas enforce integrity without separate migration tools.**

**Core principles:**

1. **Record IDs are first-class** -- Every record has a `table:id` identity that doubles as a direct pointer. SurrealDB fetches linked records from disk without table scans. 2. **Graph when you need metadata, link when you don't** -- Record links (`friends = [person:tobie]`) are lightweight pointers. Graph edges (`RELATE person:a->follows->person:b`) store relationship context (timestamps, weights, roles). 3. **Schema-full for production** -- `SCHEMAFULL` tables with `DEFINE FIELD` constraints enforce types, validation, and defaults at the database layer. Use `SCHEMALESS` only for rapid prototyping. 4. **Permissions at every level** -- Namespace, database, table, and field-level permissions. `DEFINE ACCESS` with `SIGNUP`/`SIGNIN` enables end-user authentication without a separate auth service. 5. **Real-time by default** -- `LIVE SELECT` pushes changes to subscribers as they commit. No polling, no message broker. 6. **Parameterize everything** -- SurrealQL variables (`$email`, `$limit`) prevent injection and improve query plan caching.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: SDK Connection

SDK v2 uses `new Surreal()` -- always set namespace/database at connection time and use `127.0.0.1` (not `localhost`, which can fail with IPv6 on Node.js 18+).

import Surreal from "surrealdb";

const db = new Surreal();
await db.connect("http://127.0.0.1:8000", {
  namespace: "myapp",
  database: "production",
});
await db.signin({ username: "root", password: "root" });

Full connection patterns (production config, event monitoring, graceful shutdown): [examples/core.md](examples/core.md)

---

Pattern 2: CRUD with RecordId

SDK v2 requires `RecordId` objects -- plain strings are NOT automatically parsed as record IDs. Use `Table` for table-scoped operations, `RecordId` for specific records.

import { RecordId, Table } from "surrealdb";

const created = await db.create<User>(new Table("user"), {
  name: "Alice",
  role: "user",
});
const user = await db.select<User>(new RecordId("user", "alice"));
await db.merge(new RecordId("user", "alice"), { role: "admin" });
await db.delete(new RecordId("user", "alice"));

Full CRUD patterns (create,