24601/surreal-skills

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 を使用しています。本番環境や共有インスタンスではデフォルト認証情報を使用しないでください。非ローカル環境では、スコープ付きの最小権限ユーザーを作成してください。

# ローカル開発専用：SurrealDB をインメモリで起動
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# 永続的な RocksDB ストレージで起動（ローカル開発）
surreal start rocksdb://data/mydb.db --user root --pass root

# SurrealKV で起動（タイムトラベルクエリ対応、ローカル開発）
surreal start surrealkv://data/mydb --user root --pass root

# CLI REPL 経由で接続（ローカル開発）
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# SurrealQL ファイルをインポート
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# データベースをエクスポート
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# バージョン確認
surreal version

# スキルのヘルスチェックを実行
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、サブクエリ、トランザクション、フューチャー、およびすべての組み込み関数（配列、暗号、期間、地理、数学、メタ、オブジェクト、パース、ランダム、文字列、時間、型、ベクトル）。

参照：rules/surrealql.md

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

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

参照：rules/data-modeling.md

グラフクエリ

JOIN 不要のファーストクラスのグラフトラバーサル。RELATE でレコード間に型付きエッジを作成。->（出力）、<-（入力）、<->>（双方向）演算子でトラバース。任意の深さでフィルタリング、集約、再帰が可能。

参照：rules/graph-queries.md

ベクトル検索

HNSW インデックスを使用した組み込みベクトル類似性検索（v3 ベクトルインデックスタイプ。ブルートフォースはインデックス構築/再構築中のフォールバックとして利用可能）。ベクトルフィールドを定義し、設定可能な距離メトリック（コサイン、ユークリッド、マンハッタン、ミンコフスキー）でインデックスを作成し、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 統合

公式 SDK：JavaScript/TypeScript（Node.js、Deno、Bun、ブラウザ）、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift（iOS/macOS/visionOS）、Ruby。ソースのみの 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] エクストラが安定した文書化された境界です。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 サブコマンドが必要です。ツールのワイヤーネームはスネークケース：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 をベクトルストアとして公開します。JS パッケージ、async クラス、チャット履歴、および v1.4.0 のハイブリッドレトリーバーは 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 -- 他のデータベースからの移行のための Change Data Capture（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 ブートストラップではありません（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 セクション）

ドクター / ヘルスチェック

# 完全診断（stderr に Rich 出力、stdout に JSON）
uv run {baseDir}/scripts/doctor.py

# クイックチェック（終了コード 0 = 正常、1 = 問題あり）
uv run {baseDir}/scripts/doctor.py --check

# 特定のエンドポイントをチェック
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

ドクタースクリプトは以下を確認します：surreal CLI がインストールされ PATH に存在するか、サーバーに到達可能か、認証が成功するか、名前空間とデータベースが存在するか、バージョンの互換性、ストレージエンジンの状態。

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

# 完全スキーマダンプ（全テーブル、フィールド、インデックス、イベント、アクセス）
uv run {baseDir}/scripts/schema.py introspect

# サマリー付きでテーブル一覧表示
uv run {baseDir}/scripts/schema.py tables

# 特定のテーブルを検査
uv run {baseDir}/scripts/schema.py table <table_name>

# スキーマを SurrealQL としてエクスポート（再現可能な DEFINE ステートメント）
uv run {baseDir}/scripts/schema.py export --format surql

# スキーマを 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	望ましい状態のスキーマ同期、ロールアウトベースのマイグレーション、シーディング、宣言的 DB テスト
rules/gotchas.md	クロスドメインのエッジケースと落とし穴：アップグレード、グラフ、ベクトル、セキュリティ、MCP、SDK（v3.1.4+）

ワークフロー例

すべてのワークフロー例はローカル開発専用に root/root を使用しています。 本番環境では、スコープ付きの最小権限資格情報を持つ DEFINE USER を使用してください。

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

# 1. 環境を確認
uv run {baseDir}/scripts/doctor.py

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

# 3. スキーマを設計（ガイダンスについては rules/data-modeling.md を参照）
# 4. 初期スキーマをインポート
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

# 5. イントロスペクションで確認
uv run {baseDir}/scripts/schema.py introspect

Surr からの移行

…[翻訳のため省略]