surrealdb-js

SurrealDB JavaScript SDK

公式 SDK（npm の surrealdb）は、Node.js、Deno、Bun、ブラウザーで動作します。WebSocket／HTTP 経由でリモートの SurrealDB インスタンスに接続するか、プロセス内で組み込みエンジンを実行します。最新の安定版 surrealdb を対象としてください。ユーザーが特定のバージョンを必要としている場合を除き、バージョンを固定せずにインストールしてください（npm i surrealdb）。

インストール

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

接続とネームスペース／データベースの選択

必ず connect を実行し、次にネームスペースとデータベースを use で選択してから、認証してください。処理が終わったら接続を閉じてください。

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();

surreal start -u root -p root rocksdb:mydb（またはインメモリの場合は surreal start -u root -p root）でローカルサーバーを起動します。サーバーなしでプロセス内に SurrealDB を実行する方法については、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: "[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

テーブルは文字列（"person"）として渡すか、特定のレコードには RecordId を渡します。RecordId、Table、Duration、Decimal、その他の値クラスについては、references/data-types.md を参照してください。

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) は生の SurrealQL を実行し、各ステートメントにつき 1 つのエントリーを含む配列を返します。ユーザー入力は必ずバインドパラメーターで渡し、文字列補間は決して使わないでください。

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") },
);

その他のヘルパー：db.let(name, value)／db.unset(name) は、後続のクエリで $name として使えるセッションパラメーターを設定します。db.run(fnName, version, args) は定義済み関数を呼び出します。db.queryRaw() は解析されていない RPC レスポンス（ステートメントごとのステータスと実行時間）を返します。

ライブクエリ

db.live() でテーブルのリアルタイム変更を購読します。WebSocket（または組み込み）接続が必要で、HTTP には対応していません。詳しくは 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

リファレンス

• references/data-types.md — RecordId、Table、Duration、Decimal、Uuid、ジオメトリ、CBOR マッピング。
• references/embedded.md — @surrealdb/node を使った組み込みエンジン（RocksDB／SurrealKV／インメモリ）と、@surrealdb/wasm（インメモリ／IndexedDB）。
• references/live-queries.md — live、subscribeLive、kill のパターン。

リソース

• SDK ドキュメント
• GitHub リポジトリ