24601/surreal-skills

SurrealDB 3 エキスパートスキル

GitHub Copilot 向けのエキスパートレベル SurrealDB 3 アーキテクチャ、開発、運用スキル。

Copilot がこのスキルを使用するタイミング

以下の場合に自動的にアクティブ化します：

• ユーザーが SurrealQL クエリを作成・質問する
• .surql ファイルを扱う
• SurrealDB のデータベーススキーマを設計する
• SurrealDB のデプロイメントや Docker を設定する
• SurrealDB SDK（JavaScript、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby）を使用する
• グラフ関係（RELATE、トラバーサル）を扱う
• ベクトル検索や RAG パターンを実装する
• セキュリティ、権限、アクセス制御を設定する
• Surrealism WASM 拡張を構築する
• 他のデータベースから SurrealDB へデータを移行する
• SurrealDB を MCP ホスト、n8n、AI フレームワーク、カスタムエディタに接続する

ルールリファレンス

このスキルには 18 の詳細なルールファイルが含まれています。ユーザーのリクエストがそのドメインに一致する場合、関連するルールファイルを読み込んでください：

ルールファイル	読み込むタイミング	ドメイン
surrealql.md	SurrealQL クエリの記述・デバッグ時	SurrealQL 言語完全リファレンス
data-modeling.md	スキーマ設計、フィールドタイプ選択、レコード ID	マルチモデルスキーマ設計パターン
graph-queries.md	RELATE、グラフトラバーサル、パス式	グラフエッジとトラバーサルパターン
vector-search.md	HNSW インデックス、類似検索、埋め込み	ベクトル検索と RAG パイプライン
security.md	権限、認証、JWT、アクセス制御	行レベルセキュリティと認証フロー
deployment.md	SurrealDB のインストール、設定、実行	ストレージエンジン、Docker、Kubernetes
performance.md	低速クエリ、インデックス戦略、EXPLAIN	パフォーマンスチューニングと最適化
sdks.md	アプリケーションコードからの SurrealDB 使用	JS、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby パターン
surrealism.md	WASM 拡張の記述	Rust から WASM への拡張開発
surrealml.md	SurrealML 周辺の作業	プレビュー .surml 境界とネイティブ依存関係警告
surrealmcp.md	AI ホストの接続	MCP ツールカタログとデプロイメント
editor-tooling.md	エディタ/IDE サポート	LSP、tree-sitter、CodeMirror、エディタ拡張
langchain.md	LangChain RAG	Python ベクトルストア API
ecosystem-integrations.md	n8n/フレームワーク参照	n8n、AI フレームワークドキュメント、Spectron 境界、Agent Skills
surrealist.md	Surrealist IDE/GUI の使用	IDE 機能とスキーマデザイナー
surreal-sync.md	他のデータベースからの移行	Postgres、Mongo などからの CDC 同期
surrealfs.md	AI エージェントファイルシステム操作	SurrealDB をバックエンドにした仮想ファイルシステム
surrealkit.md	スキーマ同期、ロールアウト、シード、宣言的テスト	SurrealDB アプリ向けの望ましい状態スキーマ管理

クイックリファレンス

SurrealQL 基本

-- レコード作成
CREATE person:alice SET name = 'Alice', age = 30;

-- グラフエッジ
RELATE person:alice->follows->person:bob SET since = time::now();

-- グラフトラバーサル
SELECT ->follows->person.name AS following FROM person:alice;

-- ベクトル検索（HNSW）
DEFINE INDEX idx_embed ON document FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
SELECT * FROM document WHERE embedding <|10,40|> $query_vector;

-- 行レベル権限
DEFINE TABLE post SCHEMALESS PERMISSIONS
  FOR select WHERE published = true OR user = $auth.id
  FOR create, update WHERE user = $auth.id;

-- ライブクエリ
LIVE SELECT * FROM person WHERE age > 25;

主要な概念

• レコード ID: table:id（例：person:alice）— 第一級市民、JOIN 不要
• マルチモデル: ドキュメント + グラフ + ベクトル + 時系列 + 地理空間を 1 つの DB で
• グラフ演算子: ->（外向き）、<-（内向き）、<->（双方向）
• KNN 演算子: <|K,EF|> で K=近傍数、EF=検索パラメータ（距離指標ではない）
• ストレージエンジン: memory、RocksDB、SurrealKV（タイムトラベル）、TiKV（分散）
• WASM 拡張: v3 の新機能 — Rust を書き、WASM にコンパイルし、DEFINE MODULE で登録

スクリプト

# ヘルスチェック
uv run scripts/doctor.py

# スキーマイントロスペクション
uv run scripts/schema.py introspect

# 上流の更新をチェック
uv run scripts/check_upstream.py

セキュリティ注意事項

• 例ではローカル開発専用に root/root を使用しています。本番環境ではスコープ付き認証情報を使用してください。
• スクリプトはユーザー指定のエンドポイントのみに接続します。サードパーティへのネットワーク呼び出しはありません。
• テーブル名はクエリ補間前に [a-zA-Z_][a-zA-Z0-9_]* に対して検証されます。
• リモートシェルインストーラよりも、パッケージマネージャーまたはコンテナインストールを推奨します。