surrealkit

SurrealKit

SurrealDB のスキーマ管理およびマイグレーション用 CLI、SurrealKit を操作するためのスキルです。SurrealKit 1.0（現在は 1.0.0-beta.3）を対象にしています。

SurrealKit は、SurrealDB のデータベースを .surql スキーマファイルと同期させます。開発向けの高速な宣言型 sync と、共有データベースや本番データベース向けの、段階を制御した rollout という相補的な 2 つのワークフローに加え、シードデータの投入、静的解析、型生成、宣言型テストフレームワークを提供します。

このスキルを使用する場面

次のガイドラインが必要な場合に参照してください。

• 新しい SurrealDB プロジェクトをスキャフォールディングする（surrealkit init）、またはテンプレートを作成する
• 開発環境でスキーマ変更を適用する（surrealkit sync）
• 本番マイグレーションを計画、実行、またはロールバックする（surrealkit rollout）
• 既存のデータベースで SurrealKit を導入する（surrealkit rollout baseline）
• スキーマを個別に追跡するモジュールに分割する、または複数のデータベースに適用する
• データベースを使わずに、スキーマに対して SurrealQL を静的にチェックする（surrealkit check）
• ライブスキーマから JSON または TypeScript の型を生成する（surrealkit typegen）
• スキーマ、権限、または API エンドポイント用の宣言型テストを作成または実行する（surrealkit test）

このスキルでは SurrealKit ツール自体を扱います。.surql ファイルに記述する実際のスキーマ、シード、クエリの文を書くには、surrealql スキルを使用してください。

インストール

方法	コマンド
cargo binstall（推奨）	cargo binstall surrealkit
Cargo（ソースから）	cargo install surrealkit
Docker	docker pull ghcr.io/surrealdb/surrealkit:latest
ビルド済み tarball	GitHub Releases

ソースからビルドするには、C コンパイラーと cmake が必要です。静的解析はデフォルトで有効になっており、tree-sitter（約 7.5 MiB、ビルド時間約 100 秒）が追加されます。cargo install surrealkit --no-default-features --features kv-mem,cli を使うと無効にできます。このバイナリでは check、generate、watch は使用できません。ビルド済みバイナリと cargo binstall には、常に解析機能が含まれます。

Docker イメージは distroless（約 25 MB、uid 65532）で、処理が完了すると終了します。そのため、SurrealDB とともに Docker Compose で実行する「スキーマを適用してからテストを実行する」パイプラインに適しています。

コマンド一覧

コマンド	目的	リファレンス
surrealkit init	テンプレートからプロジェクトをスキャフォールディングし、オプション機能を選択する	init-templates.md
surrealkit sync	スキーマファイルに合わせてデータベースを宣言的に調整する（開発環境）	sync-rollouts.md
surrealkit rollout <sub>	マイグレーションを計画、ステージング、完了、ロールバック、修復する（共有／本番環境）	sync-rollouts.md
surrealkit seed [--force]	database/seed/ のシードファイルを実行する（冪等、ハッシュで追跡）	sync-rollouts.md
surrealkit check	プロジェクトの SurrealQL を静的に解析する（データベースには接続しない）	static-analysis.md
surrealkit generate / watch	埋め込みクエリ用の型付きクライアントを生成する／継続的に更新する	static-analysis.md
surrealkit typegen	ライブ DB をイントロスペクションし、JSON／TypeScript の型を生成する	typegen.md
surrealkit test	宣言型 TOML テストスイートを実行する	testing.md
surrealkit apply <path>	単一の .surql ファイルを直接適用する	—
surrealkit setup	database/setup.surql を実行する（SurrealKit 独自のメタデータテーブル）	—
surrealkit status	同期／ロールアウトの状態を表示する	—

インストール済みバージョンで利用できるフラグを確認するには、surrealkit <command> --help を実行してください。

接続と設定

グローバルフラグはすべてのコマンドで使用でき、次の順序で解決されます（左側ほど優先されます）。 surrealkit.toml の [target.<name>] > CLI フラグ > システム環境変数 > .env ファイル > デフォルト値。

surrealkit --host http://localhost:8000 --ns my_ns --db my_db \
  --user root --pass root --auth-level root sync

フラグ	環境変数	デフォルト値
--host	SURREALDB_HOST	http://localhost:8000
--ns	SURREALDB_NAMESPACE	db
--db	SURREALDB_NAME	test
--user	SURREALDB_USER	root
--pass	SURREALDB_PASSWORD	root
--auth-level	SURREALDB_AUTH_LEVEL	root（root / namespace|ns / database|db / none）
--folder	SURREALDB_FOLDER	./database
--connect-timeout-secs	SURREALDB_CONNECT_TIMEOUT_SECS	30（0 の場合は無期限に待機します）
--query-timeout-secs	SURREALDB_QUERY_TIMEOUT_SECS	未設定（ロールアウト手順の SQL は無期限に待機します）

DATABASE_* エイリアスは 1.0 で削除されました。 SURREALDB_* に置き換えずに設定すると、フォールバックは行われず、致命的なエラーになります。アップグレード時に .env ファイルと CI を更新してください。

選択フラグもグローバルです。-s/--schema <name>、-t/--target <name>、--all、--keep-going、--no-deps については、modules-targets.md を参照してください。

プロジェクトのルートには、[variables]、[typegen]、[analyze]、[schema.*]、[target.*] セクションを含む surrealkit.toml を配置します。

埋め込みデータベース

インプロセスのデータストアを管理するには、埋め込みエンドポイントを --host に指定します。認証は自動的にスキップされます。

surrealkit --host surrealkv://./data --ns my_ns --db my_db sync

スキーム：surrealkv://、rocksdb://、speedb://、mem://、file://、tikv://。--auth-level none を指定すると、どのエンドポイントでもサインインしない方式が強制されます。ビルド済み CLI バンドルに含まれるのはインメモリエンジンのみです。ディスク上のエンジンを使用するには、--features kv-surrealkv（または kv-rocksdb、embedded）を指定してビルドしてください。埋め込みエンジンは排他的ロックを取得するため、CLI で実行する前にアプリケーションを停止してください。アプリケーションの起動時に内部からスキーマを管理する場合は、代わりにライブラリを使用してください。

テンプレート変数

任意の .surql ファイル（スキーマ、シード、ロールアウト SQL）で ${VAR_NAME} トークンを使用できます。名前の大文字と小文字は区別されません。値は次の順序で解決されます（左側ほど優先されます）。

1. --var KEY=VALUE CLI フラグ（複数回指定可能）
2. SURREALKIT_VAR_<KEY> 環境変数
3. surrealkit.toml の [variables] セクション

# surrealkit.toml
[variables]
schema_prefix = "myapp"
talent_username = "talent_rw"

surrealkit sync --var schema_prefix=acme --var talent_username=talent_rw

• 未定義の変数は致命的なエラーになります。SurrealKit が変数を黙ってスキップしたり、SQL 内にトークンを残したりすることはありません。
• 文字列 ${...} をそのまま記述するには、ドル記号を 2 つ重ねます：$${literal}。
• 置換はテキスト上で行われるため、SurrealQL の文字列リテラル内にある ${VAR} も置換されます。
• 置換は sync、seed、apply、rollout start/complete/rollback で実行されます。rollout plan/baseline/status/lint では実行されません（ユーザー SQL が実行されないためです）。

プロジェクト構成

surrealkit init を実行すると、database/ ディレクトリが作成されます（--folder / SURREALDB_FOLDER でルートを変更できます）。

database/
├── schema/                     # Schema definitions (.surql) — the default module, the source of truth
├── modules/<name>/schema/      # Additional schema modules, when declared in surrealkit.toml
├── rollouts/                   # Generated rollout manifests (.toml)
├── snapshots/                  # Drift tracking — what `rollout plan` diffs against
│   ├── schema_snapshot.json
│   └── catalog_snapshot.json
├── seed/                       # Seeding files (.surql)
├── tests/
│   ├── suites/                 # Test suites (.toml)
│   ├── fixtures/               # Test fixture data (.surql)
│   └── config.toml             # Global test config
└── setup.surql                 # One-time setup script (SurrealKit's own metadata tables)
surrealkit.toml                 # Project config

SurrealKit は、データベース内の 3 つのメタデータテーブルで独自の状態を追跡します。__entity（ファイルハッシュと定義ごとのレコード）、__rollout（ロールアウト実行状態）、__seed（シードファイルのハッシュ）です。

ルールと規約

• sync と rollout の使い分け： ローカル、プレビューなど、ファイルにすぐ合わせても問題のない破棄可能なデータベースには sync を使用します。レビュー、段階的な実行、ロールバック、またはオペレーターが制御する切り替えが必要な共有／本番データベースには rollout を使用します。
• スキーマファイルが信頼できる唯一の情報源です。sync は、スキーマディレクトリに合わせて SurrealKit が管理するオブジェクトを作成、更新、削除します。
• スキーマファイルには DEFINE／REMOVE ステートメントを記述してください。--allow-all-statements を指定した場合に限り、ほかのステートメント（INSERT、UPDATE、CREATE）を許可できます。このオプションを指定すると、カタログのエンティティ追跡は無効になります。
• rollout plan はライブデータベースではなく database/snapshots/ と差分を比較し、sync はスナップショットを書き込みません。 sync のみで作業していた期間を経て rollout を導入する場合は、最初に rollout baseline を実行してください。そうしないと、最初の plan ですべてのファイルが提案されます。
• 生成されたマニフェストと更新したスナップショットは、必ず一緒にコミットしてください。plan を取り消す場合は、両方を元に戻します。
• SurrealQL は .surql 拡張子のファイルに保存してください。生成された SurrealQL の検証とフォーマットには、surrealql スキルに記載されているツール（surreal validate、npx @surrealdb/surql-fmt）を使用し、CI では surrealkit check を使ってチェックします。
• SurrealKit はまだ新しく、発展途上です。コマンドの仕様は surrealkit --help と README で確認してください。

Rust ライブラリとして SurrealKit を使用する

surrealkit クレートを使うと、アプリケーション内から sync、seed、rollout を実行できます。これは、起動時にスキーマを適用する場合や、CLI ではロックを保持できない組み込みエンジンで役立ちます。

[dependencies]
surrealkit = { version = "1.0.0-beta.3", default-features = false, features = ["kv-mem"] }

• default = ["kv-mem", "cli"] です。ライブラリの利用者は cli を外して、clap、inquire、rustls、tempfile への依存をなくせます。
• embed_schema! と embed_seed! は、スキーマファイルと seed ファイルをバイナリにコンパイルするため、実行時にファイルシステムは必要ありません。
• Sync は実行時の制御に使うビルダーです。1.0 以降、Rollout はディスクへの書き込みを行いません。
• 進捗は log ファサードを通じて出力されます。ロガーがない場合、ライブラリは何も出力しません。

API の完全なリファレンス：crates/surrealkit/README.md。アップグレードに関する注意事項：MIGRATING.md。

参考資料

• プロジェクトのひな形とテンプレート — references/init-templates.md
• 開発環境での sync、本番環境での rollout、seed の適用 — references/sync-rollouts.md
• スキーマモジュールとデータベースターゲット — references/modules-targets.md
• 静的解析（check／generate／watch） — references/static-analysis.md
• 型生成（JSON と TypeScript） — references/typegen.md
• 宣言型テストフレームワーク — references/testing.md