开始使用

添加 SDK，
然后创建数据库。

受支持的应用 crate 是 netbadb-sdk。默认特性为 embedded。仅使用 Protocol v1 客户端时，请关闭默认特性并启用 remote。工具链 1.97.1；MSRV 1.85.0。

1. 添加依赖

该 crate 来自工作区仓库。Cargo 会在该 git workspace 中解析名为 netbadb-sdk 的包。

[dependencies]
netbadb-sdk = { git = "https://github.com/sskycn/netbadb" }

[dependencies]
netbadb-sdk = { git = "https://github.com/sskycn/netbadb", default-features = false, features = ["remote"] }

2. 嵌入式创建、插入与查询

Database::create 拒绝覆盖已有数据库或 WAL 槽。insert 与 execute 作为隐式事务运行。create_index 回填当前行并注册非唯一单列索引。analyze 写入新的优化器快照；DML 不会自动刷新该快照。

use netbadb_sdk::{
    ColumnDef, ColumnId, Database, DatabaseError, PhysicalType, ScalarValue, TableDef, TableId,
    TypeSpec,
};

fn users() -> TableDef {
    TableDef::new(
        TableId(1),
        "users",
        vec![
            ColumnDef::new(
                ColumnId(1),
                "id",
                TypeSpec::Semantic {
                    name: "UserId".into(),
                    physical: PhysicalType::UInt64,
                },
            ),
            ColumnDef::new(ColumnId(2), "name", TypeSpec::Physical(PhysicalType::Text)),
        ],
    )
}

fn main() -> Result<(), DatabaseError> {
    let mut database = Database::create("users.db", users())?;
    database.insert(&[
        ScalarValue::UInt64(1),
        ScalarValue::Text("Ada".into()),
    ])?;
    database.create_index(TableId(1), ColumnId(1))?;
    database.analyze(TableId(1))?;
    let _rows = database.query("SELECT id, name FROM users WHERE id = 1")?;
    database.close()
}

3. 检查目录与计划

检查会编译并规划语句，但不会执行。它不会扫描堆、刷新 ANALYZE、获取写者或追加 WAL。

use netbadb_sdk::inspection;

let catalog = database.inspect_catalog()?;
println!("{}", inspection::render_catalog(&catalog));

let statement = database.inspect_statement(
    "SELECT id FROM users WHERE id = 1",
)?;
println!("{}", inspection::render_statement(&statement));

4. 启动 netbadbd

服务器打开部署清单 v4 声明的已有堆文件。回环明文要求恰好一个 local_plaintext 主体。非回环监听要求双向 TLS。

{
  "version": 4,
  "listen": "127.0.0.1:7878",
  "authorization": {
    "local_plaintext": {
      "tables": [
        { "table_id": 1, "read": true, "write": true, "transaction": true, "analyze": true }
      ]
    },
    "clients": []
  },
  "tables": [
    {
      "path": "users.db",
      "id": 1,
      "name": "users",
      "columns": [
        { "id": 1, "name": "id", "physical_type": "uint64", "semantic_type": "UserId", "nullable": false },
        { "id": 2, "name": "name", "physical_type": "text", "nullable": false }
      ]
    }
  ]
}

cargo run -p netbadbd -- --manifest server.json

5. 连接远程客户端

仅当解析后的 TCP 对端为回环地址时才接受明文。远程部署要求经过校验的双向 TLS。不提供连接池、自动重试或多路复用。

use netbadb_sdk::remote;

let mut client = remote::Client::connect(
    remote::Config::new("127.0.0.1:7878"),
)?;
client.ping()?;
let mut rows = client.query("SELECT id, name FROM users ORDER BY id")?;
while let Some(values) = rows.next_row()? {
    println!("{values:?}");
}

6. 使用命令行检查文件

请先停止 netbadbd 以及任何使用同一文件的嵌入式进程。CLI 通过正常启动恢复打开表，并且不会执行被检查的 SQL。

cargo run -p netbadb -- inspect catalog --manifest server.json

cargo run -p netbadb -- inspect statement \
  --manifest server.json \
  --sql "SELECT id FROM users WHERE id = 1"

Go 客户端

Go 模块是独立的 Protocol v1 客户端，不使用 cgo 或 Rust FFI。Dial 会自动完成 Hello。

client, err := netbadb.Dial(ctx, netbadb.Config{
    Address: "localhost:7878",
})
if err != nil { /* handle */ }
defer client.Close()

rows, err := client.Query(ctx, "SELECT id, name FROM users ORDER BY id")

从源码构建

git clone https://github.com/sskycn/netbadb.git
cd netbadb
make test

运行约束

每个打开的数据库对象允许一个写者。只读事务不预定写者。
读者不隔离，可能观察到活动写者的缓冲修改。
成功的提交表示 Commit 记录已持久化；堆页可能仍留在缓冲中，直到 flush 或 close。
不提供 SQL 索引 DDL。请通过嵌入式 API 调用 create_index。
不支持跨表写事务。
实验性磁盘格式会拒绝旧版本，不提供迁移路径。

许可

NetbaDB 以 AGPL-3.0-or-later 授权。如果修改程序并让用户通过网络与之交互，必须提供对应源代码。

添加 SDK，然后创建数据库。