Basalt

Basalt 是一款从零开始用 Rust 构建的嵌入式 SQL 数据库和命令行应用。它提供小型库 API、交互式 shell、持久化存储、快照隔离事务、崩溃恢复、可移植的结构化数据工作区，以及面向本地 AI Agent 的 stdio MCP 服务。它并非兼容 SQLite 的替代品，也不是托管数据库。

亮点

• SQL 词法分析器和递归下降解析器，支持表达式、联接、分组、聚合、别名和事务语句。
• 原子语句执行，支持主键、UNIQUE 和用户创建的索引。
• 采用乐观冲突检测的快照隔离事务。
• 带校验和的页面快照和预写日志，可在进程崩溃后恢复已提交状态。
• 简易查询规划，支持表扫描、等值索引和范围索引。
• 交互式且可编写脚本的 CLI 输出，支持表格、CSV 和 JSON 行格式。
• 可移植工作区，具有版本化元数据，并支持原子导入/导出 CSV、JSON/JSONL 和 SQL 转储。
• 可安装的 MCP 服务，提供类型化 SQL 工具、受限的工作区导入和导出、引擎限制的 SQL、架构资源，以及可恢复的 Agent 更改。

安装

使用 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)

运行一次性命令：

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

使用 Database::in_memory() 创建临时数据库。持久化写入会立即追加到 WAL；调用 checkpoint() 可将当前状态合并到快照中并清除旧的 WAL 帧。持久化路径一次只能由一个进程拥有；克隆的 Database 句柄可在线程间安全地共享该所有权，而第二个进程会收到“已打开”的错误。

工作区

当 Agent 或脚本需要一个可随时丢弃的本地关系型工作区来处理 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；导出结果具有确定性。当 Agent 或脚本需要机器可读的操作报告时，可为工作区导入／导出命令添加 --json；导出到 - 的原始数据仍会保持为纯净的数据流。之后的写入可以预览、按精确的计划 ID 应用、在历史记录中检查、通过架构和行变更计数进行差异比较，并在最新变更仍有效时撤销。工作区打开期间由一个 Basalt 进程独占，因此从命令行使用该工作区或直接打开其 data.basalt 文件之前，请先停止工作区 MCP 服务。有关格式和边界，请参阅 docs/workspaces.md。

在 Agent 所有的数据场景中使用 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 主机。工作区模式是推荐的 Agent 集成方式：它限定数据访问范围，并要求写入遵循明确的预览／应用生命周期。

{
  "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。

命令行

执行 SQL 文件：

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

在一个连接上按顺序运行命令，包括跨多个命令的事务：

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

使用 --file - 从标准输入读取 SQL。按需重复使用 --command 和 --file；它们会按出现顺序执行。表格输出便于阅读，CSV 输出查询行，--json 则为每条语句输出一个 JSON 对象。在 shell 中运行 .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 服务、Agent 工具和架构资源
server.json	MCP Registry 发布元数据
docs/sql.md	支持的 SQL 方言和事务语义
docs/benchmark-results.md	已记录的工作流基准测试快照
docs/compatibility.md	文件格式边界和差分测试策略
docs/production-readiness.md	技术发布约定、限制和证据
docs/early-user-validation.md	五分钟切换测试和反馈模板
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	打包 crate 和发布前检查
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

它会将精确的打包 crate 安装到临时前缀，并运行已安装二进制文件的冒烟测试流程。如果相关工具可用，它还会运行 cargo audit 和 dist plan。

有关贡献指南，请参阅 CONTRIBUTING.md；有关项目历史，请参阅 CHANGELOG.md。发布检查清单位于 docs/release.md，其中包括生成的发布工作流和干净二进制文件冒烟测试。

许可证

MIT。请参阅 LICENSE。