surrealdb-cli

SurrealDB CLI

surreal コマンドラインバイナリを操作するためのスキルです。SurrealDB のオールインワンツールで、サーバーの実行、クエリの実行、データの入出力を行えます。

このスキルでは、surreal バイナリ自体の操作を扱います。このバイナリで実行する SurrealQL を記述するには surrealql スキルを、宣言的なスキーマ移行と型生成には surrealkit スキルを使用してください。

このスキルを使う場面

次の作業を行うときは、こちらのガイドラインを参照してください。

• SurrealDB サーバーをローカルまたはコンテナー内で起動する（surreal start）
• SQL シェルを開く、またはファイルからクエリをパイプで渡す（surreal sql）
• バックアップ、シード、移行のためにデータベースをインポートまたはエクスポートする（surreal import / surreal export）
• サーバーの稼働状況を条件としてスクリプトや CI の実行を制御する（surreal is-ready）
• バイナリをアップグレードする、またはアップグレード後にディスク上のストレージを修復する（surreal upgrade / surreal fix）
• SurrealML モデルをインポートまたはエクスポートする（surreal ml）

インストール

方法	コマンド
curl（macOS / Linux）	curl -sSf https://install.surrealdb.com | sh
Windows（PowerShell）	iwr https://windows.surrealdb.com -useb | iex
Homebrew	brew install surrealdb/tap/surreal
Docker	docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start

surreal version で確認してください。本番環境では、特定のイメージタグ（latest 以外）を指定してください。現在利用可能なインストール方法については、インストールドキュメントを参照してください。

コマンド一覧

コマンド	用途	リファレンス
surreal start [PATH]	選択したストレージバックエンドでデータベースサーバーを実行する	start.md
surreal sql	対話型 REPL、またはパイプ入力による非対話型クエリの実行	sql.md
surreal import <FILE>	SurrealQL スクリプトをデータベースに読み込む	import-export.md
surreal export [FILE]	データベースを SurrealQL として（ファイルまたは標準出力に）ダンプする	import-export.md
surreal is-ready	サーバーが接続を受け付けている場合に終了コード 0 を返す（エイリアス isready）	maintenance.md
surreal version	ローカルのツールとリモートサーバーのバージョンを表示する	maintenance.md
surreal upgrade	バイナリを新しいリリースに置き換える	maintenance.md
surreal fix [PATH]	ディスク上のストレージを現在の形式に移行する	maintenance.md
surreal ml <sub>	SurrealML モデルをインポート／エクスポートする	maintenance.md

surreal validate（SurrealQL ファイルのチェック）とフォーマットについては、surrealql スキルで扱います。新しいサブコマンド（mcp、module）も存在します。インストール済みのバージョンで利用できるコマンドを確認するには、surreal help と surreal <command> --help を実行してください。

接続フラグと環境変数

sql、import、export、ml は共通の接続フラグを使用します。各フラグには SURREAL_* 環境変数による代替指定があり、明示的なフラグが優先されます。

フラグ（エイリアス）	環境変数	補足
-e, --endpoint	—	sql では ws://localhost:8000、import／export では http://localhost:8000
--namespace（--ns）	SURREAL_NAMESPACE	import／export／ml では必須
--database（--db）	SURREAL_DATABASE	import／export／ml では必須
-u, --username（--user）	SURREAL_USER
-p, --password（--pass）	SURREAL_PASS
-t, --token	SURREAL_TOKEN	JWT。ユーザー名／パスワードの代わりに使用
--auth-level	SURREAL_AUTH_LEVEL	root（デフォルト）、namespace／ns、または database／db

シークレットはフラグではなく環境変数で渡してください。シェルの履歴やプロセス一覧に漏れるのを防げます。

クイックスタート

# 1. Start an authenticated in-memory server (foreground)
surreal start --user root --pass root memory

# 2. In another shell, open the SQL REPL on namespace/database "main"
surreal sql --endpoint ws://localhost:8000 \
  --user root --pass root --ns main --db main --pretty

# 3. Load a dump into that database
surreal import --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main backup.surql

ルールと慣例

• 認証はデフォルトで有効です。 surreal start では --user／--pass が必要です。使い捨てのローカルインスタンスでのみ --unauthenticated を使用してください。
• ストレージバックエンドは意図的に選択してください。 memory（デフォルト）は一時的なもので、終了するとデータは消失します。永続化には rocksdb:／surrealkv://、分散クラスターには tikv:// を使用してください。start.md を参照してください。
• エクスポートのデフォルト出力先は標準出力です。 surreal export はファイルパスを指定しない限り -（標準出力）に書き込みます。必要に応じてリダイレクトまたはパイプしてください。
• CI では is-ready を使って準備状態を確認してください。 サーバーが接続を受け付けるまで、ゼロ以外の終了コードを返します。ヘルスチェックやスクリプトに最適です。
• メジャーアップグレード後、サーバーから互換性のないストレージバージョンが報告された場合は、fix を実行してください。 start で使用したものと同じ PATH を指定します。
• CLI は進化し続けています。 インストール済みバージョンの surreal <command> --help で、フラグとサブコマンドを確認してください。このスキルは v3.x を対象としています。

リファレンス

• サーバーの実行とストレージバックエンド — references/start.md
• 対話形式のクエリとパイプ経由のクエリ — references/sql.md
• データのインポートとエクスポート — references/import-export.md
• バージョン管理、アップグレード、準備状態、修復、ML モデル — references/maintenance.md