Basalt

Basalt は、Rust で一から構築された組み込み SQL データベースおよびコマンドラインアプリケーションです。小規模なライブラリ API、対話型シェル、永続ストレージ、スナップショット分離トランザクション、クラッシュリカバリー、ポータブルな構造化データワークスペース、ローカル AI エージェント向けの stdio MCP サーバーを提供します。SQLite 互換の代替品でも、ホスト型データベースでもありません。

特長

• 式、結合、グループ化、集約、エイリアス、トランザクション文に対応した SQL 字句解析器と再帰下降構文解析器。
• 主キー、UNIQUE、およびユーザー作成インデックスを備えた、アトミックな文の実行。
• 楽観的競合検出を備えた、スナップショット分離トランザクション。
• プロセスのクラッシュ後にコミット済み状態を復元する、チェックサム付きページスナップショットと先行書き込みログ。
• テーブルスキャン、等価インデックス、範囲インデックスを使ったシンプルなクエリプランニング。
• テーブル、CSV、JSON Lines 形式での対話型およびスクリプト実行可能な CLI 出力。
• バージョン管理されたメタデータと、アトミックな CSV、JSON/JSONL、SQL ダンプのインポート／エクスポートに対応したポータブルなワークスペース。
• 型付き SQL ツール、上限付きワークスペースのインポート／エクスポート、エンジンによる制約付き SQL、スキーマリソース、復元可能なエージェント変更を備えた、インストール可能な MCP サーバー。

インストール

Cargo でインストールするには、Rust 1.88 以降が必要です。

cargo install basalt-db --locked

公開パッケージの名前は basalt-db ですが、インストールされるコマンド名は basalt のままです。現在のチェックアウトをインストールするには、cargo install --path . --locked を使用してください。

タグ付きリリースには、チェックサム付きインストーラーと、Linux、macOS、Windows 向けのビルド済みバイナリが含まれています。ツールチェーン不要の最新インストール方法については、GitHub Releases をご覧ください。最新のタグ付きリリースは、公開済みインストーラーとそのチェックサムを使って検証されています。

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yoshiii-xyz/basalt/releases/latest/download/basalt-db-installer.sh | sh

チェックアウトから直接実行するには、次のようにします。

cargo run --release -- app.basalt

クイックスタート

データベースを開いて、対話形式で SQL を実行します。

$ basalt app.basalt
basalt> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
basalt> INSERT INTO users VALUES (1, 'Ada');
basalt> SELECT * FROM users;
id | name
---+-----
1  | Ada
1 row(s)

1 回だけ実行するコマンドの場合：

basalt --json --command "SELECT * FROM users ORDER BY id;" app.basalt

一時的なデータベースには Database::in_memory() を使用します。永続的な書き込みはすぐに WAL に追記されます。現在の状態をスナップショットに統合し、古い WAL フレームを消去するには、checkpoint() を呼び出してください。永続パスを使用できるのは一度に 1 つのプロセスだけです。クローンされた Database ハンドルは、スレッド間で同じ所有者を安全に共有します。一方、2 つ目のプロセスには「すでに開かれています」というエラーが返されます。

ワークスペース

エージェントやスクリプトが、CSV、JSON、ログ、課題のエクスポート、またはフィクスチャ用に、使い捨てのローカルなリレーショナル領域を必要とする場合は、ワークスペースを使用してください。

basalt init .basalt-workspace
basalt workspace import --table issues .basalt-workspace issues.csv
basalt workspace inspect --json .basalt-workspace
basalt workspace query --json .basalt-workspace "SELECT * FROM issues ORDER BY id"
basalt workspace export .basalt-workspace issues issues.jsonl

インポートはアトミックで復元可能であり、永続的な change_id を返します。エクスポートは決定論的です。エージェントやスクリプトが機械可読な操作レポートを必要とする場合は、ワークスペースのインポート／エクスポートコマンドに --json を追加してください。- への生のエクスポートは、クリーンなデータストリームのままです。以降の書き込みはプレビューでき、正確なプラン ID を指定して適用できるほか、履歴で確認したり、スキーマと行の変更件数を含めて差分を比較したり、最新の変更であれば取り消したりできます。ワークスペースを開いている間は、1 つの Basalt プロセスがそのワークスペースを所有します。そのため、CLI からそのワークスペースを使用する場合や、data.basalt ファイルを直接開く場合は、先にワークスペース MCP サーバーを停止してください。形式と境界については、docs/workspaces.md を参照してください。

エージェントが所有するデータに Basalt を使用する理由は、書き込みの境界にあります。提案された変更を永続化する前に確認し、レビュー済みの正確なプランのみを適用して、必要に応じて最新の変更を差分比較または取り消します。

basalt workspace preview --json .basalt-workspace \
  "UPDATE issues SET status = 'closed' WHERE id = 42"
# Review the returned plan_id, then:
basalt workspace apply --json .basalt-workspace PLAN_ID
# Review the returned change_id, then:
basalt workspace diff --json .basalt-workspace CHANGE_ID
basalt workspace undo --json .basalt-workspace CHANGE_ID

互換性や分析性能が必要な場合は、SQLite または DuckDB を使用してください。Basalt は、既存のデータベースを置き換えることより、範囲が限定され復元可能な書き込みを重視するローカルの構造化データ作業向けです。

この説明がワークフローに当てはまる場合は、機密情報を含まない使い捨ての入力を使って早期ユーザー検証ガイドに従い、具体的なタスクと障害要因を記録してください。開発者が普段使用しているツールでこのワークフローを完了するまでは、Basalt は導入済みとは見なしません。

MCP サーバー

Basalt は、stdio 経由でローカルのModel Context Protocolサーバーとして実行できます。このチェックアウトからバイナリをインストールします。

cargo install --path . --locked

次に、絶対パスのワークスペースを指定して MCP ホストを設定します。ワークスペースモードは、データアクセスの範囲を限定し、書き込みに明示的なプレビュー／適用のライフサイクルを求めるため、推奨されるエージェント統合方式です。

{
  "mcpServers": {
    "basalt": {
      "command": "basalt",
      "args": [
        "mcp",
        "--workspace",
        "/absolute/path/to/project-data",
        "--init-workspace"
      ]
    }
  }
}

--init-workspace は、指定したパスが存在しない場合に限り、設定済みのワークスペースを作成します。既存のディレクトリやマニフェストを置き換えることはありません。ワークスペースを別途プロビジョニングする必要がある場合は、省略してください。ワークスペースのプラン適用と変更の取り消しに対して、ホストに明示的なオペレーター承認ポリシーがある場合に限り、"--allow-writes" を追加してください。直接データベースモードも引き続き利用でき、"args": ["mcp", "/absolute/path/to/app.basalt"] で指定できますが、デフォルトでは読み取り専用です。execute と checkpoint には同じフラグが必要です。一時的な直接モードのセッションには、"args": ["mcp", ":memory:"] を使用してください。ホストの設定にはインストール済みのバイナリを推奨しますが、チェックアウトから cargo run --quiet -- mcp --workspace /absolute/path/to/project-data を実行することもできます。

最新の MCP ホストがフォームによる入力要求に対応している場合、Basalt はワークスペースの各インポート、適用、取り消しの前に input_required 承認リクエストを返し、ホストが明示的な承認を付けて再試行した後にのみ実行します。初期化済みのレガシーホストには elicitation/create が送信されます。入力要求を通知しないホストでは、起動ポリシーとして明示的な --allow-writes を使用します。

リリースメタデータには、MCP Registry の掲載に使用される、表示可能な Cargo 所有権マーカーが含まれています。

• MCP Registry の所有権マーカー：mcp-name: io.github.yoshiii-xyz/basalt
• 公開済みの掲載情報：io.github.yoshiii-xyz/basalt

ワークスペースモードでは、workspace_import、workspace_inspect、workspace_preview、workspace_plan、workspace_apply、workspace_history、workspace_diff、workspace_undo、workspace_export と、範囲が限定された query、list_tables、describe_table ツールを利用できます。また、現在のスキーマを basalt://schema で公開します。完全なツールの仕様、設定の詳細、承認の境界、トラブルシューティングについては、docs/mcp.md を参照してください。

CLI

SQL ファイルを実行します。

basalt --file schema-and-seed.sql app.basalt

複数のコマンドにまたがるトランザクションを含め、1 つの接続でコマンドを順番に実行します。

basalt --command "BEGIN;" --command "INSERT INTO users VALUES (2, 'Grace');" --command "COMMIT;" app.basalt

--file - を使用すると、標準入力から SQL を読み込みます。必要に応じて --command と --file を繰り返し指定できます。指定した順序で実行されます。テーブル形式の出力は人が読みやすい形式で、CSV はクエリの行を出力し、--json はステートメントごとに 1 つの JSON オブジェクトを出力します。シェル内で .help を実行すると、.tables、.schema、.mode、.headers、.checkpoint、.show、.clear を確認できます。各 CLI の SQL 操作と保留中の対話型バッファーは 16 MiB に制限されています。これを超えるスクリプトは、より小さな操作に分割するか、上限のあるワークスペースのインポート形式を使用してください。

ライブラリの使用方法

use basalt::{Database, db::StatementResult};

let database = Database::open("example.basalt")?;
database.execute_sql(
    "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL); INSERT INTO users VALUES (1, 'Ada');",
)?;
let result = database.execute_sql("SELECT * FROM users WHERE id = 1")?;
assert!(matches!(result[0], StatementResult::Select { .. }));
database.checkpoint()?;
# Ok::<(), basalt::db::DbError>(())

SQL のトランザクションステートメントを複数回の呼び出しにまたがって実行する必要がある場合は、database.connect() を使用してください。

プロジェクト構成

パス	用途
src/sql/	レキサー、パーサー、AST、SQL 方言
src/engine.rs	ステートメントの実行とクエリのセマンティクス
src/planner.rs	アクセスパスの選択
src/db.rs, src/database.rs	テーブル、制約、トランザクション、API
src/storage.rs, src/wal.rs	スナップショット、チェックサム、復旧
src/cli.rs	対話型およびスクリプト対応のコマンドラインフロントエンド
src/workspace.rs	ローカルワークスペースのライフサイクルとデータ交換
src/mcp.rs	標準入出力 MCP サーバー、エージェントツール、スキーマリソース
server.json	MCP Registry のリリースメタデータ
docs/sql.md	サポート対象の SQL 方言とトランザクションのセマンティクス
docs/benchmark-results.md	記録済みのワークフローベンチマークスナップショット
docs/compatibility.md	ファイル形式の境界と差分テストの方針
docs/production-readiness.md	技術的なリリース契約、制限、根拠資料
docs/early-user-validation.md	5 分間の切り替えテストとフィードバック用テンプレート
docs/fuzzing.md	パーサーと永続化のファジング手順
docs/mcp.md	MCP のインストール、設定、ツールの契約
docs/workspaces.md	ワークスペースの構成とインポート／エクスポートの契約
tests/	統合テストとクラッシュ復旧のテスト
benches/	インプロセスエンジンのスループットベンチマーク
scripts/benchmark_workspace.py	再現可能なワークフロー比較ハーネス
scripts/differential_sql.py	サポート対象サブセットの SQLite 差分チェック
scripts/mcp-smoke.py	インストール済みバイナリの書き込み可能な MCP スモークテスト
scripts/verify-release-artifacts.py	リリースアーカイブのチェックサムと内容の確認
scripts/verify-registry-metadata.py	MCP Registry のパッケージ／バージョン整合性チェック
scripts/release-check.sh	パッケージ化したクレートとリリース前の確認
scripts/smoke-test.sh	インストール済みバイナリの CLI と読み取り専用 MCP のスモークテスト
fuzz/	オプションの libFuzzer パーサーおよびスナップショットターゲット

開発

cargo fmt --all -- --check
cargo check --all-targets --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-targets --locked
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
cargo bench --bench throughput
cargo package --locked
cargo build --release --locked
cargo audit
python3 scripts/benchmark_workspace.py --basalt target/release/basalt

Unix での完全なリリース前確認には、次を使用してください。

bash scripts/release-check.sh

このコマンドは、パッケージ化したクレートそのものを一時的なプレフィックスにインストールし、インストール済みバイナリのスモークテストを実行します。また、利用可能な場合は cargo audit と dist plan も実行します。

貢献ガイドラインについてはCONTRIBUTING.mdを、プロジェクトの履歴についてはCHANGELOG.mdを参照してください。リリースチェックリストはdocs/release.mdにあります。生成されるリリースワークフローとクリーンバイナリのスモークテストも記載されています。

ライセンス

MIT。LICENSEを参照してください。