surrealdb

SurrealDB 3 スキル

SurrealDB 3 のアーキテクチャ、開発、運用に関するエキスパートレベルの知識を提供します。SurrealQL、マルチモデルのデータモデリング、グラフ走査、ベクトル検索、セキュリティ、デプロイ、パフォーマンスチューニング、SDK 統合、および SurrealKit、SurrealMCP、n8n、CodeMirror、エージェントスキルのインターフェースを含む、幅広い SurrealDB エコシステムを網羅します。

AI エージェント向け

機能マニフェスト、判断ツリー、出力コントラクトの全容を確認できます。

uv run {baseDir}/scripts/onboard.py --agent

構造化されたブリーフィングの全容については、AGENTS.md を参照してください。

コマンド	内容
uv run {baseDir}/scripts/doctor.py	ヘルスチェック：surreal CLI、接続、バージョンを確認します
uv run {baseDir}/scripts/doctor.py --check	合否のみを確認するクイックチェック（終了コードのみ）
uv run {baseDir}/scripts/schema.py introspect	実行中の SurrealDB インスタンスのスキーマ全体を出力します
uv run {baseDir}/scripts/schema.py tables	すべてのテーブルをフィールド数とインデックスとともに一覧表示します
uv run {baseDir}/scripts/onboard.py --agent	エージェント統合用の JSON 機能マニフェスト

前提条件

• surreal CLI -- brew install surrealdb/tap/surreal（macOS）またはインストール手順を参照してください
• Python 3.10+ -- スキルのスクリプトに必要です
• uv -- brew install uv（macOS）、pip install uv、またはuv のドキュメントを参照してください

任意：

• Docker -- コンテナ化された SurrealDB インスタンス用（docker run surrealdb/surrealdb:v3）
• 任意の SDK -- JavaScript、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby

セキュリティに関する注意：このスキルでは、パッケージマネージャーとコンテナによるインストールのみを説明しています。 リモートのワンライナー形式のシェルインストーラーではなく、Homebrew、apt/dnf、Cargo、npm、Docker を通じて監査可能なインストールを行うことを推奨します。

クイックスタート

認証情報に関する警告：以下の例では、ローカル開発のみを対象として root/root を使用しています。本番環境や共有インスタンスでは、デフォルトの認証情報を決して使用しないでください。 ローカル以外の環境では、権限を必要最小限に限定したユーザーを作成してください。

# Start SurrealDB in-memory for LOCAL DEVELOPMENT ONLY
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Start with persistent RocksDB storage (local dev)
surreal start rocksdb://data/mydb.db --user root --pass root

# Start with SurrealKV (time-travel queries supported, local dev)
surreal start surrealkv://data/mydb --user root --pass root

# Connect via CLI REPL (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Import a SurrealQL file
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# Export the database
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# Check version
surreal version

# Run the skill health check
uv run {baseDir}/scripts/doctor.py

環境変数

変数	説明	デフォルト値
SURREAL_ENDPOINT	SurrealDB サーバーの URL	http://localhost:8000
SURREAL_USER	ルートまたは名前空間のユーザー名	root
SURREAL_PASS	ルートまたは名前空間のパスワード	root
SURREAL_NS	デフォルトの名前空間	test
SURREAL_DB	デフォルトのデータベース	test

これらは surreal sql CLI のフラグ（--endpoint、--user、--pass、--ns、--db）に直接対応し、SurrealDB 公式 SDK で認識されます。

主な機能

SurrealQL の習得

SurrealQL クエリ言語を幅広く網羅します。CREATE、SELECT、UPDATE、UPSERT、DELETE、RELATE、INSERT、LIVE SELECT、DEFINE、REMOVE、INFO、サブクエリ、トランザクション、future、すべての組み込み関数（array、crypto、duration、geo、math、meta、object、parse、rand、string、time、type、vector）を扱います。

参照先：rules/surrealql.md

マルチモデルのデータモデリング

SurrealDB のマルチモデル機能を活用するスキーマを設計できます。ドキュメントコレクション、グラフエッジ、リレーショナル参照、ベクトル埋め込み、時系列データ、地理空間座標を、単一のデータベースと単一のクエリ言語で扱います。

参照先：rules/data-modeling.md

グラフクエリ

JOIN を使わずに、第一級の機能としてグラフ走査を実行できます。RELATE でレコード間に型付きエッジを作成します。->（出方向）、<-（入方向）、<->（双方向）の演算子で走査します。任意の深さでフィルタリング、集計、再帰を行えます。

参照先：rules/graph-queries.md

ベクトル検索

HNSW インデックス（v3 のベクトルインデックス型。インデックスのビルド／再ビルド中はフォールバックとして総当たり検索を利用可能）を使用した、組み込みのベクトル類似性検索機能です。ベクトルフィールドを定義し、設定可能な距離メトリクス（cosine、euclidean、manhattan、minkowski）を使ってインデックスを作成し、vector::similarity::* 関数でクエリできます。RAG パイプラインやセマンティック検索を SurrealQL 内で直接構築できます。

参照先：rules/vector-search.md

セキュリティと権限

DEFINE TABLE ... PERMISSIONS による行レベルセキュリティ、名前空間／データベース／レコードレベルのアクセス制御、JWT／トークンベース認証のための DEFINE ACCESS、システムユーザーのための DEFINE USER、権限述語用の $auth／$session 実行時変数を使用します。

参照：rules/security.md

デプロイと運用

単一バイナリでのデプロイ、Docker、Kubernetes（Helm チャート）、ストレージエンジンの選択（メモリ、RocksDB、SurrealKV、分散環境向けの TiKV）、バックアップ／復元、監視、本番環境向けの強化を扱います。

参照：rules/deployment.md

パフォーマンスのチューニング

インデックス戦略（一意、検索、ベクトル HNSW）、EXPLAIN によるクエリ最適化、コネクションプーリング、ストレージエンジンのトレードオフ、一括操作、リソース制限を扱います。

参照：rules/performance.md

SDK 統合

JavaScript／TypeScript（Node.js、Deno、Bun、ブラウザー）、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift（iOS／macOS／visionOS）、Ruby 向けの公式 SDK を用意しています。ソースのみの C バインディング、未リリースの Python v3 API 境界、.NET v0.10.2 ベータ版の機能範囲、接続プロトコル、認証フロー、ライブクエリのサブスクリプション、型付きレコードの処理も含みます。

参照：rules/sdks.md

Surrealism WASM 拡張機能

SurrealDB 3 の新機能：Rust で記述して WASM にコンパイルしたカスタム関数、アナライザー、ロジックでデータベースを拡張できます。Surrealism モジュールを定義、デプロイ、管理します。

参照：rules/surrealism.md

SurrealML データベース内推論（プレビュー／不安定）

surrealml には GitHub の v0.1.2 リリースがありますが、このスナップショット時点では PyPI で公開されている最新パッケージは surrealml 0.0.4 です。.surml アーティファクト形式と [sklearn]、[torch]、[tensorflow] extras が、安定して文書化されている範囲です。DEFINE MODEL、INFO FOR MODEL、REMOVE MODEL、ml::name<version>(...)、surreal ml import、db.upload_ml(...)、および SurMlFile.from_<framework>(...) ファクトリーメソッドに関する v1.4.0 のドキュメントは、v1.4.1 で撤回されました。現在の Python セットアップ手順では、LOCAL_BUILD=TRUE を指定しない限り GitHub Releases からネイティブライブラリをダウンロードするため、本番環境で使用する前にバージョンを固定して監査してください。

参照：rules/surrealml.md

SurrealMCP -- Model Context Protocol サーバー

公式 MCP サーバー（surrealdb/surrealmcp）を使うと、MCP 対応の AI ホスト（Claude Desktop、Cursor、VS Code の GitHub Copilot、Zed、n8n）から、設定を 1 つ追加するだけで SurrealDB の読み書きができます。ソース（cargo install --path .）または Docker からインストールします。crates.io と npm では公開されていません。バイナリの実行には start サブコマンドが必要です。ツールのワイヤー名は snake_case です：query、select、insert、create、upsert、update、delete、relate、connect_endpoint、use_namespace、use_database、list_namespaces、list_databases、disconnect_endpoint、およびクラウドツール。

参照：rules/surrealmcp.md、skills/surrealmcp/SKILL.md

エディターツール

surrealql-language-server v0.1.3 はファーストパーティの LSP 基準です。surql-lsp v0.1.1 は、これとは別のコミュニティ製クレートです。このルールでは、tree-sitter、ファーストパーティのエディター拡張機能、カスタム Web エディター向けの @surrealdb/codemirror／@surrealdb/lezer v1.0.5 を追跡しています。拡張機能ごとのコマンドパレットと設定については、引き続き各拡張機能の README を一次情報として参照してください。

参照：rules/editor-tooling.md

LangChain 統合（Python のみ）

langchain-surrealdb 0.2.1（Python；langchain-core ~= 1.1.0、surrealdb ~= 1.0.8 v1 SDK）は、コンストラクター SurrealDBVectorStore(embeddings, conn) を通じて SurrealDB をベクトルストアとして公開します。v1.4.0 で提供されていた JS パッケージ、非同期クラス、チャット履歴、ハイブリッドリトリーバーは、v1.4.1 で撤回されました。

参照：rules/langchain.md

エコシステム統合

まだ専用ルールとして完全には整備されていない、公式ドキュメントおよびファーストパーティに近い機能を紹介します。セルフホスト可能な n8n 向けの @surrealdb/n8n-nodes-surrealdb v0.6.0、公式 AI フレームワークのドキュメント索引、ロードマップのみで紹介されている Spectron／Agent Memory Context、CodeMirror パッケージ、公式の surrealdb/agent-skills リポジトリが含まれます。ロードマップや参照ページを本番用 API として提示しないよう、このルールを活用してください。

参照：rules/ecosystem-integrations.md

エコシステムツール

• Surrealist -- SurrealDB 公式 IDE および GUI（スキーマデザイナー、クエリエディター、グラフビジュアライザー）
• Surreal-Sync -- 他のデータベースからの移行に対応する変更データキャプチャ（CDC）
• SurrealFS -- SurrealDB を基盤とする AI エージェント向けファイルシステム
• SurrealKit -- 望ましい状態とのスキーマ同期、ロールアウトベースの移行、シーディング、宣言的テスト
• SurrealML -- プレビュー段階の .surml アーティファクトツール。サーバー呼び出しのインターフェースはまだ不安定です
• SurrealMCP -- AI エージェント向け Model Context Protocol サーバー
• n8n -- セルフホスト可能な n8n ワークフロー向けの公式スコープ付きコミュニティパッケージ
• CodeMirror -- カスタムエディター向けの公式 SurrealQL 構文パッケージ
• setup-surreal -- CI ワークフローで SurrealDB を実行するための公式 GitHub Action（surrealdb/setup-surreal@v2）。CLI のブートストラップではありません（そのように説明していた v1.4.0 のドキュメントは v1.4.2 で撤回されました）

参照：rules/surrealist.md、rules/surreal-sync.md、rules/surrealfs.md、rules/surrealkit.md、rules/surrealml.md、rules/surrealmcp.md、rules/ecosystem-integrations.md、rules/deployment.md（setup-surreal のセクション）

Doctor / ヘルスチェック

# Full diagnostic (Rich output on stderr, JSON on stdout)
uv run {baseDir}/scripts/doctor.py

# Quick check (exit code 0 = healthy, 1 = issues found)
uv run {baseDir}/scripts/doctor.py --check

# Check a specific endpoint
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

doctor スクリプトは、surreal CLI がインストールされていて PATH 上にあること、サーバーに到達できること、認証が成功すること、ネームスペースとデータベースが存在すること、バージョンの互換性、ストレージエンジンの状態を確認します。

スキーマのイントロスペクション

# Full schema dump (all tables, fields, indexes, events, accesses)
uv run {baseDir}/scripts/schema.py introspect

# List tables with summary
uv run {baseDir}/scripts/schema.py tables

# Inspect a specific table
uv run {baseDir}/scripts/schema.py table <table_name>

# Export schema as SurrealQL (reproducible DEFINE statements)
uv run {baseDir}/scripts/schema.py export --format surql

# Export schema as JSON
uv run {baseDir}/scripts/schema.py export --format json

イントロスペクションでは、INFO FOR DB、INFO FOR TABLE、INFO FOR NS を使用して、スキーマ全体を再構築します。

ルールリファレンス

ルールファイル	対象範囲
rules/surrealql.md	SurrealQL の構文、ステートメント、関数、演算子、慣用表現
rules/data-modeling.md	スキーマ設計、レコード ID、フィールド型、リレーション、正規化
rules/graph-queries.md	RELATE、グラフ走査演算子、パス式、再帰クエリ
rules/vector-search.md	ベクトルフィールド、HNSW インデックス（v3 のベクトルインデックス型）、類似度関数、RAG パターン
rules/security.md	権限、アクセス制御、認証、JWT、行レベルセキュリティ
rules/deployment.md	インストール、ストレージエンジン、Docker、Kubernetes、本番環境の設定；surrealdb/setup-surreal@v2 GitHub Action（CI 専用。CLI のブートストラップではありません）
rules/performance.md	インデックス、EXPLAIN、クエリ最適化、一括操作、リソース調整
rules/sdks.md	JS/TS、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby SDK の使用方法、接続パターン、ライブクエリ
rules/surrealism.md	WASM 拡張機能、カスタム関数、Surrealism モジュールの作成
rules/surrealml.md	SurrealML のプレビュー対象範囲、.surml アーティファクト、パッケージ／リリースの境界、ネイティブ依存関係に関する警告
rules/surrealmcp.md	Model Context Protocol サーバー：ツールカタログ、ホスト設定、トランスポート、デプロイ
rules/editor-tooling.md	LSP、tree-sitter 文法、CodeMirror、VS Code / JetBrains / Neovim / Helix / Sublime / Zed 拡張機能
rules/langchain.md	LangChain Python 統合：ベクトルストア、コンストラクター API、custom_filter の境界
rules/ecosystem-integrations.md	n8n、AI フレームワークのドキュメントインデックス、Spectron ロードマップの境界、CodeMirror、公式 Agent Skills リポジトリ
rules/surrealist.md	Surrealist IDE/GUI の使用方法、スキーマデザイナー、クエリエディター
rules/surreal-sync.md	CDC 移行ツール、ソース／ターゲットコネクター、移行ワークフロー
rules/surrealfs.md	AI エージェント向けファイルシステム、ファイルストレージ、メタデータ、検索パターン
rules/surrealkit.md	望ましい状態とのスキーマ同期、ロールアウトベースの移行、シーディング、宣言的なデータベーステスト
rules/gotchas.md	ドメイン横断のエッジケースと注意点：アップグレード、グラフ、ベクトル、セキュリティ、MCP、SDK（v3.1.4 以降）

ワークフローの例

すべてのワークフロー例では、ローカル開発に限り root/root を使用します。 本番環境では、スコープを限定した最小権限の認証情報とともに DEFINE USER を使用してください。

新規プロジェクトのセットアップ

# 1. Verify environment
uv run {baseDir}/scripts/doctor.py

# 2. Start SurrealDB
surreal start rocksdb://data/myproject.db --user root --pass root

# 3. Design schema (use rules/data-modeling.md for guidance)
# 4. Import initial schema
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

# 5. Introspect to verify
uv run {baseDir}/scripts/schema.py introspect

SurrealDB v2 からの移行

# 1. Export v2 data
surreal export --endpoint http://old-server:8000 --user root --pass root \
  --ns myapp --db production v2-backup.surql

# 2. Review breaking changes (see rules/surrealql.md v2->v3 migration section)
# Key changes: range syntax 1..4 is now exclusive of end, new WASM extension system

# 3. Import into v3
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production v2-backup.surql

# 4. Verify schema
uv run {baseDir}/scripts/schema.py introspect

新しいドメインのデータモデリング

# 1. Read rules/data-modeling.md for schema design patterns
# 2. Read rules/graph-queries.md if your domain has relationships
# 3. Read rules/vector-search.md if you need semantic search
# 4. Draft schema.surql with DEFINE TABLE, DEFINE FIELD, DEFINE INDEX
# 5. Import and test
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns dev --db test schema.surql
uv run {baseDir}/scripts/schema.py introspect

本番環境へのデプロイ

# 1. Read rules/deployment.md for storage engine selection and hardening
# 2. Read rules/security.md for access control setup
# 3. Read rules/performance.md for index strategy
# 4. Run doctor against production endpoint
uv run {baseDir}/scripts/doctor.py --endpoint https://prod-surreal:8000
# 5. Verify schema matches expectations
uv run {baseDir}/scripts/schema.py introspect --endpoint https://prod-surreal:8000

上流ソースの確認

# Check if upstream SurrealDB repos have changed since this skill was built
uv run {baseDir}/scripts/check_upstream.py

# JSON-only output for agents
uv run {baseDir}/scripts/check_upstream.py --json

# Only show repos that have new commits
uv run {baseDir}/scripts/check_upstream.py --stale

追跡対象のすべてのリポジトリについて、現在の HEAD SHA とリリースタグを SOURCES.json のベースラインと比較します。これを使用して、段階的なスキル更新を計画してください。

ソースの来歴

このスキルは、2026-06-17 に以下の上流ソースを基に更新されました。

リポジトリ	リリース	スナップショット日
surrealdb/surrealdb	v3.1.4	2026-06-10
surrealdb/surrealist	surrealist-v3.9.0	2026-06-16
surrealdb/surrealdb.js	v2.0.3	2026-06-17
surrealdb/surrealdb.py	v2.0.0（PyPI）；main 3.0.0 は未リリース	2026-06-17
surrealdb/surrealkit	v0.7.0	2026-06-11
surrealdb/surrealmcp	スタンドアロン版 v0.4.0；3.1 以降は組み込み MCP	2026-06-17

ドキュメント： surrealdb.com/docs のスナップショット（2026-06-17）。

機械可読な来歴： SOURCES.json。

出力規約

このスキルのすべての Python スクリプトは、出力を 2 種類に分けるパターンに従います。

• stderr：人が読みやすい Rich 形式の出力（テーブル、パネル、ステータスインジケーター）
• stdout：AI エージェントがプログラムで処理するための機械可読な JSON

つまり、2>/dev/null を指定すると人向けの出力が非表示になり、stdout をパイプで渡すと後続処理用のクリーンな JSON が得られます。